opencode subagents

opencode-subagent-mcp

通过更便宜的 opencode 模型运行 Claude Code 子 Agent，例如使用 opencode Go 订阅中的 opencode-go/deepseek-v4.1-flash（DeepSeek），同时 Claude Code 本身仍直接与 Anthropic 通信。将搜索、重构、修复 Bug、测试和研究任务委派给成本仅为 Opus 或 Sonnet 一小部分的模型，同时保留你已在使用的工具：后台 Agent、通过 send_message 恢复任务、工作树隔离、.claude/agents 定义、权限提示和结构化输出。

这是一个 stdio MCP 服务。你的 Claude Code 主会话不会被代理或路由到任何地方；此服务只会运行你委派给它的子 Agent，并使用它自行启动的专用 opencode serve 实例。

安装

需要 Node 22+、git，以及已登录到所需提供商的 opencode CLI（opencode auth login）。

作为 Claude Code 插件安装（还会添加一项技能，告知 Claude 何时将任务委派给 opencode）：

claude plugin marketplace add sebstaq/opencode-subagent-mcp
claude plugin install opencode-subagent-mcp@sebstaq-opencode

或作为普通 MCP 服务安装：

claude mcp add -s user opencode -- npx -y [email protected]

运行和发送的内容

• 它会在随机的 localhost 端口上启动一个专用的 opencode serve 进程，并使用随机密码；Claude Code 退出时，该进程也会停止。每次运行都会生成密码，且只在此服务与该本地进程之间使用。该进程会继承你的环境，因此 opencode 可以使用你已为其配置的提供商登录信息和 API 密钥；此服务本身绝不会读取、存储或发送这些凭据。
• 你委派的提示词，以及子 Agent 读取的文件和命令输出，都会通过 opencode 发送给你选择的模型提供商（默认为 opencode Go），并受该提供商的数据保留条款约束。opencode 会在你机器上的本地数据库中保留会话历史记录。不会向其他任何地方发送任何内容；此服务没有遥测功能，也不会进行其他网络调用。
• 它会读取 ~/.claude/settings.json、项目的 .claude/settings.json 和 .claude/settings.local.json、.claude/agents/*.md（用户和项目级别），以同步你的权限规则和 Agent 定义；如果存在，还会读取 ~/.config/opencode-subagent-mcp/config.json。
• 使用 isolation: "worktree" 时，它会在项目的 .claude/worktrees/ 下创建 git 工作树，并在工作树没有改动时将其移除。

这是一个独立项目，与 Anthropic 或 opencode 团队均无关联。

工具

工具	原生对应项	功能
agent	Agent 工具	运行子 Agent；返回最终报告、用量和工作树结果
send_message	SendMessage	使用完整历史记录继续已结束的 Agent；重启后也可继续
wait	后台完成通知	收集通过 run_in_background 运行的 Agent（可选超时时间）
stop	TaskStop	中止正在运行的 Agent，并返回其已生成的内容
list	/agents	列出此会话的 Agent、Claude Agent 定义和 opencode Agent

agent_id 在 MCP 服务或 Claude Code 重启后仍可继续使用：wait 和 stop 会返回该 Agent 的运行情况，而 send_message 会继续运行它。重启前的 Agent 在再次使用其 ID 前不会出现在 list 中，但仍保留在 opencode 的本地会话存储中。

agent 参数：description、prompt、subagent_type、model、isolation: "worktree"、permission_mode、tools、disallowed_tools、max_turns、effort、output_schema、run_in_background、cwd。

与原生子 Agent 的功能对等

原生行为	此处
全新上下文，只返回最终消息	相同。长输出会被截断（maxResultChars），完整文本会写入文件
在项目目录中运行	相同（依次使用 MCP 根目录中的 cwd、CLAUDE_PROJECT_DIR，然后是服务端的 cwd）
isolation: worktree	布局相同（.claude/worktrees/<name>，分支为 worktree-<name>，基于默认分支）。内容未更改时会移除，否则会保留并附带提交/文件摘要。禁止访问外部路径
权限提示显示在主会话中	opencode ask 规则会显示为 MCP 询问对话框（允许一次／始终允许／拒绝，可选提供反馈）
权限模式	default、acceptEdits、auto、bypassPermissions、plan 会映射到 opencode 规则；用户、项目和本地设置中的 Claude permissions.allow/ask/deny 均适用
后台 Agent 完成时发送通知	Claude Code 会自动将耗时较长的 MCP 调用转入后台，并在完成时通知；使用 run_in_background 和 wait 可进行显式控制
使用完整历史记录恢复	send_message（也适用于先前会话中的 Agent 或重启后的 Agent，因为 opencode 会持久化这些 Agent）
.claude/agents/*.md 定义	通过 subagent_type 使用：prompt、tools、disallowedTools、permissionMode、maxTurns、effort、isolation。仅当 model 为 opencode 的 provider/model 时才适用
maxTurns 返回部分输出	相同；状态为 max_turns，可恢复
UI 中的进度	工具调用会作为 MCP 进度通知发送
子 Agent 无法生成子 Agent，也无法向用户提问	opencode 的 task 和 question 工具已禁用
结构化输出	output_schema（JSON Schema）→ opencode 结构化输出，以 structuredContent 的形式返回
已知缺口：Agent 不会显示在 Claude Code 的 /tasks Agent 视图中；不支持携带父级上下文的分叉；Workflow 工具的 agent() 无法将任务交给它们；auto 模式没有安全分类器（除你配置的规则和固定的一组会要求确认的破坏性命令外，它允许所有操作，包括访问项目外的路径：rm -r/-rf、git push --force、git reset --hard、git clean -f、git restore/git checkout --、`curl	sh、sudo、chmod -R/chown -R、dd、mkfs、npm/pnpm publish；opencode 会分别匹配命令链中的每条命令）；父级的权限模式对 MCP 服务不可见，因此默认模式来自配置；钩子、技能预加载、memory` 和每个 Agent 独立的 MCP 服务都未映射。

引导 Claude

Claude Code 会自行决定使用其原生 Agent 工具还是此工具，因此路由行为不可预测。若要将 opencode 设为默认选项，用于处理易于验证的委派工作，请将 docs/claude-md-snippet.md 中的代码片段粘贴到全局 ~/.claude/CLAUDE.md 中。

配置

可选的 ~/.config/opencode-subagent-mcp/config.json（或 $OPENCODE_SUBAGENT_CONFIG）：

{
  "defaultModel": "opencode-go/deepseek-v4.1-flash",
  "defaultPermissionMode": "auto",
  "pure": true,
  "opencodeBin": "opencode",
  "maxConcurrent": 8,
  "maxResultChars": 80000
}

OPENCODE_SUBAGENT_MODEL 和 OPENCODE_SUBAGENT_MODE 可覆盖前两项。pure 会在不加载外部插件的情况下启动 opencode。

工作原理

首次使用时，服务会在随机的本地回环端口上启动 opencode serve，并使用随机密码，订阅其事件流，同时为每个 Agent 启动一个 opencode 会话（Agent ID = 会话 ID）。opencode 发出的权限请求会通过 MCP 询问机制进行响应。MCP 服务停止时，opencode 进程也会停止；崩溃服务遗留的进程会在下次启动时清理。

开发

pnpm check   # typecheck, lint, format check, unit tests
pnpm smoke [provider/model]   # end-to-end run against a real model in a temp repo

许可证

MIT