AI Agent 安装指南

Forgexa 编排 13 个 AI 编码 Agent 集成，包含 DeepSeek Harness 开发者预览。平台支持不同：Harness 在 macOS 受构件门禁保护，Linux 要求 bubblewrap 与本机验收，原生 Windows 暂未开放。

每台 Runtime 至少安装 一种 Agent，认证仍留在本机。Harness 的运行配置是例外：Forgexa 管理独立运行 profile，并可只读引用操作者批准的认证文件，不复制或修改秘密。随后继续阅读《安装部署》。

受支持的 Agent 一览

#	Agent	CLI 命令	最低版本	路由方式	macOS	Linux	Windows
1	Claude Code	claude	2.0.0	自动	原生	原生	原生 / WSL2
2	OpenAI Codex	codex	0.147.0	自动	原生	原生	WSL2（推荐）
3	GitHub Copilot CLI	copilot	1.0.70	自动	原生	原生	原生
4	Gemini CLI	gemini	—	自动	原生	原生	原生
5	OpenCode	opencode	1.4.0	自动	原生	原生	原生（npm）/ WSL2
6	Kimi Code	kimi	0.18.0	自动	原生	原生	WSL2
7	MiMo Code	mimo	0.1.14	显式选择	原生	原生	WSL2
8	Qwen Code	qwen	0.24.1	显式选择	原生	原生	原生（npm）
9	CodeBuddy Code	codebuddy	2.156.0	显式选择	原生	原生	原生（npm）
10	Qoder CLI	qoder	1.1.59	显式选择	原生	原生	WSL2
11	TraeCode CLI	traecli	—	显式选择	原生	原生	WSL2
12	ZCode	zcode	—	显式选择	原生	原生	WSL2
13	DeepSeek Harness	dsh	精确 0.2.0-rc.2	显式选择	构件验收	bubblewrap + 本机验收	未开放

路由方式说明：

• 自动——六个标准候选。Forgexa 的 RouterAgent 可自动选用它们，并纳入后备链（例如某 Agent 触发限流时自动切换）。
• 显式选择——后七个。不参与自动路由与默认后备链。Harness 限于 Desktop 和个人 Runtime；策略中手工填写的 fallback 条目也属于显式启用。

为什么是这些最低版本？ 每个下限都只在有可验证证据表明 Forgexa 的集成依赖该版本引入的功能时才设置——并非随意填写：

Agent	版本下限	验证依据
Claude Code	2.0.0	Agent 模式设计的门禁要求：stream-json + --resume + 跳过权限确认的执行栈按 Claude Code 2.x 规格制定
Codex	0.147.0	在 0.147.0 上真机验证通过；0.125.0 的 npm 包 vendor 目录为空，无法运行
Copilot CLI	1.0.70	包含 AgentHost 所需的一次性鉴权持久化修复
OpenCode	1.4.0	--dangerously-skip-permissions（无头运行不能阻塞在交互式权限确认上）于 v1.4.0 引入；v1.2.27 已知与 Forgexa 不兼容
Kimi Code	0.18.0	裸 -p 的非交互自动批准（无需 --yolo）与当前磁盘上的 auth/session 存储布局均要求 0.18.0+
MiMo Code	0.1.14	mimo run --format json 协议与非交互权限标志于 0.1.14 引入
Qwen Code	0.24.1	经验证的 stream-json 事件信封与原生 --resume 支持
CodeBuddy	2.156.0	经验证的无头 stream-json 协议、原生 --resume 与 setting-source 隔离
Qoder CLI	1.1.59	经验证的无头 stream-json 协议、原生 --resume 与 setting-source 隔离
Gemini CLI	—	无硬性下限；L1 兼容级别
TraeCode CLI	—	无版本下限；就绪状态由真实账号 live gate 把关
ZCode	—	无版本下限；就绪状态由二进制指纹批准 + 协议验收把关
DeepSeek Harness	精确 0.2.0-rc.2	CLI、headless、base、扩展、Node 与平台指纹必须验收匹配

环境要求（全平台通用）

