mcpField
C
codex-subagents

codex-subagents

github.com/obraAgent 工作流24105 次安装44 周前更新
代码仓库

关于 codex-subagents

codex-subagents 技能通过后台线程将工作交给子 Agent，使主上下文保持精简。适合并行研究、耗时任务和需要隔离上下文的工作，并提供线程等待、查看与归档流程。

主要功能

  1. 01在后台线程启动子 Agent
  2. 02并行运行多个研究任务
  3. 03等待线程完成或查看进度
  4. 04向已停止线程发送后续提示词
  5. 05归档已完成线程并清理旧归档

适用场景

  1. 01并行调查多个 API 或主题
  2. 02将长时间研究移出主上下文
  3. 03等待后台任务完成后继续跟进

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/obra/external-subagents --skill codex-subagents

安装后在 Claude Code 中输入/codex-subagents确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

TODO.md
.gitignore
README.md
.prek.toml
dev/
build.mjs
.editorconfig
.prettierrc
demo-watch.ts
.npmrc
demo-watch-prompt.txt
eslint.config.js
run-prek-install.mjs
package.json
package-lock.json
dev/src/bin/
codex-subagent.ts
dev/src/commands/
archive.ts
log.ts
clean.ts
label.ts
list.ts
status.ts
peek.ts
send.ts
start.ts
wait.ts
watch.ts
dev/src/lib/
backends.ts
controller-id.ts
exec-runner.ts
file-lock.ts

详细介绍

Codex 子 Agent

概述

codex-subagent 会将工作交给后台线程处理，让主上下文保持精简。线程默认以分离模式运行；使用 wait/peek 检查结果。

重要规则：

  1. 不能向正在运行的线程发送消息。发送后续消息前，务必先等待。
  2. 使用 --permissions read-only 或 --permissions workspace-write（不要使用 workspace-read）

如需了解详细工作流文档，请参阅 reference/workflow.md。

适用场景

情况子 Agent 的帮助
并行研究任务多个线程同时运行
上下文会变得臃肿研究内容保留在线程中，不占用主上下文
长时间运行的工作分离执行，稍后检查

不要用于：快速的即时问题、需要紧密依赖当前状态的工作。

核心工作流

1. start with --prompt    (inline text or stdin)
2. wait/peek → check result
3. send → resume with follow-up (ONLY after thread stops)
4. archive/clean → lifecycle management

运行中线程规则

你不能向正在运行的线程发送消息。 这是最常见的错误。

# WRONG - thread might still be running
echo "followup" | codex-subagent send thread-abc --prompt -

# RIGHT - wait first, then send
codex-subagent wait --threads thread-abc
echo "followup" | codex-subagent send thread-abc --prompt -

可恢复状态：completed、failed、stopped、waiting

快速参考

命令用途关键标志
start启动新线程--role、--permissions、--prompt、--label、-w
send恢复已停止的线程<thread-id>、--prompt、-w
peek读取最新的未查看消息<thread-id>、--save-response
log完整历史记录<thread-id>、--tail、--json
status线程摘要<thread-id>
wait阻塞，直到线程停止--threads、--labels、--all、--follow-last
list显示线程--status、--label、--role
archive将已完成的线程移至归档--completed、--yes、--dry-run
clean删除旧归档--older-than-days、--yes

提示词输入：简单提示词使用 --prompt "text"，--prompt - 从标准输入读取（用于多行内容），文件使用 -f/--prompt-file

位置线程 ID：peek abc123 的作用与 peek -t abc123 相同

常见模式

简单的行内提示词
codex-subagent start --role researcher --permissions read-only \
  --label "quick-task" --prompt "List all exported functions in src/lib/"
多行提示词（heredoc）
cat <<'EOF' | codex-subagent start --role researcher --permissions read-only --label "auth-research" --prompt -
Research authentication patterns in this codebase:
1. Find all auth-related files
2. Document the auth flow
3. Note any security concerns
EOF
并行研究
# Launch multiple researchers
cat <<'EOF' | codex-subagent start --role researcher --permissions read-only --label "API: Stripe" --prompt -
Research Stripe API authentication methods and best practices
EOF

cat <<'EOF' | codex-subagent start --role researcher --permissions read-only --label "API: Twilio" --prompt -
Research Twilio API authentication methods and best practices
EOF

# Wait for all, see results
codex-subagent wait --labels "API:" --follow-last
阻塞任务
# -w blocks until complete (may take minutes)
cat <<'EOF' | codex-subagent start --role researcher --permissions read-only --prompt - -w --save-response result.txt
Analyze error handling patterns in src/
EOF
cat result.txt

警告：-w 会一直阻塞，直到 Agent 运行结束。对于长时间运行的任务，建议使用分离模式并配合 wait --follow-last。

清理旧工作
# Two-phase: archive completed, then clean old archives
codex-subagent archive --completed --yes
codex-subagent clean --older-than-days 30 --yes

故障排除

问题原因修复方法
"profile does not exist"权限错误使用 read-only 或 workspace-write（不要使用 workspace-read）
"not resumable" 错误线程仍在运行先执行 wait，然后再执行 send
"different controller"会话错误使用 --controller-id 或检查 list
线程消失已归档检查归档目录或重新运行任务

检查清单

  • start 包含 --role、--permissions、--prompt 和 --label
  • 权限为 read-only 或 workspace-write
  • send 前先执行 wait（绝不要向正在运行的线程发送消息）
  • 使用 --save-response 或 peek 保存结果

评论

支持 Markdown