核心用法
coding-agent 是一套多代理代码执行框架，通过 bash 工具调用 Codex、Claude Code、Pi 或 OpenCode 完成复杂开发任务。核心模式为 workdir + background + pty 三要素组合：指定工作目录聚焦上下文、后台运行释放主线程、PTY 分配保证交互式 CLI 正常运作。
关键执行差异：
- Codex/Pi/OpenCode：必须启用
pty:true，使用codex exec "prompt"或pi "prompt"等命令 - Claude Code：禁用 PTY，改用
--print --permission-mode bypassPermissions参数实现非交互式执行
典型场景：
1. 功能构建：codex exec --full-auto 'Build dark mode toggle' 自动审批变更
2. PR 审查：临时目录克隆仓库，避免污染主工作区，支持 git worktree 实现并行多 PR 审查
3. 大规模重构：后台会话 + 进程监控（process action:log/poll/kill），支持长时间任务
4. 批量修复：多 git worktree 并行启动代理，分别处理不同 issue 后独立提 PR
进程管理：通过 background:true 获取 sessionId，后续可用 process 工具执行 list/poll/log/write/submit/kill 等操作。支持 openclaw system event 唤醒通知实现任务完成即时告警。
显著优点
- 多代理兼容：统一封装 OpenAI Codex、Anthropic Claude Code、Pi 等主流编码代理的差异调用
- 并行执行：可同时启动数十个后台会话处理批量 PR 审查或 issue 修复
- 安全隔离：强制要求 PR 审查使用临时目录或 git worktree，防止污染生产代码
- 精细监控：完整的进程生命周期管理，支持非侵入式日志查看与交互式输入
- 自动通知：内置 OpenClaw 事件唤醒机制，长任务完成后秒级通知
潜在局限
- 环境依赖重：需预装
claude/codex/pi/opencode等 CLI 工具，且 Codex 强制要求 git 仓库上下文 - PTY 配置复杂：不同代理的 PTY 要求相反（Codex 需开启、Claude 需关闭），易配置错误导致挂起或退出
- 安全风险敞口：
--yolo模式无沙箱无审批，适合可信代码但存在误操作风险；--dangerously-skip-permissions与 PTY 组合会导致异常退出 - 资源消耗：并行大量代理时内存与 API 调用成本显著上升
- Claude Code 限制：禁用 PTY 后无法使用交互式确认，必须通过
bypassPermissions全权委托
适合人群
- 需要批量处理 GitHub PR 审查的维护者
- 进行大规模代码重构或新功能开发的全栈开发者
- 使用多种 AI 编码工具并追求统一工作流的团队
- 熟悉 bash 与 git 工作树、能接受后台异步协作模式的高级用户
常规风险
| 风险类型 | 具体表现 | 缓解措施 |
|---------|---------|---------|
| **权限失控** | `--yolo`/`bypassPermissions` 模式下代理可任意修改文件系统 | 仅在隔离环境使用，避免生产目录 |
| **代码污染** | 未使用临时目录直接在工作区执行 PR 审查 | 强制 `mktemp -d` 或 `git worktree` 隔离 |
| **敏感信息泄露** | 在 `~/.openclaw/` 或 `~/clawd` 目录启动代理会读取配置文档 | 绝对禁止在上述路径 spawn 代理 |
| **进程僵尸** | 后台任务异常退出未清理，占用资源 | 定期 `process action:list` 检查，设置合理 `timeout` |
| **API 成本** | 并行多代理导致 Token 消耗激增 | 任务分片，监控用量，避免无限制 `--yolo` 并发 |
| **会话死锁** | 代理等待用户输入但后台模式无交互 | 使用 `auto-notify` 唤醒机制，或前置确认无交互需求 |
特别警告：Claude Code 的 --dangerously-skip-permissions 与 PTY 组合会触发确认对话框后立即退出，必须使用 --print 模式替代。