配置参考

MushroomAgent 通过 ~/.MushroomAgent/config.yaml 进行配置。本文档记录所有配置段和字段。

配置按以下顺序加载：

1. MUSHROOM_ROOT/config/config.yaml（项目根目录）
2. ~/.MushroomAgent/config.yaml（本地覆盖）

本地设置会覆盖同名字段。

agent

Agent 身份和运行时设置。

agent:
  id: "local-agent"
  name: "LocalAgent"

字段	类型	默认值	说明
id	string	—	唯一 agent 标识
name	string	—	agent 显示名称
ephemeral_system_prompt	string	""	每轮临时指令（子 agent 使用）
skip_context_files	bool	false	跳过工作区上下文文件（AGENTS.md、SOUL.md、IDENTITY.md）
quiet_mode	bool	false	静默模式（子 agent 使用）

llm

LLM 提供商配置。

llm:
  api_type: "openai"
  api_key: "sk-..."
  base_url: "https://api.openai.com/v1"
  model: "gpt-5.2"
  temperature: 0.0
  max_completion_tokens: 4096
  stream: false
  timeout: 600
  proxy: ""

字段	类型	默认值	说明
api_type	string	—	提供商类型：openai、deepseek、anthropic、gemini 等
api_key	string	—	API 密钥（也可通过 LLM_API_KEY 环境变量设置）
base_url	string	—	API 端点地址
api_version	string	—	API 版本（Azure）
model	string	—	模型名称
temperature	float	0.0	采样温度
top_p	float	1.0	核采样
top_k	int	0	Top-k 采样
max_completion_tokens	int	4096	最大输出 token 数
stream	bool	false	启用流式响应
timeout	int	600	请求超时时间（秒）
proxy	string	—	代理地址（覆盖全局代理）

所有支持的提供商列表请参见 LLM Providers。

tools

工具开关和配置。

tools:
  read:
    enabled: true
  exec:
    enabled: true
    allowlist:
      - curl
      - python
      - python3
      - ls
      - rg
      - cat
      - pwd
    default_timeout: 120
    max_output_chars: 80000

字段	类型	默认值	说明
tools.exec.allowlist	list	[]	exec 允许执行的命令
tools.exec.default_timeout	int	1800	exec 命令默认超时（秒）
tools.exec.max_output_chars	int	200000	最大输出字符数
tools.read.enabled	bool	true	启用文件读取工具
tools.write.enabled	bool	true	启用文件写入工具
tools.web_fetch.enabled	bool	true	启用网页抓取工具
tools.web_fetch.timeout	int	20	网页抓取超时（秒）
tools.web_fetch.max_bytes	int	200000	最大抓取字节数
tools.api_request.enabled	bool	true	启用 API 请求工具
tools.process.enabled	bool	true	启用长时进程管理
tools.delegate_task.enabled	bool	false	启用任务委派（子 agent）
tools.delegate_task.max_depth	int	2	子 agent 最大嵌套深度
tools.delegate_task.max_iterations	int	20	每个子 agent 最大循环次数

可用工具：read、write、exec、web_fetch、api_request、process、delegate_task、manage_schedule、skip_voice_reply。

channels

平台渠道配置。

channels:
  feishu:
    enabled: false
    app_id: ""
    app_secret: ""
    verification_token: ""
    encrypt_key: ""
  discord:
    enabled: false
    bot_token: ""
  livekit:
    enabled: false
    url: ""
    api_key: ""
    api_secret: ""

字段	类型	默认值	说明
feishu.enabled	bool	false	启用飞书机器人
feishu.app_id	string	—	飞书应用 ID
feishu.app_secret	string	—	飞书应用密钥
feishu.verification_token	string	—	飞书验证 Token
feishu.encrypt_key	string	—	飞书加密 Key
discord.enabled	bool	false	启用 Discord 机器人
discord.bot_token	string	—	Discord Bot Token
livekit.enabled	bool	false	启用 LiveKit 语音
livekit.url	string	—	LiveKit 服务地址
livekit.api_key	string	—	LiveKit API Key
livekit.api_secret	string	—	LiveKit API Secret

tts

文本转语音配置。

tts:
  provider: "minimax"
  group_id: ""
  tts_url: "wss://api.minimax.io"
  tts_token: "YOUR_TTS_TOKEN"
  voice_id: "Chinese (Mandarin)_Warm_Bestie"