• Node.js ≥ 18（推荐 20 LTS）——npm 安装的 Agent 依赖它（claude、codex、copilot、gemini、qwen、codebuddy、opencode）。用 node --version 检查。
• Harness 要求 22.x 中的 Node 22.19+，或 Node 24+；Node 20 和 23 不满足其要求。
• 相应的包管理器：Homebrew（macOS）、系统包管理器（Linux）或 npm。
• 能访问各 Agent 的认证端点（浏览器 OAuth 流程会打开本地浏览器）。
• 运行 Forgexa daemon 的用户必须与完成 Agent 登录的用户一致。

Windows：原生 vs WSL2

Windows 用户有两条可行路径：

1. 原生（Windows 10+）——适用于官方支持 Windows 的 npm 类 Agent：Claude Code、GitHub Copilot CLI、Gemini CLI、OpenCode、Qwen Code、CodeBuddy Code。安装 Windows 版 Node.js 后，在 PowerShell 中使用相同的 npm install -g 命令即可。
2. WSL2——适用于基于脚本的 macOS/Linux 安装器（Codex、Kimi Code、MiMo Code、Qoder CLI、TraeCode CLI、ZCode）。先安装 WSL2 并装好 Ubuntu 22.04+，然后在 WSL 发行版内按 Linux 小节操作。

同侧原则

Agent 必须与 Forgexa daemon 及其操作的工作空间处于同一环境。工作空间在 WSL 内，daemon 和 Agent 也必须在该 WSL 发行版内运行——Windows 侧的 Agent 看不到 WSL 侧的工作空间（反之亦然）。桌面应用启用 WSL 工作空间的用户尤其要注意：应把 Agent 装进发行版，而不是装在 Windows 侧。

macOS 图形界面提示

macOS 从 Dock/Finder 启动的应用不会继承 shell 的 export。如果某 Agent 需要环境变量，请先在 Terminal 中启动一次桌面应用，或用 launchctl setenv <VAR> "<value>" 持久化（重启后需重设）。

---

Claude Code（Anthropic）

Anthropic 的终端智能编程工具。

• 官网：https://claude.com/product/claude-code
• 文档：https://code.claude.com/docs
• 仓库：https://github.com/anthropics/claude-code

macOS / Linux

# 官方原生安装脚本（推荐）
curl -fsSL https://claude.ai/install.sh | bash

# 或通过 npm
npm install -g @anthropic-ai/claude-code

Windows

# 原生安装脚本（PowerShell）
irm https://claude.ai/install.ps1 | iex

# 或通过 npm（Bash 工具需要 Git for Windows）
npm install -g @anthropic-ai/claude-code

官方同样支持 WSL2——在发行版内按 Linux 方式安装即可。

授权

claude

首次运行会打开浏览器，用 Claude 账号（Pro/Max 订阅）或 Anthropic Console 账号登录。服务器/daemon 机器没有浏览器时，先生成长期令牌：

claude setup-token   # 生成 CLAUDE_CODE_OAUTH_TOKEN，供无头环境使用

也可以改用环境变量 ANTHROPIC_API_KEY（Console 计费）。

验证

claude --version    # Forgexa 要求 >= 2.0.0

---

OpenAI Codex

OpenAI 的开源编程 Agent。

• 官网：https://developers.openai.com/codex
• 仓库：https://github.com/openai/codex

macOS

brew install codex
# 或
npm install -g @openai/codex

Linux

npm install -g @openai/codex

Windows

官方文档推荐 WSL2：在发行版内用上面的 Linux 命令安装。如需非 WSL 方案，请关注 GitHub Releases 页面的原生 Windows 构建进展。

授权

codex login

通过浏览器 OAuth 使用 ChatGPT 账号（Plus、Pro、Team 或 Enterprise）登录。如改用 API 计费：

codex login --api-key   # 或 export OPENAI_API_KEY

验证

codex --version    # Forgexa 要求 >= 0.147.0

---

GitHub Copilot CLI

GitHub 官方的终端 Copilot Agent，通过 Copilot 订阅计费。

• 官网：https://github.com/features/copilot/cli
• 文档：https://docs.github.com/zh/copilot

macOS / Linux / Windows

npm install -g @github/copilot

Windows PowerShell 原生可用，无需 WSL。

授权

copilot

