核心用法
Coding Agent 是一种通过 bash 工具在后台运行 AI 编码代理（Codex、Claude Code、Pi、OpenCode）的技能，专门用于处理复杂的开发任务。使用时必须开启 pty:true 参数，因为编码代理是交互式终端应用，需要伪终端才能正常工作。
典型工作流程：
1. 快速任务：bash pty:true command:"codex exec '你的任务'"
2. 长时间后台任务：bash pty:true workdir:~/project background:true command:"codex --yolo '重构任务'"，然后通过 process action:log sessionId:XXX 监控进度
3. PR 审查：在临时目录克隆仓库，使用 codex review --base origin/main 进行安全审查
4. 并行批量处理：通过 git worktree 创建多个工作目录，同时启动多个代理处理不同 Issue
关键参数组合：
workdir：限定代理的工作范围，防止读取无关文件background+pty：后台运行并保持终端交互能力timeout：设置任务超时防止无限挂起
显著优点
1. 多代理支持：兼容 Codex（OpenAI）、Claude Code（Anthropic）、Pi、OpenCode 四种主流 AI 编码工具
2. 真正的并行能力：可同时启动多个后台会话处理批量 PR 审查或多 Issue 修复
3. 安全的隔离机制：PR 审查强制要求使用临时目录或 git worktree，避免污染主仓库
4. 精细的过程控制：通过 process 工具可实现查看日志、发送输入、终止会话等完整生命周期管理
5. 灵活的执行模式：支持 --full-auto（沙箱自动批准）、--yolo（无沙箱最快模式）、exec（一次性执行）等多种模式
潜在缺点与局限性
1. 外部依赖重：需要本地安装 claude、codex、opencode 或 pi 等二进制工具，且 Codex 要求必须在 git 仓库内运行
2. PTY 复杂性：虽然必要，但伪终端模式增加了调试难度，输出解析不如纯文本可靠
3. 安全风险：--yolo 模式无沙箱、无审批，文档明确标注为"最危险"模式；代理可能访问敏感文件（如 soul.md）
4. 资源消耗：并行运行多个编码代理对计算资源要求较高
5. 状态同步挑战：后台任务需要显式监控，用户可能只看到"Agent failed before reply"而缺乏上下文
适合人群
- 中大型项目开发者：需要处理大规模重构、多文件改动的复杂任务
- 开源维护者：需要批量审查 PR、并行处理多个 Issue
- DevOps/平台工程师：需要自动化代码审查、持续集成中的智能代码分析
- 探索性编程场景：快速原型开发、实验性功能构建
不适合：简单单行修复（直接用编辑器）、纯代码阅读（用 read 工具）、以及任何在 ~/clawd 工作目录的操作（明确禁止）
常规风险
| 风险类型 | 具体表现 | 缓解措施 |
|---------|---------|---------|
| 执行安全风险 | `--yolo` 模式无沙箱，代理可直接修改系统 | 优先使用 `--full-auto`，敏感操作加人工确认 |
| 信息泄露风险 | 代理可能读取 soul.md 等敏感文档获取"奇怪想法" | 严格使用 `workdir` 限定范围，禁止在 `~/.openclaw/` 启动代理 |
| 资源耗尽风险 | 并行会话过多导致系统负载过高 | 合理控制并行数量，设置 `timeout` 参数 |
| 状态不可见风险 | 后台任务失败时用户缺乏上下文 | 遵循进度更新规范：启动通知、里程碑汇报、完成/失败明确告知 |
| 仓库污染风险 | PR 审查时误修改主仓库 | 强制使用临时目录或 git worktree 隔离 |
文档强调：若代理失败或挂起，应重新启动或询问用户方向，禁止静默接管手动编写补丁，这是 Orchestrator 模式的核心约束。