forge-delegate

forge-delegate

MCP 服务，可将编码工作从你的主 Agent（Claude Code、Codex 或 opencode）委派给其他 AI 模型，从而让主 Agent 的上下文保持精简。大量文本生成由另一个模型在自己的上下文中完成，通常成本更低或免费，最后只返回摘要。通过 opencode 实现完整的 Agent 式委派，以处理实际工作；通过直接调用 API 获取第二意见。

你的主 Agent（成本较高的模型）负责架构、关键逻辑和艰难决策。低成本模型则处理大量低风险工作（样板代码、重复编辑、测试、Lint／类型修复），并汇报结果。

┌──────────────────┐   MCP (stdio)   ┌──────────────────┐   opencode run   ┌──────────────────┐
│ Claude / Codex / │ ──────────────► │ forge-delegate   │ ───────────────► │ opencode + cheap  │
│ opencode (primary)│                │  (this server)   │    --model cheap │      model        │
└──────────────────┘ ◄────────────── └──────────────────┘ ◄─────────────── └──────────────────┘
        result: text + session + token usage

快速开始

网页配置器——选择模型、目标和范围，生成可直接粘贴的命令 （https://muhamadbarzani.github.io/forge-delegate/）。模型选择器依托实时的 models.dev 目录，支持搜索、免费／低价筛选和真实价格， 让你选择实际可用的模型，而不是盲目猜测。

npx（推荐——适用于所有平台，无需 bash）：

npx -y forge-delegate setup --model "opencode/deepseek-v4.1-flash-free" --targets "claude,codex,opencode"

就这么简单——npx 会引导你完成软件包的初始化，而 setup 会为你选择的 Agent 注册 MCP 服务、设置默认模型，并安装一个小型启动器，让服务保持最新。在 Windows（cmd／PowerShell）、macOS 和 Linux 上均可运行——无需 bash。

不带标志运行 setup，即可按提示交互式选择（默认值显示在[方括号]中，按 Enter 接受）。对于默认模型，它会列出 opencode 可运行的所有模型，你可以按编号或名称选择；传入任意标志即可跳过该提示。在自动化／非终端运行中，它会直接使用合理的默认值。

GitHub Pages：通过 Settings → Pages → Deploy from a branch → main / /docs 启用。 配置器位于 docs/index.html。只有在自行托管备用安装程序时，install.sh 中的 FORGE_DELEGATE_REPO 默认值 （以及其中的原始 URL）才会影响安装。

如果你正在使用检出的代码库？运行 node cli.mjs setup 即可完成相同操作。

setup 将会：

1. 为你选择的每个 Agent 注册 MCP 服务（--targets claude,codex,opencode）。
2. 设置默认模型（--model），这样调用时就可以省略 model。
3. 安装自动更新启动器（适用于通过发布版本安装的情况；从 git 检出时会跳过）。
4. 对于 Codex，将 MCP 超时设置（startup_timeout_sec、tool_timeout_sec）调高到 Codex 的默认值（10 秒／60 秒）以上，以免内联委派被中断。

MCP 服务会通过 MCP instructions 将路由和成本策略指导直接注入 Agent 的上下文，无需编辑记忆文件（CLAUDE.md／AGENTS.md）。

然后重启你的 Agent，并确认服务已连接：在 Claude Code 中运行 /mcp，在 Codex 中运行 codex mcp，或在 opencode 中运行 opencode。

所需条件

