| name | use-claude-code |
| description | 使用 Claude Code 执行编程、文件操作、终端任务等。支持两种模式：
(1) 一次性研究模式：Claude Code 完成一轮任务后通过 streamTo=parent 将结果回流到当前 OpenClaw 会话（仅限有 parent session 的上下文，即从 OpenClaw agent 内部发起）；
(2) 持续协作模式：通过 direct acpx 维持独立 Claude Code 会话，结果通过 stop hook 回流到发起渠道（聊天渠道、agent 均适用）。
触发词：用 claude code / 让 claude code / 交给 claude code / 帮我写代码 / 帮我改代码 / 执行命令
|
| metadata | {"openclaw":{"emoji":"💻"}} |
Use Claude Code
职责
本 skill 负责将适合 Claude Code 处理的任务委托给 Claude Code，并根据任务类型选择正确模式。
适合委托的任务类型：
- 编写、修改、调试代码
- 读写文件、目录操作
- 执行终端命令、脚本
- Git 操作
- 需要访问本地文件系统的任何任务
- 需要独立研究或长期协作的本地工程任务
核心原则
- 一次性研究模式 与 持续协作模式 是两种不同模式，不要混用。
- 两种模式的实现路径和回流机制完全不同：
- 研究模式：ACP run +
streamTo=parent，结果直接回到当前会话（仅限有 parent session 的上下文）
- 持续协作模式：direct acpx（因为聊天渠道不支持线程绑定，ACP session/thread 路不通），结果通过 stop hook 回流
- agentId 说明：ACP run 调用时用
"claude"（ACP harness 实际 id），不是 "claude-code"（OpenClaw agents.list 包装名）
两种推荐模式
模式 A：一次性研究模式
适用于：
- "让 Claude Code 研究一下这个问题"
- "让 Claude Code 看完后把结论带回来"
- "用 Claude Code 分析这个 bug，然后告诉我"
- 仅限从 OpenClaw agent 上下文内发起（有 parent session）
推荐调用：
{
"runtime": "acp",
"agentId": "claude",
"mode": "run",
"thread": false,
"streamTo": "parent"
}
特点：
- Claude Code 在一次 run-mode ACP 子会话中完成任务
- 进度与结果通过标准 ACP parent-return 回到当前 OpenClaw 会话
- 从聊天渠道直接发起时无 parent session，此模式不适用，应改用持续协作模式
模式 B：持续协作模式
适用于：
- "开个 Claude Code 线程长期做"
- "给 Claude Code 一个独立会话继续做这个项目"
- "后面我还要继续跟它聊"
- 从聊天渠道（Telegram、QQBot 等）发起的任何长期协作
实现方式：direct acpx（ACP session/thread 因聊天渠道不支持线程绑定而不可用）
acpx claude sessions ensure --name <sessionName>
echo "<用户消息>" | acpx claude prompt --session <sessionName> --file -
特点：
sessionName 由 OpenClaw 维护，代管会话身份，全程保持不变- 每轮任务完成后，Claude Code 通过 stop hook 把结果推回发起渠道
- stop hook 是此模式的结果回流主链路
sessionName 命名规范
持续协作模式中，sessionName 必须以 oc- 开头，便于在 acpx session 列表中识别 OpenClaw 调起的会话。
- ✅ 正确：
oc-<userId>-<timestamp>、oc-<openclawSessionId>
- ❌ 错误：任何不以
oc- 开头的名称
注意：stop.js hook 收到的是 Claude Code 内部的 session_id（UUID），与 acpx 的 --session <name> 是不同字段，无法在 hook 里按 name 过滤。全量回调均会送达 OpenClaw。
执行流程
阶段一：识别模式
收到用户请求后，先判断属于哪类：
选择一次性研究模式（需满足：从 agent 上下文发起，有 parent session）：
- 分析一下 / 看看这个问题 / 跑一轮研究后把结论告诉我
选择持续协作模式（默认用于聊天渠道，或需要长期会话时）：
- 开个 Claude Code 会话 / 线程 / 后面我要继续跟它聊 / 让它持续做这个项目
阶段二：一次性研究模式执行
- 用
sessions_spawn(runtime="acp") 启动 Claude Code run
- 带上：
agentId: "claude"mode: "run"streamTo: "parent"
- 告知用户：已交给 Claude Code 处理，结果会回当前会话
- 等待标准 ACP 回流结果
阶段三：持续协作模式执行
发起任务
- 确定本次对话的
sessionName（如已有则复用，否则新建，必须以 oc- 开头）
- 先确保 session 存在（幂等，已存在则复用）：
- 将用户需求原文写入 stdin，后台执行：
- 若用户指定了项目目录
<projectDir>：
nohup sh -c 'cd <projectDir> && echo "<用户消息>" | acpx claude prompt --session <sessionName> --file -' > /tmp/acpx-<sessionName>.log 2>&1 &
- 否则：
nohup sh -c 'echo "<用户消息>" | acpx claude prompt --session <sessionName> --file -' > /tmp/acpx-<sessionName>.log 2>&1 &
- 命令发出后立即返回，告知用户：已交给 Claude Code，正在处理
处理 hook 回调
当收到 hook 事件时：
Stop 事件
- 取出
reply 字段内容
- 将
reply 转发给用户
- 等待用户下一条消息
SessionEnd 事件
- 若
status: "completed"：
- 若
summary 不为空，向用户展示总结
- 告知用户 Claude Code 会话已结束
- 若
status: "cleared"：
- 告知用户会话被清除，如需继续将以新
sessionName 发起新会话
消息转发原则
一次性研究模式
- 允许 OpenClaw 用正常助手口吻把 Claude Code 的结果带回或转述给用户
- 不要求逐字原样转发，重点是保持结果语义正确、上下文可继续
持续协作模式
- 用户消息原文透传给 Claude Code
- Claude Code 的 reply 尽量原样转发
- 仅在必要时插入简短状态提示
错误处理
| 情况 | 处理方式 |
|---|
acpx 命令不存在 | 告知用户检查 acpx 是否已加入 PATH（参见 setup-claude-code skill） |
Failed to spawn agent command: claude | claude CLI 未安装或不在 PATH，告知用户检查 Claude Code 安装 |
Exec failed ... signal SIGTERM | direct acpx 进程被超时杀掉，检查是否用了后台执行（nohup ... &） |
stop 回调中 reply 为空 | 跳过，继续等待下一个事件 |
| 60 秒内无任何回调 | 提示用户 Claude Code 可能仍在处理，继续等待 |
| session_end 未收到 summary | 仅告知会话已结束，不强行总结 |
