Install

使用官方安装脚本安装 MushroomAgent。目前原生安装暂时仅支持 Linux 和 macOS。Windows 用户请先使用 WSL2。

MushroomAgent 可以作为单机 agent 独立运行，也可以部署成一个 agent 加多个 node 的分布式形态。agent 负责决策，node 负责信息收集和输出执行。

安装 agent（推荐先做）

在终端中运行：

curl -fsSL https://docs.kiwilightyear.com/install.sh | bash

agent 安装脚本会一步一步引导你完成安装。它会检查操作系统、尽量安装所需系统依赖、在缺少 uv 时自动安装 uv、下载 MushroomAgent、安装 Python 依赖、链接 mushroom-agent 命令，并运行 agent 初始化向导。它会准备环境；安装结束后需要手动启动 agent。

Tip

安装脚本需要交互式终端。请在正常终端里运行，不要在完全没有 /dev/tty 的 headless shell 中运行。

支持系统

系统	状态	说明
Linux	支持	Debian/Ubuntu、Fedora、CentOS/RHEL、Alpine、Arch 等发行版会尽量由安装脚本自动处理。
macOS	支持	如需可选系统包，安装脚本会使用 Homebrew。
Windows	暂不原生支持	请使用 WSL2，并在 WSL 内执行 Linux 安装命令。

agent 和 node 的区别

MushroomAgent 把“决策端”和“设备输入输出端”分开：

角色	负责什么	常用命令
`agent`	决策端。接收上下文，调用模型做判断，决定下一步要做什么，再把动作发出去。agent 可以单独存在，也可以作为服务端让多个 node 接入。	`mushroom-agent start`
`node`	设备端。负责收集语音、视频、文本、本地设备事件等信息并转发给 agent；agent 决策后，node 再执行返回的 action。action 可能是语音输出，也可能是机器人动作或其他设备能力。	`mushroom-agent node attach`

第一次安装时，通常先安装 agent。单独的 agent 已经可以完成本机聊天和本地 runtime。只有当这台机器或设备要接入另一个已经运行的 agent 时，才需要安装 node。

安装过程中

按安装脚本提示一步一步完成即可。默认推荐单机 agent 安装路径：

在运行 agent 的机器上执行 install.sh。
按提示选择依赖档位和运行模式。
初始化向导询问模型或服务商配置时，按你的实际 API 配置填写。
等待依赖安装和初始化完成。

默认文件位置：

路径	用途
`~/.mushroom_agent/app`	MushroomAgent 源码目录
`~/.mushroom_agent/config.yaml`	主配置文件
`~/.mushroom_agent/node.yaml`	本地 node 身份、远端接入和 builtin 能力设置
`~/.mushroom_agent/prompts/`	`SOUL.md`、`AGENTS.md`、`IDENTITY.md` 等 starter prompt 文件
`~/.mushroom_agent/skills/`	本地 skills 目录
`~/.local/bin/mushroom-agent`	安装脚本链接出的命令

如果安装脚本提示 ~/.local/bin 不在 PATH 中，把下面这行加入你的 shell 配置，然后重新打开终端：

export PATH="$HOME/.local/bin:$PATH"

启动 MushroomAgent

以 agent 模式安装完成后，用下面的命令启动：

mushroom-agent start

这会在同一台机器上启动 agent 端和本地 runtime。agent 端可以单独使用，不一定需要额外 node。

然后在浏览器中打开本地 UI：

http://127.0.0.1:7860/web

如果只想启动服务/API 路径和浏览器 UI，不想把当前机器作为本地 runtime 接入，可以使用：

mushroom-agent serve --ui

本地开发环境如果没有配置 Langfuse auth，可以先设置：

export MUSHROOM_SKIP_LANGFUSE_AUTH=1

从源码或 pip 安装

仓库开发使用：

git clone https://github.com/kiwi-data/mushroomAgent.git
cd mushroomAgent
uv sync --extra full
source .venv/bin/activate
mushroom-agent init --run-mode text

