名称： coding-agent
描述： 通过后台进程运行 Codex CLI、Claude Code、OpenCode 或 Pi 编程助手，实现程序化控制。
元数据： {"moltbot":{"emoji":"🧩","requires":{"anyBins":["claude","codex","opencode","pi"]}}}

编程助手（首选 Bash）

所有编程助手任务均使用 Bash（可选后台模式）。简单高效。

⚠️ 必须启用 PTY 模式！

编程助手（Codex、Claude Code、Pi）是交互式终端应用程序，需要伪终端（PTY）才能正常工作。没有 PTY，你会得到损坏的输出、丢失颜色，或者助手可能挂起。

运行编程助手时，务必使用 pty:true：

# ✅ 正确 - 使用 PTY
bash pty:true command:"codex exec '你的提示'"

# ❌ 错误 - 没有 PTY，助手可能出错
bash command:"codex exec '你的提示'"

Bash 工具参数

进程工具操作（用于后台会话）

快速开始：一次性任务

对于快速提示/聊天，创建一个临时 git 仓库并运行：

# 快速聊天（Codex 需要 git 仓库！）
SCRATCH=$(mktemp -d) && cd $SCRATCH && git init && codex exec "你的提示"

# 或者在真实项目中 - 使用 PTY！
bash pty:true workdir:~/Projects/myproject command:"codex exec '为 API 调用添加错误处理'"

为什么需要 git init？ Codex 拒绝在受信任的 git 目录外运行。创建临时仓库可以解决临时工作的这个问题。

标准模式：workdir + background + pty

对于较长的任务，使用带 PTY 的后台模式：

# 在目标目录中启动助手（使用 PTY！）
bash pty:true workdir:~/project background:true command:"codex exec --full-auto '构建一个贪吃蛇游戏'"
# 返回用于跟踪的 sessionId

# 监控进度
process action:log sessionId:XXX

# 检查是否完成
process action:poll sessionId:XXX

# 发送输入（如果助手提问）
process action:write sessionId:XXX data:"y"

# 提交并换行（类似输入 "yes" 后按 Enter）
process action:submit sessionId:XXX data:"yes"

# 必要时终止
process action:kill sessionId:XXX

为什么 workdir 很重要： 助手在指定目录中启动，不会读取无关文件（比如你的 soul.md 😅）。

备用策略

当主要助手达到限制时，按顺序回退：

需要回退的迹象：
- "你已达到使用限制"
- 速率限制 / 429 错误
- 模型过载消息

Codex CLI

模型： gpt-5.2-codex 是默认模型（在 ~/.codex/config.toml 中设置）

标志

构建/创建

# 快速一次性（自动批准）- 记住 PTY！
bash pty:true workdir:~/project command:"codex exec --full-auto '构建一个深色模式切换器'"

# 后台运行处理较长任务
bash pty:true workdir:~/project background:true command:"codex --yolo '重构认证模块'"

审查 PR

⚠️ 关键：切勿在 Moltbot 自己的项目文件夹中审查 PR！
克隆到临时文件夹或使用 git worktree。

# 克隆到临时文件夹进行安全审查
REVIEW_DIR=$(mktemp -d)
git clone https://github.com/user/repo.git $REVIEW_DIR
cd $REVIEW_DIR && gh pr checkout 130
bash pty:true workdir:$REVIEW_DIR command:"codex review --base origin/main"
# 完成后清理：删除 $REVIEW_DIR

# 或使用 git worktree（保持主分支完整）
git worktree add /tmp/pr-130-review pr-130-branch
bash pty:true workdir:/tmp/pr-130-review command:"codex review --base main"

批量 PR 审查（并行大军！）

# 首先获取所有 PR 引用
git fetch origin '+refs/pull/*/head:refs/remotes/origin/pr/*'

# 部署大军 - 每个 PR 一个 Codex（全部使用 PTY！）
bash pty:true workdir:~/project background:true command:"codex exec '审查 PR #86。git diff origin/main...origin/pr/86'"
bash pty:true workdir:~/project background:true command:"codex exec '审查 PR #87。git diff origin/main...origin/pr/87'"

# 监控所有进程
process action:list

# 将结果发布到 GitHub
gh pr comment <PR#> --body "<审查内容>"

Claude Code

当 Codex 不可用时的备用方案。

# 非交互式
claude -p "为 src/api.ts 添加错误处理"
claude -p --permission-mode acceptEdits "修复这个 bug"

# 交互式（使用 PTY）
bash pty:true workdir:~/project command:"claude '你的任务'"

详细文档： 参见 references/claude-code.md

Gemini CLI

具有不同模型系列的备用方案。

# 非交互式（一次性）
gemini "为 src/api.ts 添加错误处理"
gemini -y "构建一个 REST API"  # yolo 模式

# 交互式（使用 PTY）
bash pty:true workdir:~/project command:"gemini -i '你的任务'"

详细文档： 参见 references/gemini-cli.md

OpenCode

bash pty:true workdir:~/project command:"opencode run '你的任务'"

Pi 编程助手

# 安装：npm install -g @mariozechner/pi-coding-agent
bash pty:true workdir:~/project command:"pi '你的任务'"

# 非交互模式（仍推荐 PTY）
bash pty:true command:"pi -p '总结 src/'"

# 不同的提供商/模型
bash pty:true command:"pi --provider openai --model gpt-4o-mini -p '你的任务'"