首次运行会在浏览器中启动 GitHub 设备码登录。账号需具备有效的 Copilot 订阅（Pro、Business、Enterprise，或有限额的免费档）。

验证

copilot --version    # Forgexa 要求 >= 1.0.70（含鉴权持久化修复）

---

Gemini CLI（Google）

Google 的开源终端 AI Agent，由 Gemini 模型驱动。

• 官网：https://google-gemini.github.io/gemini-cli
• 仓库：https://github.com/google-gemini/gemini-cli

macOS / Linux / Windows

npm install -g @google/gemini-cli

macOS 也可用 brew install gemini-cli。Windows PowerShell 原生可用。

授权

gemini

首次运行提示 Google 账号登录（浏览器 OAuth）。个人 Google 账号含免费额度。API 计费方式：从 Google AI Studio 获取并导出 GEMINI_API_KEY；Vertex AI 亦受支持（独立配置）。

验证

gemini --version

---

OpenCode

开源 AI 编程 Agent（不绑定单一厂商——自带模型供应商接入）。

• 官网：https://opencode.ai
• 仓库：https://github.com/sst/opencode

macOS / Linux

curl -fsSL https://opencode.ai/install | bash
# 或
npm install -g opencode-ai
# macOS 也可: brew install sst/tap/opencode

Windows

npm install -g opencode-ai

原生 npm 可用；偏好脚本安装器的话，WSL2 也是稳妥选择。

授权

opencode auth login

选择供应商（Anthropic、OpenAI、Google 等），完成浏览器 OAuth 或粘贴 API Key。OpenCode 支持一个 profile 同时配置多个供应商。

验证

opencode --version    # Forgexa 要求 >= 1.4.0

---

Kimi Code（月之暗面）

月之暗面（Moonshot AI）的终端编程 Agent，由 Kimi 模型驱动。

• 官网：https://code.kimi.com

macOS / Linux

curl -fsSL https://code.kimi.com/kimi-code/install.sh | bash

Windows

使用 WSL2——在发行版内运行 Linux 安装脚本。原生 Windows 支持请关注官网。

授权

kimi

首次运行打开浏览器，使用 Kimi 账号登录。无头机器可在 CLI 设置中改用 API Key（Moonshot OpenAPI）。

验证

kimi --version    # Forgexa 要求 >= 0.18.0

---

MiMo Code（小米）

小米的终端编程 Agent。在 Forgexa 中该集成仅限显式选择（不参与自动路由和后备链）。

• 官网：https://mimo.xiaomi.com

macOS / Linux

curl -fsSL https://mimo.xiaomi.com/install | bash

Windows

使用 WSL2——在发行版内运行 Linux 安装脚本。原生 Windows 支持请关注官网。

授权

mimo

按首次运行提示在浏览器中完成 MiMo 账号登录。

验证

mimo --version    # Forgexa 要求 >= 0.1.14

---

Qwen Code（阿里）

通义千问的终端编程 Agent，基于 Gemini CLI 架构衍生。

• 仓库：https://github.com/QwenLM/qwen-code
• 文档：https://qwenlm.github.io/qwen-code-docs/

macOS / Linux / Windows

npm install -g @qwen-code/qwen-code

Windows PowerShell 原生可用。

授权

qwen

首次运行提供 Qwen OAuth 登录（通过 chat.qwen.ai 账号，含免费额度）。API 计费方式：导出指向阿里云百炼 / DashScope 兼容端点的 OpenAI 兼容凭证：

export OPENAI_API_KEY="<your-key>"
export OPENAI_BASE_URL="<compatible-endpoint>"

可选开启沙箱以获得更安全的执行：qwen sandbox --sandbox。

验证

qwen --version    # Forgexa 要求 >= 0.24.1

---

CodeBuddy Code（腾讯）

腾讯的终端编程 Agent。在 Forgexa 中仅限显式选择。

• 官网：https://www.codebuddy.ai

macOS / Linux / Windows

npm install -g @tencent-ai/codebuddy-code

Windows PowerShell 原生可用。

授权

codebuddy login

通过浏览器 OAuth 使用腾讯云 / CodeBuddy 账号登录。

验证

codebuddy --version    # Forgexa 要求 >= 2.156.0