源码开发的依赖集合：

目标	命令
纯文本开发	`uv sync`
语音开发	`uv sync --extra voice`
完整开发	`uv sync --extra full`
不安装 dev 依赖的完整运行时	`uv sync --no-dev --extra full`

如果只需要打包后的 CLI 入口，可以安装：

pip install mushroom-cli

高级安装选项

大多数用户直接运行一行安装命令即可。如果需要自定义安装参数，可以通过 bash -s -- 传给安装脚本：

curl -fsSL https://docs.kiwilightyear.com/install.sh | bash -s -- --extras minimal

install.sh 常用参数：

参数	默认值	说明
`--dir PATH`	`$MUSHROOM_HOME/app`	源码安装目录
`--branch NAME`	`main`	要安装的 Git 分支
`--extras NAME`	交互选择	依赖档位。可用值包括 `minimal`、`text`、`pure-text`、`none`、`voice`、`hardware`、`full`。`minimal` / `text` / `pure-text` / `none` 会安装文本档位；`voice` / `hardware` 会安装语音依赖。

常用环境变量：

变量	用途
`MUSHROOM_HOME`	数据/配置根目录，默认 `~/.mushroom_agent`
`MUSHROOM_INSTALL_DIR`	源码安装目录，默认 `$MUSHROOM_HOME/app`
`MUSHROOM_REPO_URL`	覆盖仓库 URL
`MUSHROOM_BRANCH`	覆盖 Git 分支
`MUSHROOM_PROXY`	可选出站代理

在另一台设备安装 node

node 使用独立安装脚本。它用于单独的机器或设备：把采集到的信息发给已有 agent，并执行 agent 返回的 action。它需要已有 agent server 和 access key。

先在 agent 主机上执行：

mushroom-agent accesskey create --name "Kitchen Pi" --node-id pi-kitchen
mushroom-agent serve --ui

再在 node 设备上执行：

curl -fsSL https://docs.kiwilightyear.com/install_node.sh | bash -s -- \
  --server-url ws://server-host:7860 \
  --access-key <accesskey> \
  --node-name "Kitchen Pi"

安装完成后，使用下面命令接入：

mushroom-agent node attach

node 安装脚本还支持 --proxy、--dir 和 --branch。也可以用 MUSHROOM_SERVER_URL、MUSHROOM_ACCESS_KEY、MUSHROOM_NODE_NAME、MUSHROOM_PROXY 环境变量代替参数。

卸载

如需清空 MUSHROOM_HOME（默认 ~/.mushroom_agent）下的本地数据/配置（保留目录本身），运行：

curl -fsSL https://docs.kiwilightyear.com/uninstall.sh | bash

卸载脚本需要交互式终端，并会要求你输入确认路径后才会删除数据。

常见问题

现象	可能原因	解决方法
`command not found: mushroom-agent`	`~/.local/bin` 不在 `PATH` 中	把 `export PATH="$HOME/.local/bin:$PATH"` 加到 shell 配置并重新打开终端
安装脚本提示系统不支持	原生安装目前仅支持 Linux/macOS	使用 Linux、macOS，或在 Windows 上使用 WSL2
安装脚本提示没有 tty	当前 shell 完全不可交互	在正常终端中重新运行安装命令
依赖安装失败	系统包或网络问题	修复包管理器或网络后重新运行安装脚本
7860 端口被占用	默认端口已有其他进程	关闭占用进程，或修改配置中的 server 端口

下一步

Getting Started

从安装到运行的最短路径。

CLI 参考

全部 MushroomAgent CLI 命令和选项。

故障排查

常见问题的解决方案。

安装 agent（推荐先做）​

支持系统​

agent 和 node 的区别​

安装过程中​

启动 MushroomAgent​

从源码或 pip 安装​

高级安装选项​

在另一台设备安装 node​

卸载​

常见问题​

下一步​