跳到主要内容

配置参考

MushroomAgent 的本地运行时主要由 ~/.mushroom_agent/config.yaml 配置。mushroom-agent init 还会写入 ~/.mushroom_agent/node.yaml、prompt 文件、skills/log 目录，以及被 config.yaml 引用的本地 secrets sidecar。

配置按以下顺序加载：

  1. 项目根目录中的 MUSHROOM_ROOT/config/config.yaml
  2. 本地覆盖 ~/.mushroom_agent/config.yaml

本地设置会覆盖同名字段。生成的 starter 会尽量保持本地路径隐式：日志、prompt discovery、memory 存储、skills 和工具工作目录都会在运行时从本地根目录派生。

生成文件​

文件或目录用途
config.yamlagent、模型、tools、channel、voice、eval 和 skill 主配置
node.yamlnode 身份、远端接入设置和 builtin 设备能力
local secrets sidecarconfig.yaml 引用的 API keys 和 access keys；不要提交
prompts/IDENTITY.md标准身份和角色
prompts/SOUL.md人格和交互风格
prompts/AGENTS.md操作规则、项目约束和边界
prompts/APPROACH_GREETING.md摄像头接近事件的问候风格
skills/本地用户 skills
logs/运行日志

node.yaml​

node.yaml 包含 node 身份、远端连接设置，以及 builtin audio/video/speech/text 能力配置。

node:
  node_id: "auto-generated"
  node_name: "MyNode"
  remote:
    url: "ws://127.0.0.1:7860"
    access_key: "mushroom-local-accesskey"
    proxy: ""
    headers: {}
  builtin:
    audio_input:
      enabled: false
    video_input:
      enabled: false
    speech_output:
      enabled: false
    text_input:
      enabled: false

mushroom-agent start 使用 node.yaml 把当前机器作为本地 node runtime 接入。mushroom-agent node attach 也使用同一文件，把设备接入远端 mushroom-agent serve 主机。

小节用途
builtin.audio_input麦克风输入、codec、设备选择、本地 VAD、回声消除、降噪、debug recording
builtin.video_input摄像头输入、设备列表、帧尺寸、JPEG 质量、vision 设置、proximity observer、side-face gate
builtin.speech_output扬声器或流式输出、codec、RTSP/WebSocket 输出选项
builtin.text_input控制台文本输入

摄像头尺寸、JPEG 质量、近距检测和 side-face gate 设置位于 node.yaml 的 builtin video 配置中，不在 config.yaml 中。

agent​

agent:
  id: "local-agent"
  name: "LocalAgent"
  max_iterations: 90
字段说明
id稳定 agent 标识
name显示名称
max_iterationsthink/action 循环最大迭代数
ephemeral_system_prompt每轮临时指令，主要给 delegated sub-agents 使用
skip_context_files跳过 AGENTS.md、SOUL.md、IDENTITY.md 等 workspace context 文件
quiet_mode子 agent 或 quiet runs 中抑制非必要输出

llm​

llm:
  api_type: "openai"
  api_key: "${MUSHROOM_LLM_API_KEY}"
  base_url: "https://api.openai.com/v1"
  model: "gpt-5.5"
  reasoning: "medium"
  temperature: 0.2
  max_output_tokens: 4096
  timeout: 600

当前 init wizard 的文本 provider 是 openai、deepseek 和 qwen。语音模式主模型 provider 可选 OpenAI 或 Qwen，OpenAI realtime 模型由 realtime_llm 配置。

字段说明
api_typeprovider 类型，例如 openai、deepseek、qwen
api_keyAPI key 或 secrets-sidecar placeholder
base_urlprovider endpoint
model模型名
reasoningreasoning effort，例如 none、minimal、low、medium、high、xhigh
temperature采样温度
max_output_tokens最大输出 token 数
timeout请求超时时间，单位秒

模型/provider 详情见 LLM Providers。

embedding​

embedding:
  api_type: "openai"
  api_key: ""
  base_url: "https://qwen3-embed.kiwilightyear.com/v1"
  model: "Qwen3-Embedding-0.6B"
  embed_batch_size: 100
  dimensions: 1024

Embedding 用于 memory 和 retrieval。请确保向量维度与所选 embedding 模型一致。

server​

