@fastagent/cli

@fastagent/cli 是 FastAgent 的公开命令行工具。你可以用它在本地运行 FastAgent、接入内置 IM 通道、安装 skills，并使用一组面向长会话和自动化场景的工程化能力，例如记忆、上下文压缩、任务调度和 sandbox 路由。 当前已 IM 通道包括完整的微信入站媒体处理、保守型非终态反馈、/resume 挂起恢复，以及会话内 cron / send_im_media 这类可主动回发 IM 的能力。

注意：npm 安装得到的是一个干净的 CLI/runtime 运行面，默认不预装任何 skills，也不捆绑任何第三方 MCP server / tool。内置 IM 通道和 CLI 自带能力可以直接使用；如果你需要额外的 skills 或 MCP 集成，需要在安装后自行添加或配置。

它适合这些场景：

• 把 FastAgent 作为本地 CLI agent 使用，通过ACP协议实现各类客户端。
• 通过内置 IM 通道把 FastAgent 跑成 IM 服务（内置微信接入）。

模型兼容：

• 支持 Kimi K2 (kimi-k2*) 和 Xiaomi MiMo (mimo-v2*) 家族模型的 OpenAI Chat Completions 兼容接口，在 thinking 多轮工具调用中保留并回放 assistant reasoning_content

能力概览

当前版本主要聚焦长会话和自动化场景下的工程化运行能力：

• 文件读取、写入和编辑（read/write/edit）
• 文件搜索与内容搜索（glob/grep）
• 命令执行与进程管理（bash/powershell）
• MCP 工具接入与 MCP 资源读取
• skills 安装、发现和调用
• 记忆：从 project / user 记忆目录召回可复用的长期信息，并在稳定回合后沉淀新的记忆
• Dream: 记忆整理，以及后台 auto-dream 记忆巩固 (支持手动/dream)
• 上下文压缩：长会话自动压缩历史上下文
• 定时任务（cron）：会话级持久化定时调度
• 计划清单：管理会话内的任务列表（task_**）
• 后台任务控制：查看、等待和停止子智能体 / 后台运行任务
• IM runtime：微信扫码登录、图片入模、语音转写复用、文件/视频持久化、typing状态、/resume 恢复、文件推送、会话内 cron 主动回发
• local / remote sandbox 运行模式

这些能力很多会在运行时自动生效，当前并不都会以独立子命令的形式直接暴露。

安装

npm install -g @fastagent/cli

安装完成后可直接使用：

fastagent --help
fastagent doctor

可用命令

fastagent
fastagent --channel weixin
fastagent --channel weixin --config ./fastagent.config.json
fastagent --channel weixin --output jsonl
fastagent --channel weixin --sandbox local
fastagent --channel weixin --sandbox remote --sandbox-url http://127.0.0.1:8788
fastagent config
fastagent doctor
fastagent doctor --config ./fastagent.config.json
fastagent skills add <source>
fastagent skills list
fastagent mcp list

当前 fastagent 裸命令默认显示帮助信息；如果你想直接启动一个可工作的服务入口，优先从 IM 通道开始。

Runtime Config File

runtime 命令和 doctor 支持显式 JSON 配置文件：

fastagent --channel weixin --config ./fastagent.config.json
fastagent doctor --config ./fastagent.config.json

• 只有显式传入 --config <path> 时才会读取配置文件。
• 优先级固定为 命令行参数 > 配置文件 > 环境变量。
• fastagent --config ... 裸命令会报固定错误；--config 当前必须和 runtime 命令或 doctor 一起使用。
• fastagent --channel weixin --config ... 会读取 gateway、sandbox、engine、imGateway；fastagent doctor --config ... 只诊断 sandbox.launcher
• IM 运行时预算走统一 owner： gateway.requestTimeoutMs/maxRetries、 engine.turnTimeoutMs/toolExecutionTimeoutMs、 imGateway.stallTimeoutMs
• sandbox 整段都是可选的；只有 remote sandbox 需要从配置文件注入地址/API key，或 local sandbox 需要自定义 launcher 时才需要填写
• sandbox.workspaceMode=host-bind 只支持 --sandbox local。如果没有设置 sandbox.hostWorkspaceRoot，IM 命令会默认使用 imGateway.workspaceDir 作为执行根。
• 当前配置示例文件是 examples/fastagent.config.example.json

OpenAI Responses supportsPreviousResponse 说明

作用：

• 用于控制 openai-responses provider 是否走 previous_response_id anchored replay
• 不设置时，保持 auto 语义：CLI/IM 不显式下发该字段，交给 gateway 按 provider host 自动判断
• 设为 true 时，显式开启该 provider 的 stateful replay
• 设为 false 时，强制 full transcript replay

配置位置：

• fastagent.config.json.gateway.supportsPreviousResponse
• FASTAGENT_SUPPORTS_PREVIOUS_RESPONSE=true|false

补充：

• 示例里写成 false 只是保守配置示例，不代表运行时默认值
• 官方 host 在未显式关闭时默认开启
• 非官方 openai-responses host 在未显式开启时默认走 full transcript replay
• 如果设置了 FASTAGENT_SUPPORTS_PREVIOUS_RESPONSE，值必须是 true|false|1|0；非法值会在 CLI runtime config 解析阶段直接报错