---

Qoder CLI（阿里）

Qoder 团队的智能编程 CLI。在 Forgexa 中仅限显式选择。

• 官网：https://qoder.com

macOS / Linux

curl -fsSL https://qoder.com/install | bash

Windows

使用 WSL2——在发行版内运行 Linux 安装脚本，或关注官网的原生 Windows 安装包。

授权

qoder

按首次运行提示在浏览器中完成 Qoder 账号登录。

验证

qoder --version    # Forgexa 要求 >= 1.1.59

---

TraeCode CLI（Trae）

Trae 的终端编程 Agent。在 Forgexa 中仅限显式选择。

• 官网（国内）：https://trae.cn
• 官网（国际）：https://trae.ai

macOS / Linux

sh -c "$(curl -fsSL https://trae.cn/trae-cli/install_v2.sh)"

国际用户可使用 https://trae.ai 上的对应安装脚本。

Windows

使用 WSL2——在发行版内运行 Linux 安装脚本，或关注官网的原生 Windows 安装包。

授权

traecli login

浏览器 OAuth 登录 Trae 账号（国内或国际，与安装脚本来源保持一致）。

Forgexa 就绪门槛

在通过真实账号 live gate 之前，Forgexa 将 TraeCode CLI 保持为未就绪状态。安装并登录后，请先确认 Runtime 页面显示就绪，再向其派发任务。

验证

traecli --version

---

ZCode（智谱 Z.ai）

Z.ai 的编程 Agent，Forgexa 通过 app-server 协议接入。仅限显式选择。

• 官网：https://z.ai
• 仓库：https://github.com/zai-org/ZCode

macOS / Linux / Windows

从 GitHub Releases 页面安装——选择对应平台的压缩包。Windows 若无原生构建，请使用 WSL2。

授权

zcode login

浏览器 OAuth 登录 Z.ai 账号。

Forgexa 专属步骤（建议执行）：

# 将已安装二进制的指纹写入持久化允许清单
# （GUI 启动的桌面应用/daemon 均可见，无需重启）
forgexa zcode approve-build

# 替代方案：环境变量（仅对能读到它的进程生效）
export FORGEXA_ZCODE_ALLOWED_SHA256="<approved-zcode-sha256>"

# 可选：为 Forgexa 指定专用的 ZCode profile 目录
export FORGEXA_ZCODE_HOME="$HOME/.forgexa/zcode"
HOME="$HOME/.forgexa/zcode" zcode login   # 在专用 profile 内完成一次登录

# 可选：profile 未持久化默认模型时，指定模型
export FACTORY_ZCODE_MODEL="<providerId/modelId>"

验证

zcode --version

---

DeepSeek Harness（开发者预览）

• 官网：https://www.deepseek.com/harness/
• 仓库：https://github.com/deepseek-ai/deepseek-harness
• 规范 ID：deepseek；CLI：dsh。这不是给 OpenCode 配 DeepSeek 模型，也不是通用 LLM Integration。

deepseek 为规范 ID，原 deepseek-harness 仍作为 CLI、工作流、API 和 Desktop 旧会话的输入兼容别名；新选择与响应使用 deepseek。原 deepseek-harness home/批准路径、FACTORY_DEEPSEEK_HARNESS_* 变量和 native handle 不变。更新/重启服务器与 Runtime 或 Desktop 后加载新代码；向旧版 daemon 派发时，服务器保留它实际报告的旧 wire ID。

默认建议全局安装，便于 PATH 发现：

node --version
npm i -g @deepseek-ai/dsh@0.2.0-rc.2
dsh --version

也可安装到独立工具目录，不要加入业务项目依赖：

npm install --prefix "$HOME/.forgexa/tools/deepseek-harness" --save-exact @deepseek-ai/dsh@0.2.0-rc.2
export FACTORY_DEEPSEEK_HARNESS_PATH="$HOME/.forgexa/tools/deepseek-harness/node_modules/.bin/dsh"

发现阶段不会通过 npx 下载 CLI。macOS 使用 /usr/bin/sandbox-exec；Linux 要求可用的 bwrap，包括用户命名空间权限。WSL 按同一发行版的 Linux 路径运行，仍需验收，不能视为原生 Windows 已就绪。