字段	类型	默认值	说明
provider	string	"minimax"	TTS 提供商
group_id	string	—	提供商 group ID
tts_url	string	—	TTS WebSocket 地址
tts_token	string	—	TTS 认证 Token
voice_id	string	—	音色 ID

realtime_llm

语音模式下的实时 LLM 配置。

realtime_llm:
  model: "gpt-realtime"
  api_key: "YOUR_REALTIME_API_KEY"

字段	类型	默认值	说明
model	string	"gpt-realtime"	实时模型名称
api_key	string	—	实时 API 密钥（未设置则回退到 llm.api_key）

skills

Skills 配置。

skills:
  enabled: true
  roots: []
  include_defaults: true
  explicit_only: false
  max_active: 3
  active: []
  allowlist: []
  blocklist: []
  inject_mode: "hybrid"
  summary_max_chars: 280
  content_max_chars: 2000
  refresh_interval: 300

字段	类型	默认值	说明
enabled	bool	true	启用 Skills 系统
roots	list	[]	额外的 skill 目录
include_defaults	bool	true	包含工作区 skills
explicit_only	bool	false	仅加载明确请求的 skills
max_active	int	3	最多同时激活的 skills 数量
active	list	[]	始终激活的 skill 名称列表
allowlist	list	[]	仅允许这些 skills
blocklist	list	[]	屏蔽这些 skills
inject_mode	string	"hybrid"	"summary"、"full" 或 "hybrid"
summary_max_chars	int	280	摘要最大字符数
content_max_chars	int	2000	加载完整内容时的最大字符数
refresh_interval	int	300	自动刷新间隔（秒）

workspace

工作区目录设置。

workspace:
  path: "/absolute/path/to/workspace"

字段	类型	默认值	说明
path	string	—	工作区目录路径
use_uid	bool	—	使用 UID 路径

memory

记忆和知识检索。

memory:
  context_top_k: 12
  chat_mp_top_k: 1
  knowledge_top_k: 2
  similar_threshold: 0.01
  knowledge_similar_threshold: 0.1

字段	类型	默认值	说明
context_top_k	int	12	上下文检索数量
chat_mp_top_k	int	1	聊天记忆检索数量
knowledge_top_k	int	2	知识检索数量
similar_threshold	float	0.01	上下文相似度阈值
knowledge_similar_threshold	float	0.1	知识相似度阈值

embedding

嵌入模型配置。

embedding:
  api_type: "openai"
  api_key: ""
  base_url: "https://api.openai.com/v1"
  model: "text-embedding-3-small"
  dimensions: 1536

字段	类型	默认值	说明
api_type	string	—	openai 或 dashscope
api_key	string	—	API 密钥
base_url	string	—	API 端点地址
model	string	—	嵌入模型名称
dimensions	int	1536	嵌入向量维度
embed_batch_size	int	—	批处理大小

scheduler

任务调度设置。

scheduler:
  execution_timeout_seconds: 300

字段	类型	默认值	说明
execution_timeout_seconds	float	300.0	计划任务最大执行时间（秒）
one_shot_retry_max_attempts	int	3	单次任务最大重试次数
error_auto_disable_threshold	int	3	连续错误多少次后自动禁用任务

heartbeat

周期性心跳检查，用于 agent 主动巡检。

heartbeat:
  enabled: true
  every_seconds: 300
  run_on_startup: false
  active_hours: []
  prompt: ""

字段	类型	默认值	说明
enabled	bool	true	启用周期性心跳
every_seconds	int	300	心跳间隔（秒）
run_on_startup	bool	false	启动时立即执行一次心跳
wake_coalesce_ms	int	250	唤醒事件的合并窗口（毫秒）
wake_retry_ms	int	1000	失败唤醒事件的重试间隔（毫秒）
ack_max_chars	int	300	心跳确认的最大字符数
conversation_ttl_seconds	int	0	对话非活跃 TTL（0 = 禁用）
timezone	string	""	活跃时段的时区（如 "Asia/Shanghai"）
active_hours	list	[]	限制心跳在此时段内（如 ["09:00-18:00"]）
prompt	string	—	自定义心跳 prompt（默认为内置 prompt）

server_auth

可选的服务端鉴权。

server_auth:
  type: "token"
  token: "your-auth-token"