• Node.js ≥ 18 和 opencode v2 或更高版本（安装程序可以为你获取 opencode）。 v2 移除了旧版本用于设置工作目录和变体的 CLI 标志；而遇到未知标志时，opencode run 会打印帮助信息并成功退出，因此 v2 之前的二进制文件会静默失败。服务会在启动时检查并发出警告。
• 免费 opencode/* 模型（例如 opencode/deepseek-v4.1-flash-free）无需身份验证，无需任何设置。
• 任何其他提供商（deepseek、openai、google、ollama 等）都必须先在你自己的 opencode 中登录——这是你在自己的 opencode 中执行的步骤，并非 forge-delegate 会处理的操作：opencode auth login <provider>。forge-delegate 会复用你 opencode 中的凭据，且绝不会存储 API 密钥。（Ollama 无需密钥，只需运行 Ollama 应用。）

Windows

使用 npx 方式——无需 bash（适用于 cmd／PowerShell）。支持所有三个目标，包括原生 Windows Codex CLI。

范围

--scope	Claude Code	Codex	opencode
user (默认)	~/.claude.json — 所有项目	~/.codex/config.toml — 所有项目	~/.config/opencode/opencode.json — 所有项目
project	项目中的 .mcp.json（需要一次性批准）	项目中的 .codex/config.toml（仅为受信任的项目加载）	项目中的 opencode.json

免费试用 — 无需注册

opencode 在 opencode/ 下提供免费的免认证模型：

npx -y forge-delegate setup --model "opencode/deepseek-v4.1-flash-free" --targets "claude,codex"

其他免费选项：opencode/mimo-v2.6-flash-free、opencode/nemotron-3.5-lightning-free。免费套餐有 速率限制；随时可以通过 forge-delegate config set --model <m> 切换。

工具

工具	功能	上下文开销
ask_model	征求其他模型的意见（直接调用 API，不访问文件）	小
delegate	模型通过 opencode 自带的工具循环自主工作 — 默认以内联方式运行；background:true 会返回一个作业 ID，可通过 check_delegation 轮询	极小→中等
check_delegation	轮询后台作业（不带 ID 时列出所有作业）	极小
list_models	列出本地/免密钥、直接调用 API 和 Agentic 模型	小
get_delegate_config	读取当前配置（默认模型、目录、autoApprove、配置文件）	极小
set_delegate_config	在运行时更改配置 — 无需重新安装	极小

delegate 可节省上下文：外部模型通过 opencode 在本地执行自己的工具循环。文件内容绝不会进入主 Agent 的上下文。快速任务以内联方式返回；较长的任务会由 Claude Code 自动转到后台（超过约 2 分钟）。其他宿主会等待内联调用完成，因此对于较长的任务，系统会提示 Agent 在这些宿主中传入 background:true。

每次委派的结果末尾都会显示所用令牌数，以及在提供商报告价格时显示费用。forge-delegate stats 会按模型汇总两项数据。

何时委派

✅ 委派 — 量大、风险低	⛔ 保留给主 Agent
为规格明确的行为编写测试	架构、系统设计、抽象选择
样板代码和脚手架（CRUD、DTO、测试固件、模拟对象）	对安全敏感的代码（身份验证、加密、机密信息、权限）
对多个文件进行机械式修改（重命名、属性传递、导入）	并发、性能关键路径、细微的正确性问题
修复 lint / 格式 / 类型错误	需要判断的模糊或未充分说明的需求
文档字符串、注释、README / 更新日志章节	公共 API / 接口设计、破坏性变更
规格明确的简单数据转换 / 迁移	调试未知根因
明显的胶水代码 / 格式转换	出错后代价高昂或难以发现的任何任务

完整指南：docs/DELEGATION.md

delegate-work 技能

安装时也会为 Claude Code 安装此技能（~/.claude/skills/delegate-work/，或在 --scope project 下安装到 <project>/.claude/skills/），并为 Codex 安装（~/.agents/skills/delegate-work/， 或 <project>/.agents/skills/）。使用 --no-skill 跳过。

之所以提供此技能，是因为 MCP 服务的 instructions 只会在会话开始时注入一次， 随着上下文逐渐填满，这些指令就会被淹没 — 到第 30 轮时，它们的重要性已经不如模型眼前的内容。技能描述会针对每一轮用户输入重新匹配，因此委派触发条件（“为……编写测试”“将 X 全部重命名”“修复 lint 错误”）会在整个会话中持续生效，而不会逐渐失效。

配置

配置存储在 ~/.forge-delegate/config.json 中，每次调用时都会重新读取——可随时修改，无需重新安装。有四种方式：

1. 通过 Agent 使用 MCP 工具 get_delegate_config / set_delegate_config。
2. 终端 CLI：forge-delegate config get、forge-delegate config set --model <m> --timeout <s> --dir <path> --autoApprove false、forge-delegate config path。
3. setup 标志：--model、--targets、--scope、--project-dir。
4. 直接编辑文件。

字段	描述	默认值
defaultModel	调用未指定 model 时使用的提供方/模型	未设置
defaultAgent	用于委派任务的 opencode Agent	未设置
defaultVariant	默认推理强度变体	未设置
autoApprove	自动批准权限，避免无头委派任务受阻	true
timeoutMs	每次委派任务的超时时间	900000（环境变量 FORGE_OPENCODE_TIMEOUT）
defaultDirectory	委派任务的默认工作目录	未设置（服务当前工作目录）
profiles	命名预设 { name: { model, agent, variant, autoApprove, directory } }	{}

每个委派工具也接受单次调用的 model、directory、agent、autoApprove 和 profile 覆盖值。单次调用的值优先于预设值，预设值优先于配置默认值。

模型

• opencode 提供方——免费的免认证模型（opencode/deepseek-v4.1-flash-free 等），以及你通过 opencode auth login <provider> 登录的任何模型。
• 通过 opencode 登录使用直接 API——OpenAI 兼容提供方使用 provider/model 格式。
• 自定义提供方——在 opencode.json 中定义的 OpenAI 兼容提供方（@ai-sdk/openai-compatible + baseURL），可通过 provider/model 调用。
• Ollama（本地）——ollama:llama3、local:qwen2.5-coder，无需密钥。

安全注意事项

• autoApprove: true 会在以非交互方式运行委派任务时授予工具权限——请将其用于你信任的代码库，并检查差异。设置 autoApprove: false 可要求手动批准。
• 此服务绝不存储 API 密钥——提供方认证信息保存在 opencode 自己的认证存储中。
• 使用情况会记录到 ~/.forge-delegate/usage.jsonl；请参阅 forge-delegate stats。

CLI

forge-delegate --version  Print the installed version
forge-delegate setup      Register with Claude Code / Codex / opencode
forge-delegate serve      Start the MCP server (used internally)
forge-delegate config     get | set | path
forge-delegate status     Show version, update mode, opencode logins, usage
forge-delegate stats      Show detailed usage statistics

在已发布版本上运行 setup 会写入 ~/.forge-delegate/launcher.mjs，并注册该路径，而不是 npx。启动器会在 ~/.forge-delegate/pkg 下保留一个私有安装，每 6 小时最多向 npm 查询一次最新版本，并自动安装更新的同一主版本。安装时会使用 npm install --ignore-scripts，通过暂存目录进行；若发生任何故障，则回退到上一个正常版本。新版本会在下次 Agent 启动时生效；下载在后台进行，因此不会延迟启动。

使用 FORGE_AUTO_UPDATE=0 禁用自动更新。主版本更新（2.0.0）不会自动安装——请重新运行 npx -y forge-delegate setup，以主动安装该版本。

启动器也是 CLI 入口：运行 node ~/.forge-delegate/launcher.mjs status 可查看正在运行的版本和更新模式，运行 --version 可显示版本号。

手动配置的 npx 安装不受启动器管理：npx 会永久保留缓存副本，因此请使用 rm -rf ~/.npm/_npx 清除缓存并重启。运行 npx -y forge-delegate@latest setup 可将 npx 安装迁移到启动器；@latest 使用独立的 npx 缓存目录，如果仍然启动旧版本，请先清除缓存。

发布（npm）

主要安装方式是 npx -y forge-delegate setup，因此该软件包必须发布到 npm。检查清单：

1. npm run prepublishOnly — 对所有入口文件进行语法检查（发布时会自动运行）。
2. npm pack --dry-run — 确认压缩包只包含 launcher.mjs、cli.mjs、server.mjs、 lib.mjs、install.sh、docs/、skills/、README.md（由 files 字段指定），不包含 node_modules。
3. 更新 package.json 中的 version（以及 package-lock.json 根目录中的 version）。
4. npm login && npm publish — bin 字段可让 npx forge-delegate … 正常运行。

另外，请确保 GitHub 仓库 MuhamadBarzani/forge-delegate 已创建，并启用了指向 /docs（配置器）的 Pages — raw.githubusercontent.com 安装 URL 和配置器中硬编码的 URL 都指向该仓库。

许可证

MIT