模型切换兼容性提示：

• supportsPreviousResponse 只控制 openai-responses provider 是否走 previous_response_id replay，不代表任意模型历史都能无损复用。
• 某些模型族有自己的 continuation 要求。当前已支持 kimi-k2* 和 mimo-v2* 家族模型：当 thinking 开启且进入多步 tool loop 时，后续请求需要保留 assistant turn 里的 reasoning_content。
• 因此，同一会话里如果从别的模型族切到 Kimi K2 / Xiaomi MiMo 家族模型，而旧历史里又包含工具调用链路，可能会因为缺少目标模型所需 continuation 而要求新会话或 /reset；纯文本历史通常更容易兼容。

默认 Thinking Level：

• engine.defaultThinkingLevel 和 FASTAGENT_DEFAULT_THINKING_LEVEL 用来控制 engine 默认推理强度，合法值是 off|minimal|low|medium|high|xhigh
• CLI 会把这个值同时投影到 ACP runtime options 和 IM env snapshot
• 如果你准备把默认模型切到 kimi-k2* 或 mimo-v2* 家族模型，又希望尽量避开 thinking continuation 历史要求，可以把默认值设成 off

示例最小配置（IM 通道运行）：

{
  "gateway": {
    "provider": "openai",
    "model": "gpt-5.4",
    "apiType": "openai-responses",
    "baseUrl": "https://api.openai.com/v1",
    "userAgent": "fastagent-cli-example",
    "apiKey": "<your-api-key>",
    "supportsPreviousResponse": false,
    "requestTimeoutMs": 60000,
    "maxRetries": 2
  },
  "sandbox": {
    "workspaceMode": "isolated"
  },
  "engine": {
    "defaultThinkingLevel": "medium",
    "turnTimeoutMs": 180000,
    "toolExecutionTimeoutMs": 120000
  },
  "imGateway": {
    "workspaceDir": "/abs/workspace",
    "agentId": "agent-weixin-dev",
    "dataDir": "/abs/fastagent",
    "stallTimeoutMs": 900000,
    "allowAllPermissions": true
  }
}

local sandbox 直接在 host 工作区执行：

{
  "sandbox": {
    "workspaceMode": "host-bind",
    "hostWorkspaceRoot": "/weixin-bot/workspace"
  },
  "imGateway": {
    "workspaceDir": "/weixin-bot/workspace"
  }
}

fastagent --channel weixin --sandbox local --config ./fastagent.config.json

IM Channel

当前公开提供的内置 IM 通道是微信 weixin。

你可以用它把 FastAgent 作为一个微信机器人运行，支持：

• 扫码登录
• 已有登录态恢复
• 入站图片进入模型上下文，作为真实 image prompt block 参与推理
• 入站语音复用微信已提供的转写文本，不额外执行本地 STT
• 入站文件 / 视频持久化保存，当前不直接送入模型
• 文本模式输出
• 媒体/文件出站（内置send_im_media等im专有工具）

启动前需要的环境变量（如果不显式使用配置文件，需要设置环境变量）

必填：

# 用户工作区（项目级）
export IM_GATEWAY_WORKSPACE_DIR=/weixin-bot/workspace
# 全局/用户级数据目录
export IM_GATEWAY_DATA_DIR=/weixin-bot/data
# AI名字可任意命名
export IM_GATEWAY_AGENT_ID=weixin-bot
# 默认允许全部权限
export IM_GATEWAY_ALLOW_ALL_PERMISSIONS=true

LLM 最小示例：

export FASTAGENT_PROVIDER=anthropic
export FASTAGENT_MODEL=claude-opus-4-6
export ANTHROPIC_API_KEY=<your-key>

常见可选项：

export FASTAGENT_API_KEY=<your-key>
export FASTAGENT_API_TYPE=openai-responses
export FASTAGENT_BASE_URL=https://api.openai.com/v1
export FASTAGENT_USER_AGENT=your-app-name
export FASTAGENT_SUPPORTS_PREVIOUS_RESPONSE=false

FASTAGENT_API_TYPE 当前支持这些值：

• anthropic-messages
• openai-completions
• openai-responses
• google-generative-ai

如果不显式设置，会按 FASTAGENT_PROVIDER 推断：

• anthropic -> anthropic-messages
• google / gemini / google-ai-studio -> google-generative-ai
• 其他 provider 默认回落到 openai-completions
• 不设置 FASTAGENT_SUPPORTS_PREVIOUS_RESPONSE 时，运行时保持 auto 语义，由 gateway 自动判断
• FASTAGENT_SUPPORTS_PREVIOUS_RESPONSE 只在 FASTAGENT_API_TYPE=openai-responses 时有意义；设为 true 显式启用 anchored replay，设为 false 强制 full transcript replay。
• FASTAGENT_SUPPORTS_PREVIOUS_RESPONSE 设为其他值时会直接报错，不会静默回退。

启动微信服务

fastagent --channel weixin

机器可读输出：

fastagent --channel weixin --output jsonl

