name: coding-agent description: “通过后台进程将编码任务委托给 Codex、Claude Code 或 Pi 智能体。适用于：(1) 构建/创建新功能或应用程序，(2) 审查 PR（在临时目录中生成），(3) 重构大型代码库，(4) 需要文件探索的迭代编码。不适用于：简单的单行修复（直接编辑即可）、阅读代码（使用读取工具）或在 ~/clawd 工作区中的任何工作（切勿在此处生成智能体）。需要一个支持 pty:true 的 bash 工具。” metadata: { “openclaw”: { “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 工具参数
| 参数 | 类型 | 描述 |
|---|---|---|
command |
字符串 | 要运行的 shell 命令 |
pty |
布尔值 | 用于编码智能体！ 为交互式 CLI 分配伪终端 |
workdir |
字符串 | 工作目录（智能体仅看到此文件夹的上下文） |
background |
布尔值 | 在后台运行，返回用于监控的 sessionId |
timeout |
数字 | 超时时间（秒）（到期时终止进程） |
elevated |
布尔值 | 在主机上运行而不是沙箱中（如果允许） |
进程工具操作（用于后台会话）
| 操作 | 描述 |
|---|---|
list |
列出所有运行中/最近的会话 |
poll |
检查会话是否仍在运行 |
log |
获取会话输出（可选偏移量/限制） |
write |
向 stdin 发送原始数据 |
submit |
发送数据 + 换行符（如键入并按 Enter） |
send-keys |
发送键令牌或十六进制字节 |
paste |
粘贴文本（可选括号模式） |
kill |
终止会话 |
快速开始：一次性任务
对于快速提示/聊天，创建一个临时 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 😅）。
Codex CLI
模型： gpt-5.2-codex 是默认值（在 ~/.codex/config.toml 中设置）
标志
| 标志 | 效果 |
|---|---|
exec "prompt" |
一次性执行，完成后退出 |
--full-auto |
沙箱化但在工作区中自动批准 |
--yolo |
无沙箱，无批准（最快，最危险） |
构建/创建
# 快速一次性（自动批准）- 记住 PTY！
bash pty:true workdir:~/project command:"codex exec --full-auto '构建深色模式切换'"
# 后台进行较长工作
bash pty:true workdir:~/project background:true command:"codex --yolo '重构认证模块'"
审查 PR
⚠️ 关键：切勿在 OpenClaw 自己的项目文件夹中审查 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
# 使用 PTY 以获得正确的终端输出
bash pty:true workdir:~/project command:"claude '你的任务'"
# 后台
bash pty:true workdir:~/project background:true command:"claude '你的任务'"
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
⚠️ 规则
- 始终使用 pty:true - 编码智能体需要终端！
- 尊重工具选择 - 如果用户要求使用 Codex，就使用 Codex。
- 协调器模式：不要自己手动编写补丁。
- 如果智能体失败/挂起，重新启动它或向用户询问方向，但不要默默接管。
- 保持耐心 - 不要因为智能体“慢”而终止会话
- 使用 process:log 监控 - 在不干扰的情况下检查进度
- 构建时使用 --full-auto - 自动批准更改
- 审查时使用普通模式 - 不需要特殊标志
- 并行是可以的 - 为批量工作同时运行多个 Codex 进程
- 切勿在 ~/clawd/ 中启动 Codex - 它会读取你的灵魂文档并对组织架构产生奇怪的想法！
- 切勿在 ~/Projects/openclaw/ 中检出分支 - 那是 LIVE OpenClaw 实例！
进度更新（关键）
当你在后台生成编码智能体时，让用户随时了解情况。
- 启动时发送 1 条简短消息（正在运行什么 + 在哪里）。
- 然后仅在发生变化时再次更新：
- 完成一个里程碑（构建完成，测试通过）
- 智能体提问 / 需要输入
- 遇到错误或需要用户操作
- 智能体完成（包括更改了什么 + 在哪里）
- 如果你终止了一个会话，立即说明你终止了它以及原因。
这可以防止用户只看到“代理在回复前失败”而不知道发生了什么。
完成时自动通知
对于长时间运行的后台任务，在你的提示后附加一个唤醒触发器，以便在智能体完成时立即通知 OpenClaw（而不是等待下一个心跳）：
... 你的任务。
当完全完成后，运行此命令通知我：
openclaw system event --text "完成：[简要总结构建的内容]" --mode now
示例：
bash pty:true workdir:~/project background:true command:"codex --yolo exec '为待办事项构建 REST API。
当完全完成后，运行：openclaw system event --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 对俏皮的提示反应良好。让它写一首关于给太空龙虾当副手的俳句，得到了：“第二把交椅，我编码 / 太空龙虾定节奏 / 键光闪烁，我跟随” 🦞