coding-agent-common

核心用法

coding-agent 是一套通用编码代理封装方案，支持 Codex（OpenAI）、Claude Code（Anthropic）、OpenCode（开源）三种主流工具。通过 exec 指令调用，支持 PTY 交互模式、后台并行执行及进程监控。

典型工作流：
1. 快速原型：codex exec '添加登录功能'（需 pty:true）
2. 复杂重构：claude --permission-mode bypassPermissions --print '重构认证模块'
3. 多任务并行：结合 Git Worktree 创建独立工作区，启动多个后台代理同时处理不同 issue
4. 监控管理：通过 process 系列指令（list/log/poll/kill）追踪进度

显著优点

• 灵活适配：三引擎可选，Codex 速度快、Claude 理解力强、OpenCode 轻量开源
• 后台执行：支持 background:true 长时间任务不阻塞主会话
• 安全可控：--full-auto 沙箱自动批准、--yolo 极速模式、权限模式分级
• Git Worktree 集成：天然支持并行分支开发，避免代码冲突
• 进度透明：内置里程碑通知机制，关键节点主动反馈

潜在局限

• 环境依赖：Codex 强制要求 Git 目录，无 git 需手动初始化临时目录
• PTY 配置复杂：Codex/OpenCode/Pi 需 pty:true，Claude 不需要，易混淆
• 权限风险：--yolo 无沙箱模式存在文件误删风险；~/.openclaw/ 目录启动可能泄露敏感配置
• Claude 参数易错：早期版本 --dangerously-skip-permissions 已废弃，需使用 --permission-mode bypassPermissions --print

适合人群

• 中大型项目开发者，需批量处理 issue/PR 重构
• 需要并行开发多条分支的 Tech Lead
• 希望自动化代码审查、测试补全的 DevOps 工程师

常规风险

• 敏感信息泄露：代理可能读取 .env、密钥文件，建议隔离工作目录
• 代码破坏性变更：--yolo 模式无确认，生产环境慎用
• 僵尸进程：后台任务异常退出时，需手动 process action:kill 清理
• 模型幻觉：复杂架构描述可能生成不符合项目规范的代码，需人工审查 PR

核心用法

coding-agent 是一个纯文档型技能，本身不执行代码，而是提供完整的编码代理使用指南和命令模板。它封装了 Codex（OpenAI）、Claude Code（Anthropic）、OpenCode（开源）三种主流编码代理的标准化调用方式，支持快速原型开发、大型代码库重构、Bug 修复、代码审查等五大核心场景。

用户通过 exec 工具调用外部 CLI，配合 process 工具进行后台任务管理。关键配置包括：Codex/OpenCode/Pi 需要 pty:true 参数以支持交互式终端；Claude Code 使用 --print 模式实现非交互式输出。技能强调始终指定 workdir 限定工作范围，避免代理读取无关文件。

显著优点

多代理生态整合：一站式覆盖当前三大主流编码代理，提供清晰的选择指南（Codex 快速原型、Claude Code 复杂重构、OpenCode 轻量任务），降低用户决策成本。

生产级工作流设计：内置 Git Worktree 并行开发模式，支持多 Issue 同时处理；提供后台任务监控、进度通知、会话管理等完整生命周期管理方案。

安全最佳实践完备：明确警告 --yolo 无沙箱模式的危险性，推荐 --full-auto 作为平衡效率与安全的方案；规定敏感目录操作规范（禁止在 ~/.openclaw/ 启动代理）。

提示词工程指导：包含任务描述正反面示例，教导用户编写包含技术栈、功能清单、验收标准的结构化需求，显著提升代理输出质量。

潜在缺点与局限性

外部依赖刚性：必须预先安装 claude/codex/opencode/pi 等二进制工具，且 Codex 强制要求 git 目录，无版本控制的项目需临时 git init，增加使用门槛。

无原生 IDE 集成：纯 CLI 调用模式，缺乏 VS Code、JetBrains 等主流 IDE 的插件化集成，开发者需在终端与编辑器间频繁切换。

成本不可控风险：调用 OpenAI/Anthropic API 可能产生高额 token 消耗，技能未内置预算监控或用量预警机制，长时间后台任务存在费用失控隐患。

平台锁定倾向：命令模板深度绑定 OpenClaw 生态的 process 工具集，迁移至其他 Agent 框架需改写监控逻辑。

适合的目标群体

• 全栈开发者：需要快速搭建原型或并行处理多个技术债务
• 技术团队 Lead：建立标准化代码审查流程，统一团队编码规范
• 开源贡献者：利用 Git Worktree 模式同时处理多个 PR 或 Issue
• AI 辅助编程早期采用者：希望系统对比 Codex 与 Claude Code 的能力差异

使用风险

性能层面：后台长时间任务可能占用大量 CPU/内存资源，并行启动多个代理时需注意系统负载；pty 模式下的交互式进程可能因网络波动导致假死。

安全合规层面：--full-auto 模式自动批准工作区变更，存在意外覆盖生产配置的风险；--yolo 模式无沙箱隔离，恶意依赖项可能污染全局环境。

操作风险：process action:kill 强制终止可能导致 git 状态不一致或临时文件残留；多 Worktree 并行时分支管理混乱可能引发代码冲突。

供应商风险：依赖 OpenAI、Anthropic 的 API 可用性与定价策略，服务中断或涨价将直接影响工作流连续性。