远端 sandbox：

fastagent --channel weixin --sandbox remote --sandbox-url http://127.0.0.1:8788

使用 PM2 后台运行

如果你希望把 IM runtime 作为后台常驻服务托管，推荐使用 PM2。

先安装 PM2：

npm install -g pm2

建议通过 command -v fastagent 取得可执行文件绝对路径，并显式使用 --interpreter none。这样 PM2 会把 fastagent 当成可执行程序，而不是当前目录下的 Node.js 脚本来加载。

使用配置文件启动：

pm2 start "$(command -v fastagent)" --name fastagent-im --interpreter none -- --channel weixin --output jsonl --config ./fastagent.config.json

不使用配置文件时，也可以先导出必需环境变量，再启动：

export IM_GATEWAY_WORKSPACE_DIR=/weixin-bot/workspace
export IM_GATEWAY_DATA_DIR=/weixin-bot/data
export IM_GATEWAY_AGENT_ID=weixin-bot
export IM_GATEWAY_ALLOW_ALL_PERMISSIONS=true

pm2 start "$(command -v fastagent)" --name fastagent-im --interpreter none -- --channel weixin --output jsonl

常用管理命令：

pm2 logs fastagent-im
pm2 status
pm2 restart fastagent-im
pm2 restart fastagent-im --update-env
pm2 stop fastagent-im
pm2 delete fastagent-im
pm2 save

说明：

• fastagent-im 只是示例进程名，对应 --name fastagent-im；你可以按自己的部署场景改成任意更清晰的名字，例如 weixin-bot、fastagent-prod。
• -- 后面的参数会传给 fastagent；如果省略它，--channel、--output、--config 之类的参数可能会被 PM2 自己解析掉。
• 如果你修改的是 shell 环境变量而不是 --config 文件，重启时使用 pm2 restart fastagent-im --update-env 让新环境生效。

如果你要在 npm 安装态启用 --sandbox local，需要满足以下其一：

• 通过 FASTAGENT_SANDBOX_RUNTIME_BIN 和可选 FASTAGENT_SANDBOX_RUNTIME_ARGS 显式指定 launcher
• 单独安装 @fastagent/sandbox-runtime，让包提供 fastagent-sandbox
• 让 fastagent-sandbox 已经存在于 PATH 中

你也可以先运行：

fastagent doctor
fastagent doctor --config ./fastagent.config.json

当前 doctor 会按下面的顺序检查 local sandbox launcher discoverability：

• 不带 --config 时：FASTAGENT_SANDBOX_RUNTIME_BIN -> PATH fastagent-sandbox
• 带 --config <path> 时：config.sandbox.launcher -> env -> PATH
• 若两者都没有，会直接提示 companion package / env 的修复方式

Skills 命令

• fastagent skills add <source> 默认走 runtime 推断： repo-local 本地 source 会安装到当前 workspace 的 .fastagent/skills/<name>， 其他 source 默认安装到 runtime-global skill root <globalDataDir>/skills/<name>； 对普通 npm 安装且未显式覆盖时，通常是 ~/.fastagent/skills/<name>
• fastagent skills add <source> --scope project 强制安装到当前 workspace 的 .fastagent/skills/<name>
• fastagent skills add <source> --scope user 强制安装到 runtime-global skill root <globalDataDir>/skills/<name>； 对普通 npm 安装且未显式覆盖时，通常是 ~/.fastagent/skills/<name>
• fastagent skills add <source> --list 只列出候选 skill，不写磁盘
• fastagent skills list 默认同时列出 project + user 两个 scope 的已安装 skill，并按 scope 分组显示
• fastagent skills list --scope project|user 只列出单一 scope 的已安装 skill
• fastagent skills add 不再暴露 --yes；当前没有 CLI-owned confirmation flow

当前常见 source 形态：

• 本地路径：已有目录优先按本地 source 处理，包括 ./skills/demo-skill
• GitHub shorthand：owner/repo
• GitHub repo URL：https://github.com/<owner>/<repo>
• GitHub tree URL：https://github.com/<owner>/<repo>/tree/<ref> 或 .../tree/<ref>/skills/...

MCP 命令

• fastagent mcp list 列出 runtime-global settings.json.mcpServers 里的 MCP server。
• fastagent mcp add <name> --command <cmd> [--arg <arg>]... [--env KEY=VALUE]... 添加一个 runtime-global MCP server。
• fastagent mcp remove <name> 删除一个 runtime-global MCP server。
• 如果 fastagent mcp add 命中同名 server，CLI 会给出 1. Overwrite / 2. Exit 的显式选择， 不会静默覆盖现有配置。
• fastagent mcp list 只显示 env key，不回显 env value。

常见用例

fastagent --help
fastagent --version
fastagent --channel weixin
fastagent --channel weixin --output jsonl
fastagent --channel weixin --sandbox local
fastagent skills add owner/repo
fastagent skills add owner/repo --list
fastagent skills add ./skills/review-pr --scope project
fastagent skills list --scope user
fastagent mcp add search --command node --arg server.js --env API_KEY=secret
fastagent mcp remove search
fastagent config
fastagent doctor
fastagent skills list