awesome-codex-subagents → OpenCode

English | 简体中文

174 个专家 agent，一条命令装进 OpenCode。

OpenCode 自带的 subagent 只有 general 和 explore 两个。当你需要一次真正到位的 PR 级代码审查、一份能落地的威胁建模、一次跨文件的架构重构规划，往往只能靠主 agent 一边读上下文一边现编 —— 既占上下文，质量也不稳定。

这个仓库把它变成了开箱即用的东西：

npx awesome-codex-subagents-opencode --global

装完重启 OpenCode，敲 @reviewer 就能让一个只读的审查者独立跑完整个 diff，只把结论 带回你的对话。它不会污染主上下文，也不会顺手改你的文件。不需要 clone，也不需要先装依赖。

它解决什么问题

覆盖范围

174 个 agent，覆盖 13 个领域：

完整清单见 agents/。

快速开始

最快的方式不需要 clone：

npx awesome-codex-subagents-opencode --global

把 174 个 agent 装进 ~/.config/opencode/agents，重启 OpenCode 后即可用 @agent名 调用。

包名就是命令。 npx ocagents 这类简写不能用 —— npm 会去找同名包并失败。 请始终使用上面的完整包名。

只想装一部分？174 个会让 @ 菜单很长，也会稀释模型的自动选择：

npx awesome-codex-subagents-opencode --global --preset minimal

或者从仓库安装

想读源码或自己改的话。下面所有命令都假定你已经在仓库目录内：

git clone https://github.com/He-Xun/awesome-codex-subagents-opencode.git
cd awesome-codex-subagents-opencode

node install.mjs            # -> 在运行命令的项目里创建 ./.opencode/agents
node install.mjs --global   # -> ~/.config/opencode/agents（所有项目生效）

零依赖，只需 Node 18+。

脚本会自己解析路径，所以从任意目录执行 node /path/to/repo/install.mjs --global 也可以， 不需要先 cd。

参数

-g, --global          装到 ~/.config/opencode/agents
    --dir <path>      装到指定目录
    --lang <code>     描述语言（默认跟随系统）
    --preset <name>   只装预设子集（minimal / web / backend）
    --only <a,b>      只装指定 agent
    --skip <a,b>      排除指定 agent
    --list-presets    查看预设
    --dry             只预览，不写文件
-h, --help            查看帮助

--flag value 和 --flag=value 两种写法都支持。

用 npm 脚本（在仓库根目录）

npm run install:global      # 装到全局
npm run install:local       # 装到当前项目
npm run verify              # 校验所有产物
npm run switch -- --to=en   # 切换描述语言
npm run presets             # 查看可用预设

预设