server:
  host: "0.0.0.0"
  port: 7860
  accesskeys: []

server.accesskeys 保存 hash 后的 accesskey records 和 previews。明文 accesskey 只会在 mushroom-agent init 或 mushroom-agent accesskey create 创建时打印一次。

mcp​

mcp:
  enabled: false
  servers: {}

MCP 默认关闭。只有在 mcp.servers 下添加 server definitions 后再启用。

tools​

Builtin tools 由 tools.* 配置加载。查看当前 runtime 实际可见工具：

mushroom-agent tools list
小节默认用途
skill_manageenabled在可写 skill roots 中创建或更新 skills
skill_viewenabled从可读 roots 查看 skills
readenabled读取文本和图片文件
execenabled执行 shell 命令
web_fetchenabled抓取 URL 和 HTTP 响应内容
web_searchenabled搜索网页
image_generationenabled通过配置的 provider 生成图片
video_generationdisabled通过 VolcEngine Ark 或 Google provider 设置生成视频
video_analyzedisabled通过 provider 设置分析视频
audio_analyzedisabled通过 provider 设置分析音频
attach_artifactenabled附加生成的 artifacts
processenabled管理较长时间运行的后台进程
memory_searchenabled搜索 agent memory
memory_add_fileenabled把本地文本/Markdown 文件加入 memory
manage_scheduleenabledschedule 管理
skip_voice_replydisabled语音模式中跳过 spoken reply 的辅助工具
emit_ui_commanddisabled在 voice/UI runtime 中发出 UI commands
update_identity_profilestarter 中 enabled更新身份档案数据
delegate_taskdisabled派生受限 child agents

当前默认 builtin registry 不注册独立的 write 或 api_request 工具。本地自动化使用 exec/process，网页访问使用 web_fetch/web_search，外部系统集成使用服务 API。

channels​

channels:
  feishu:
    enabled: false
    app_id: ""
    app_secret: ""
    verification_token: ""
    encrypt_key: ""
  discord:
    enabled: false
    bot_token: ""
  openim:
    enabled: false
  magiccampus:
    enabled: false
  livekit:
    enabled: false

Platform channels 会把外部聊天或媒体平台适配成 MushroomAgent 消息。直接通信 transports（http、websocket、func）通过 mushroom-agent serve --communications 选择，不在本小节中配置。

Voice 相关小节​

小节用途
stt语音转文本 provider 和行为
rtcrealtime voice 开关、录音、身份、VAD、中断行为
tts文本转语音 provider 和语音输出设置
realtime_llmrealtime voice 使用的实时 LLM 模型和 API key
rtc:
  enabled: false
  identity_enabled: false
  voice_mode: "realtime"
  vad_mode: "vad"
  allow_interruptions: true

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

当 rtc.enabled=false 时，普通 mushroom-agent serve --ui 和文本 WebSocket chat 不需要 TTS 或 realtime LLM credentials。

skills​

skills:
  enabled: true
  roots: []
  include_defaults: true
  include_bundled: true
  explicit_only: false
字段说明
enabled启用 skill discovery 和 injection
roots额外 skill root 目录
include_defaults包含默认本地 skills root
include_bundled包含官方 bundled skills
explicit_only仅加载用户/task 明确请求的 skills

self_improvement​

self_improvement:
  enabled: false
  skill:
    enabled: true
    post_turn_nudge: true
  skill_curator:
    enabled: true

Self-improvement 默认关闭。只有当你希望 agent 随时间建议、审查或整理 skills 时才启用。

dev.eval​

dev:
  eval:
    enabled: true
    max_concurrency: 1
    keep_runs: 20
    default_enable_judge: false
    case_timeout: 120

该配置控制 /i/dev/eval Eval Panel。用法和 token 成本见 Eval Panel。

安全更新配置​

  • 首次生成优先使用 mushroom-agent init。
  • 只有明确要覆盖生成文件时，才使用 mushroom-agent init --force。
  • 不要提交本地 secrets sidecars。
  • 远端设备 accesskey 使用 mushroom-agent accesskey create 创建，并立即保存明文。
  • 框架仓库中的 mushroom-cli/mushroom_cli/configs/local-config.template.yaml、local-node.template.yaml、local-builtin.template.yaml 是生成默认值的事实来源。