先在本机完成官方 Harness 认证。Forgexa 读取 DEEPSEEK_API_KEY 或外部认证文件，默认 $DSH_HOME/.credentials.yaml 或 ~/.dsh/.credentials.yaml。无 API Key 时可使用操作者配置的 DeepSeek 登录账号 grant；失败不会静默切换供应商。FACTORY_DEEPSEEK_HARNESS_CREDENTIALS 指定认证文件绝对路径；FACTORY_DEEPSEEK_HARNESS_MODEL 指定支持的模型 ID，默认 deepseek-flash。Messages 端点固定为 https://api.deepseek.com/anthropic，不是任意 OpenAI-compatible 端点。失效的认证请在任务外通过官方 CLI 更新。

每个 canonical 工作区使用 ~/.forgexa/agents/deepseek-harness/<workspace-hash>、串行 profile 锁和私有运行 overlay。不导入个人 patch/plugin。唯一 preset 为 workspace-write + never：提权直接拒绝，并非自动批准。外层监督拒绝工作区/受管状态之外，以及 Git 元数据、session 绑定和认证文件的写入。这不是同 UID 秘密读取或网络隔离；仅用于可信工作区，不可信输入使用独立 OS 用户或 VM。

会话日志上传、插件清单上传与 OTel 扩展分别禁用。普通模型请求仍会把提示与选定代码发给 DeepSeek，不能承诺完全没有网络流量。

精确构件完成真实首轮/恢复/取消/隔离验收后：

forgexa agent approve-live deepseek
forgexa check --agent deepseek --quick
forgexa check --agent deepseek

批准记录操作者声明，不自动测试。--quick 不调用模型；普通 check 执行可能计费的最小任务，不是完整验收清单。构件、OS/Node 或运行策略变化使批准失效；build/provider/model/composition 改变时拒绝原生恢复，应新建会话。仅 turn 开始前明确证明原生日志不存在时，允许一次新建重试。

输出为提交后的 JSONL 消息块，不是 token 流。成功要求 session/turn-end/final 加 exit 0；取消/超时优先于原生 exit 0。监督器限制输出预算为 4 MiB。图片、原生 fork、只读 review 与并行能力保持关闭，共享池和自动路由未开放。

验证安装

逐一运行已安装 Agent 的版本命令——每条都应正常退出并打印版本号：

claude --version
codex --version
copilot --version
gemini --version
opencode --version
kimi --version
mimo --version
qwen --version
codebuddy --version
qoder --version
traecli --version
zcode --version
dsh --version

然后重启 Forgexa daemon（或桌面应用），使其重新发现 Agent，并在 Web 控制台的 Runtime 页面确认：每个已安装的 Agent 都出现在对应 Runtime 的 Agent 列表中。守护进程启动见《安装部署》→ 启动守护进程，程序化检查见 Runtime & Agent API。

常见问题排查

现象	可能原因	处理方式
Runtime 页面没有该 Agent	在 daemon 启动之后才安装	重启 daemon，重新扫描 PATH
daemon 任务报 command not found	Agent 安装在其他用户名下 / 非登录 shell	用运行 daemon 的同一用户安装；确认二进制在该用户 PATH 上
macOS 任务读不到 export 变量	GUI 启动的应用不继承 shell 环境	用 launchctl setenv（见上方提示）或从 Terminal 启动
执行中途鉴权报错（401）	令牌过期 / 登录用户不一致	在 Runtime 机器上以 daemon 用户重新执行该 Agent 的登录命令
TraeCode CLI 一直未就绪	真实账号 live gate 未通过	完成登录后重新检查 Runtime 页面
ZCode 启动被拒绝	二进制指纹未批准	执行 forgexa zcode approve-build
Harness 已安装但未就绪	未知构件/平台或未验收	精确安装 0.2.0-rc.2，验收后批准；原生 Windows 仍阻断
Harness 恢复被拒绝	配置改变或会话不属于 Forgexa	新建会话，不删除日志或借用个人会话
Windows 侧 Agent 看不到 WSL 工作空间	违反同侧原则	把 Agent 安装到 WSL 发行版内（见上文）