预设就是纯文本名单（presets/*.txt），可以直接改或加新的。

三个设计取舍

这三点决定了它和「直接把文件复制过来」的差别：

1. 不写死模型。 源仓库每个 agent 都绑定了 gpt-6.1-sol，这个模型在你的 provider 上大概率不存在，硬套过去等于 174 个 agent 全部不可用。本仓库完全不输出 model 字段， 让 subagent 继承调用方的模型 —— 换 provider、换模型都不用重新生成。

2. MCP 依赖去厂商化。 源仓库有 agent 绑定 OpenAI 自家的文档服务。这里替换成通用的 websearch + webfetch，任何厂商的文档都能查。

3. 语言只翻描述，不翻正文。 详见下方为什么 —— 中文 反而更费 token，全量汉化是负优化。

项目来源

本仓库是 VoltAgent/awesome-codex-subagents （6.4k star）的 OpenCode 移植版。上游提供的是 Codex 格式的 .toml 定义，本项目将其 转换为 OpenCode 的 Markdown agent 格式，并解决了上述三个移植问题。

只做格式适配，不改写 prompt 语义：正文原文照搬，便于上游更新时重新生成。

上游更新后重新生成：

cd awesome-codex-subagents-opencode      # 切到仓库根目录
git clone --depth 1 https://github.com/VoltAgent/awesome-codex-subagents.git ../src
node tools/codex-subagents-to-opencode.mjs ../src/categories agents

描述语言：随系统自动选择，可随时切换

prompt 正文始终是英文，只有 description（也就是 @ 菜单里显示的那一行）会跟着语言变化。

安装时自动检测

tools/install.mjs 按以下顺序决定语言，没有匹配译表时回退到英语：

1. --lang=xx 或环境变量 OPENCODE_SUBAGENTS_LANG
2. LC_ALL / LC_MESSAGES / LANG / LANGUAGE
3. Intl 报告的系统 locale
4. 回退 → 英语

内置语言：English (en) · 简体中文 (zh) · Español (es) · Русский (ru) · 한국어 (ko)。

--lang 接收的是语言代码，也就是 ISO 639-1 的两位标签（zh、es、ru、ko、en）。 它同时也是 tools/i18n/ 下译表的文件名，所以两者不会对不上。 完整的系统 locale（zh-CN、es_ES、pt_BR）只是检测时的输入，不是传给 --lang 的值。

当 LANG 或 LC_ALL 已设置但没有对应译表时，结果是英语，而不是再从 Intl 推断另一个 locale。显式设置了环境变量，就按用户意图处理。

node install.mjs                          # 跟随系统 locale
node install.mjs --lang=en                # 强制英文
node install.mjs --lang=zh                # 强制中文
node install.mjs --only=reviewer,debugger # 只装部分

系统 locale 的映射规则：先去掉地区部分，再与已有译表匹配。

随时切换

--dir 默认是 ./.opencode/agents：

cd awesome-codex-subagents-opencode      # 切到仓库根目录
node tools/switch-lang.mjs --list                                   # 查看可用语言
node tools/switch-lang.mjs --to=zh                                  # 切中文
node tools/switch-lang.mjs --to=en                                  # 切回英文
node tools/switch-lang.mjs --to=zh --dir=~/.config/opencode/agents  # 指定目录
node tools/switch-lang.mjs --to=zh --dry                            # 预演

切换器只改写 frontmatter 里的 description 那一行，正文和权限原样保留，并保持原有的 引号风格，因此中英来回切换不会产生多余 diff（已验证 174 个文件往返 0 差异）。

添加新语言

在 tools/i18n/ 下新建 <lang>.json，<lang> 是 ISO 639-1 语言代码，也就是你传给 --lang 的值（法语用 fr.json，德语用 de.json）。键为 agent 名：

{
  "reviewer": "需要 PR 式评审，聚焦正确性、安全性、行为回归与测试缺失时使用。",
  "debugger": "需要做深度缺陷定位时使用。"
}

无需改代码，install.mjs / switch-lang.mjs 会自动发现，随后即可用 --lang=fr 选择。 缺条目时该 agent 保留英文。

只用基础语言码，不要带地区：文件名必须是 fr.json 而不是 fr-FR.json，因为检测时会先 去掉地区部分再匹配。

内置译表遵循的敬语规范（贡献新语言时请沿用）：

为什么只翻译 description

先看实测数据。同一份内容的中英对照：

来源：Chinese vs. English Tokens。

国产模型分词器对中文友好得多（从 +24% 降到 +8%），但方向从未逆转：中文更费 token。 英文可以整词压成单个 token，汉字基本一字一 token 或更多。

换算到本仓库：中文 description 字符数少 66%，但 token 数增加约 50%。全量汉化正文会让 327k 字符的 prompt 再涨约 8%。

所以：语言的价值是可读性和触发准确性，不是省 token。 想省 token 应该精简 agent 数量， 而不是换语言。

设计细节

1. 不写死模型

源文件里的 model = "gpt-6.1-sol" 是 Codex 专用模型，换到 OpenCode 上大概率不存在。 转换器完全不输出 model 字段，让 subagent 继承调用方 agent 的模型 —— 这是 OpenCode 的文档行为，好处是与 provider 无关，换模型不用重跑转换。

需要给特定 agent 钉死模型时：

cd awesome-codex-subagents-opencode      # 切到仓库根目录
node tools/codex-subagents-to-opencode.mjs <src> agents \
  --model-map=gpt-6.1-sol=anthropic/claude-sonnet-5,gpt-6-luna=anthropic/claude-haiku-5

2. MCP 依赖去厂商化

Codex 允许在 agent 文件内联 [mcp_servers.NAME]，OpenCode 不允许（必须写在 opencode.json）。仓库里的两个依赖处理如下：

替换规则集中在 MCP_REPLACEMENTS 常量，需要时可扩展。

3. 权限映射

Codex 的 sandbox_mode 是沙箱级强制，OpenCode 的 permission 是 allow/ask/deny 三级：

174 个 agent 中 99 个只读、75 个可写。

例外：有 3 个只读 agent 的核心工作离不开执行命令 —— debugger 要看 stack trace 和 失败测试、performance-engineer 要跑测量、security-auditor 要复现问题。它们设成 bash: ask（每条命令仍需你批准），既保持只读语义，又不至于完全不可用。 名单在 READ_ONLY_NEEDS_SHELL 常量里。

字段映射

正文中的 Codex 会被替换为 the parent agent，避免提示词指向另一个产品。

CLI 参数

默认跳过 agent-installer、workflow-orchestrator：它们的 prompt 讲的是 「往 ~/.codex/agents/ 里装文件」，移植到 OpenCode 后语义为空。

对非 GPT 与开源模型的说明

• reasoningEffort 是 GPT 系专属参数。 只有 OpenAI 风格的接口认识它；Claude、Llama、 Mistral、Gemma、GLM、DeepSeek、Qwen 以及多数开源权重模型都会忽略。 默认不再输出，如果你的 provider 支持，再用 --keep-reasoning 恢复。
• 若给特定 agent 钉模型，用 --model-map。值的形式是 provider/model-id，provider 前缀取自你自己的 opencode.json：--model-map=gpt-6.1-sol=<provider>/<model-id>。

已知限制

1. 自动触发很弱（平台机制）。OpenCode 把 subagent 列表以 id: description 拼进 task 工具的 description，只靠文本让模型自行判断。内置 explore 的 description 带具体例句， 更容易被选中。174 个候选会稀释信号 —— 这是 OpenCode 的行为，不是转换问题。 建议要么用 --only 只装常用子集，要么始终 @agent名 手动调用。

2. 常驻上下文成本。全量安装会让 task 工具描述增加约 7.5k token。

3. prompt 同质化。源仓库 174 份 prompt 共用一个模板 （Working mode / Focus on / Quality checks / Return），长度 129/174 落在 1–2k 字符区间， 差异主要在领域词汇。不要期待它们之间有精细分工。

4. browser-debugger 需要 chrome-devtools MCP（默认 localhost:3000/mcp）。 未配置时该 agent 会被加载但缺少工具。

仓库结构

.
├── bin/{cli,lang}.mjs                    # npm 包入口（ocagents / ocagents-lang）
├── tools/
│   ├── install.mjs                       # 安装（系统语言 + 预设）
│   ├── switch-lang.mjs                   # 随时切换 description 语言
│   ├── detect-lang.mjs                   # 语言检测（含回退到英语）
│   ├── validate.mjs                      # 校验产物、译表、预设（CI 用）
│   ├── i18n/{en,zh}.json                 # description 译表，加语言只需加文件
│   ├── codex-subagents-to-opencode.mjs   # 从上游 TOML 重新生成 agents/
│   ├── analyze-subagents.mjs             # 产物分析
│   ├── compare-lang.mjs                  # 中英文 token 成本对比
│   └── verify-load.mjs                   # 验证 OpenCode 能否正确加载
├── presets/{minimal,web,backend}.txt     # 装哪些 agent 的预设名单
├── agents/                                # 174 个 OpenCode agent（英文基准）
├── .github/workflows/validate.yml         # CI
├── package.json
├── README.md                              # English
├── README.zh-CN.md                        # 本文件
└── LICENSE

agents/ 是英文基准版本，可以直接复制到任意 OpenCode 项目使用。 想换描述语言用 switch-lang.mjs，不要手动改。

校验

npm run verify

检查 frontmatter 合法性、mode: subagent、无硬编码 model、权限键有效、prompt 完整且无 Codex 残留、译表与 agent 一一对应、预设引用的 agent 都存在。

CI 在 Node 18 / 20 / 22 上运行，并额外验证「从上游重新生成的结果与提交版本一致」， 防止产物悄悄漂移。

许可证

本仓库的转换脚本与 README 以 MIT 发布。 agents/ 下的内容派生自 VoltAgent/awesome-codex-subagents， 同样为 MIT，版权归原作者及贡献者所有。