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 初始化向导。
安装脚本需要交互式终端。请在正常终端里运行，不要在完全没有 /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/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/i/chat
高级安装选项
大多数用户直接运行一行安装命令即可。如果需要自定义安装参数，可以通过 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 | 交互选择 | 可选依赖档位（text、voice、full） |
在另一台设备安装 node
node 现在使用独立安装脚本。它用于单独的机器或设备：把采集到的信息发给已有 agent，并执行 agent 返回的 action。需要已有 agent server 和 access key：
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
卸载
如需清空 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 端口 |