跳到主要内容

Troubleshooting

先排最常见的几类问题。

MushroomAgent: command not found​

先激活虚拟环境：

source .venv/bin/activate

Config file missing​

先执行：

mushroom-agent init

llm.api_key missing or placeholder​

更新配置中的真实密钥：

llm:
  api_key: "YOUR_REAL_API_KEY"

/i/chat cannot open​

先确认服务已启动：

export MUSHROOM_SKIP_LANGFUSE_AUTH=1
mushroom-agent start

然后访问：

http://127.0.0.1:7860/i/chat

Voice dependency errors​

如果启用了 voice preset，需要额外安装语音依赖：

pip install MushroomAgent-server MushroomAgent-core[voice]

如果你要启用 WebSocket 实时语音，再确认服务启用了 websocket 通信方式。

Config path confusion​

默认发现链如下：

  1. MUSHROOM_ROOT/config/config.yaml
  2. ~/.MushroomAgent/config.yaml

如果两份同时存在，本地 ~/.MushroomAgent/config.yaml 会覆盖前面的同名字段。