跳到主要内容

Getting Started

按以下步骤，几分钟内在本地把 MushroomAgent 跑起来。这是目前从安装到可工作的本地 agent 的最短支持路径，也会说明什么时候使用仅服务模式和 Node 模式。

第一次使用时，先按 agent 模式安装。agent 是决策端：它接收信息、调用模型、决定要执行什么 action，并且可以在一台机器上单独运行。只有当另一台设备需要为远端 agent 收集输入或执行输出时，才需要 node。

你需要什么​

  • Linux 或 macOS。Windows 用户请先使用 WSL2。
  • 正常的交互式终端
  • 可用的 LLM API Key

先安装 agent​

先把本地 agent 配好。你可以在下面两条路径里二选一：

  • 快速安装：适合大多数用户，路径最短。
  • 开发者模式：从源码安装，适合本地开发。

无论你选择哪条路径，完成后都可以用 mushroom-agent start 启动完整本地 runtime，或用 mushroom-agent serve --ui 只启动服务和浏览器 UI。

快速安装​

  1. 运行安装脚本

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

    安装脚本会检查系统、尽量安装缺失依赖、下载 MushroomAgent、链接 mushroom-agent 命令、安装 Python 依赖，并运行初始化向导。它会准备环境；安装结束后不会常驻一个 agent 服务。

  2. 按提示完成配置

    本地安装选择默认的 agent 模式。文本聊天选择 Pure text mode，然后按向导提示填写服务商、模型和 API key。

  3. 启动 agent

    mushroom-agent start

    浏览器打开 http://127.0.0.1:7860/web。

如果希望跳过依赖档位的交互选择，可以直接传 extras：

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

开发者模式​

如果你希望直接从源码开发，而不是使用一键安装脚本，可以按下面流程：

  1. 克隆源码仓库

    git clone https://github.com/kiwi-data/mushroomAgent.git
    cd mushroomAgent

  2. 安装完整开发依赖

    uv sync --extra full
    source .venv/bin/activate
    which mushroom-agent

    在执行 mushroom-agent 命令前，先确认返回结果中包含 .venv/bin/mushroom-agent。

  3. 初始化本地配置

    mushroom-agent init --run-mode text

    向导会写入 ~/.mushroom_agent/config.yaml、~/.mushroom_agent/node.yaml、本地 prompt 文件，以及本地 secrets sidecar。只有明确要覆盖已生成文件时，才使用 --force。

  4. 启动本地环境

    mushroom-agent start

    浏览器访问 http://127.0.0.1:7860/web。

Node 模式​

Node 模式用于单独的设备：这个设备负责为另一个已经运行的 agent 收集输入并执行输出。普通本地聊天不需要 Node 模式。

完成上面任一 agent 安装路径后，先为设备创建 access key，再配置 Node 模式。

node 会收集语音、视频、文本、本地设备事件等信息，然后转发给 agent。agent 根据信息做决策，再把要执行的 action 发回 node。action 可能是语音输出、界面操作、机器人动作，或其他设备特有能力。

先在 agent 主机上创建 access key 并启动服务：

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"

然后启动 node：

mushroom-agent node attach

语音模式​

语音相关配置可由安装脚本里的初始化向导生成。按提示选择语音模式，或在源码安装中显式初始化：

mushroom-agent init --run-mode voice

然后正常启动：

mushroom-agent start

语音模式可能需要额外系统包，以及 voice 或 full 依赖档位。

启动失败时​

如果 mushroom-agent start 因本地 auth 集成未配置而失败，可以先为本地测试关闭 Langfuse auth 再重试：

export MUSHROOM_SKIP_LANGFUSE_AUTH=1
mushroom-agent start

如果是已生成配置过旧，并且你确认要重新生成本地配置，再执行：

mushroom-agent init --force
mushroom-agent start

下一步​

文档导航

按主题浏览全部文档。

CLI 参考

了解 remote 模式和多设备接入方式。