aaaaqwq/codex-cc-guide

ACP 调用 Claude Code / Codex 写代码指南

核心：sessions_spawn + runtime: "acp"

在 OpenClaw 里，agent 可以直接用 sessions_spawn 调起 Claude Code 或 Codex，写代码像发指令一样简单。

最常用：Claude Code（已装在 /usr/bin/claude）

sessions_spawn({
  task: "用 TypeScript 重构 ~/project/src/api.ts，加入错误处理和类型定义",
  runtime: "acp",
  agentId: "claude",        // 或 "claude-code"
  label: "重构-api",
  mode: "run",              // run=一次性，session=持久会话
  cleanup: "delete"         // 完成后删除 session
})

Codex（需要额外配置）

sessions_spawn({
  task: "写一个 Python FastAPI CRUD 接口",
  runtime: "acp",
  agentId: "codex",
  model: "openai/gpt-5.4",
  label: "fastapi-crud"
})

两种模式：一次性 vs 持久会话

| 模式 | 参数 | 适用场景 | |------|------|---------| | 一次性 | mode: "run" | 单个任务，完成即删，最省资源 | | 持久会话 | mode: "session" | 多步骤迭代、需要上下文累积 |

// 一次性：适合简单任务
sessions_spawn({
  task: "在 /tmp 创建一个 React 组件 Counter.tsx",
  runtime: "acp",
  agentId: "claude",
  mode: "run"
})

// 持久会话：适合复杂项目
sessions_spawn({
  task: "继续上次的工作，修复登录页面的 bug",
  runtime: "acp",
  agentId: "claude",
  mode: "session",
  label: "react-project"
})

持久会话 + thread：绑定到 Telegram 话题

sessions_spawn({
  task: "用 Next.js 14 App Router 重构整个电商前端",
  runtime: "acp",
  agentId: "claude",
  thread: true,              // 绑定到当前 Telegram thread
  mode: "session",
  label: "nextjs重构"
})

完成后 Claude Code 的输出会自动推送到 Telegram thread 里。

聊天指令（人类直接用）

在 Telegram 发这些指令即可：

/acp spawn claude 帮我写一个 Docker Compose 文件

/acp spawn codex 用 Rust 写一个 http server

/acp status   查看当前 ACP 会话状态

/acp cancel    取消当前任务

/acp close     关闭会话

小code 团队标准工作流

场景：Daniel 让你写一个 API

错误做法（慢、资源浪费）：

自己开模型 → 写代码 → 测试 → 修 bug → 循环

正确做法（用 ACP + Claude Code）：

1. 理解需求，确定技术栈和文件位置
2. sessions_spawn 调起 Claude Code 一次性任务
3. Claude Code 完成后你负责 review
4. 有问题再调一次 Claude Code 修

// 示例：Daniel 让小code 写一个用户认证 API
sessions_spawn({
  task: `在 ~/clawd/projects/api/ 下创建用户认证模块：
  - POST /auth/login（邮箱+密码，返回 JWT）
  - POST /auth/register（邮箱+密码+昵称）
  - GET /auth/me（返回当前用户信息，需带 Bearer token）
  - 使用 Python FastAPI + SQLite
  - 密码用 bcrypt 哈希
  - JWT secret 从环境变量 AUTH_SECRET 读取
  - 代码要可以运行，有完整的错误处理`,
  runtime: "acp",
  agentId: "claude",
  label: "auth-api"
})

关键规则

1. 任务描述要具体：包含文件路径、技术栈、具体要求
2. 清理 session：cleanup: "delete" 避免垃圾积累
3. 并发控制：最多同时跑 3 个 ACP 会话
4. Review 是你的活：Claude Code 写完你要检查，不是直接交付

错误排查

| 症状 | 检查项 | |------|--------| | sessions_spawn 没反应 | 确认 acp.enabled: true 在 openclaw.json | | Claude Code 报错 "not found" | 确认 /usr/bin/claude 存在 | | 会话卡住 | /acp cancel 然后重试 | | 输出没推送到 Telegram | 确认 thread: true 且在支持 thread 的 channel |

配置文件参考

{
  acp: {
    enabled: true,
    defaultAgent: "claude",
    allowedAgents: ["claude", "codex", "gemini-cli"]
  }
}