注意： Pi 现已启用 Anthropic 提示缓存（PR #584，于 2026 年 1 月合并）！

使用 git worktrees 并行修复问题

要并行修复多个问题，请使用 git worktrees：

# 1. 为每个问题创建工作树
git worktree add -b fix/issue-78 /tmp/issue-78 main
git worktree add -b fix/issue-99 /tmp/issue-99 main

# 2. 在每个工作树中启动 Codex（后台 + PTY！）
bash pty:true workdir:/tmp/issue-78 background:true command:"pnpm install && codex --yolo '修复问题 #78：<描述>。提交并推送。'"
bash pty:true workdir:/tmp/issue-99 background:true command:"pnpm install && codex --yolo '修复问题 #99：<描述>。提交并推送。'"

# 3. 监控进度
process action:list
process action:log sessionId:XXX

# 4. 修复后创建 PR
cd /tmp/issue-78 && git push -u origin fix/issue-78
gh pr create --repo user/repo --head fix/issue-78 --title "fix: ..." --body "..."

# 5. 清理
git worktree remove /tmp/issue-78
git worktree remove /tmp/issue-99

tmux 编排（替代方案）

对于高级的多助手控制，使用 tmux 技能 而不是 bash 后台模式。

何时使用 tmux 与 bash 后台

快速示例

SOCKET="${TMPDIR:-/tmp}/coding-agents.sock"

# 为并行工作创建会话
tmux -S "$SOCKET" new-session -d -s agent-1 -c /tmp/worktree-1
tmux -S "$SOCKET" new-session -d -s agent-2 -c /tmp/worktree-2

# 启动助手
tmux -S "$SOCKET" send-keys -t agent-1 "codex --yolo '修复问题 #1'" Enter
tmux -S "$SOCKET" send-keys -t agent-2 "claude '修复问题 #2'" Enter

# 监控（检查 shell 提示符以检测完成情况）
tmux -S "$SOCKET" capture-pane -p -t agent-1 -S -100

# 附加以实时查看
tmux -S "$SOCKET" attach -t agent-1

助手分叉

在助手之间转移上下文（例如，用 Codex 计划，用 Claude 执行）：

# 从当前助手捕获上下文
CONTEXT=$(tmux -S "$SOCKET" capture-pane -p -t planner -S -500)

# 分叉到新助手并传递上下文
tmux -S "$SOCKET" new-session -d -s executor
tmux -S "$SOCKET" send-keys -t executor "claude -p '基于此计划：$CONTEXT

执行步骤 1。'" Enter

完整文档： 参见 tmux 技能了解套接字约定、等待文本助手和清理。

⚠️ 规则

1. 始终使用 pty:true - 编程助手需要终端！
2. 尊重工具选择 - 如果用户要求使用 Codex，就使用 Codex。
   • 编排器模式：不要自己手动编写补丁。
   • 如果助手失败/挂起，重新启动它或询问用户指示，但不要默默接管。
3. 保持耐心 - 不要因为助手“慢”而终止会话
4. 使用 process:log 监控 - 在不干扰的情况下检查进度
5. 构建时使用 --full-auto - 自动批准更改
6. 审查时使用 vanilla - 不需要特殊标志
7. 并行运行是可以的 - 为批量工作同时运行多个 Codex 进程
8. 切勿在 ~/clawd/ 中启动 Codex - 它会读取你的灵魂文档并对组织架构产生奇怪的想法！
9. 切勿在 ~/Projects/moltbot/ 中检出分支 - 那是 LIVE 的 Moltbot 实例！

进度更新（关键）

当你在后台生成编程助手时，请让用户了解情况。

• 启动时发送 1 条简短消息（正在运行什么 + 在哪里）。
• 然后仅在情况发生变化时再次更新：
• 一个里程碑完成（构建完成，测试通过）
• 助手提问 / 需要输入
• 遇到错误或需要用户操作
• 助手完成（包括更改了什么 + 在哪里）
• 如果你终止了一个会话，立即说明你终止了它以及原因。

这可以防止用户只看到“助手在回复前失败”而不知道发生了什么。

完成时自动通知

对于长时间运行的后台任务，在你的提示末尾附加一个唤醒触发器，以便在助手完成时立即通知 Moltbot（而不是等待下一个心跳）：

... 你的任务。

当完全完成后，运行此命令通知我：
moltbot gateway wake --text "完成：[简要总结构建了什么]" --mode now

示例：

bash pty:true workdir:~/project background:true command:"codex --yolo exec '构建一个待办事项 REST API。

当完全完成后，运行：moltbot gateway wake --text \"完成：构建了具有 CRUD 端点的待办事项 REST API\" --mode now'"

这会触发一个立即唤醒事件 — Skippy 在几秒内收到通知，而不是 10 分钟。

经验总结（2026 年 1 月）

• PTY 至关重要： 编程助手是交互式终端应用。没有 pty:true，输出会损坏或助手会挂起。
• 需要 Git 仓库： Codex 不会在 git 目录外运行。对于临时工作，使用 mktemp -d && git init。
• exec 是你的朋友： codex exec "prompt" 运行并干净退出 - 非常适合一次性任务。
• submit 与 write： 使用 submit 发送输入 + 换行，write 发送原始数据（无换行）。
• 俏皮话有效： Codex 对有趣的提示反应良好。让它写一首关于给太空龙虾当副手的俳句，得到了："副手，我编码 / 太空龙虾定节奏 / 键光闪烁，我跟随" 🦞