Claude Code Setup & Usage Skill

让 AI 助手学会调用 Claude Code 干活的完整指南。

使用场景

当用户提到以下需求时使用此 skill：

• "配置 Claude Code"
• "安装 ACP"
• "让 Claude Code 帮我写代码"
• "调用 Anthropic 的 Claude Code"
• "设置代码助手"
• "我想用 Claude Code 做开发"

核心概念

Claude Code 是 Anthropic 官方的 ACP (Agent Computer Protocol) 实现，擅长：

• 代码编写和调试
• 文件系统操作
• 命令行执行
• 技术问题解决
• 项目搭建

ACP 是标准化协议，让 AI 能直接操作计算机。

安装配置流程

第 1 步：检查环境

# 检查是否已安装
which claude
openclaw config get acp
openclaw plugins list | grep acpx

第 2 步：安装 Claude Code CLI

# 清理可能的冲突
rm -rf ~/.npm-global/lib/node_modules/@anthropic-ai/claude-code

# 安装 Claude Code
npm install -g @anthropic-ai/claude-code

# 验证安装（注意：CLI 名称是 claude，不是 claude-code）
claude --version

第 3 步：配置 OpenClaw

在 ~/.openclaw/openclaw.json 中添加 ACP 配置：

{
  "acp": {
    "defaultAgent": "claude",
    "allowedAgents": ["claude"]
  }
}

重要： 配置文件是 openclaw.json，不是 config.json！

第 4 步：安装并启用 acpx 插件

# 安装 acpx 插件
openclaw plugins install acpx

# 启用插件
openclaw plugins enable acpx

# 重启 Gateway
openclaw gateway restart

第 5 步：配置权限模式（关键步骤！）

重要： 必须配置 acpx 插件的权限模式，否则 ACP 调用会被阻止。

在 ~/.openclaw/openclaw.json 的 plugins.entries 部分添加：

{
  "plugins": {
    "entries": {
      "acpx": {
        "enabled": true,
        "config": {
          "permissionMode": "approve-all"
        }
      }
    }
  }
}

权限模式说明：

• approve-all: 自动批准所有权限请求（推荐用于开发）
• approve-reads: 只批准读取操作
• deny-all: 拒绝所有操作

配置后必须重启 Gateway：

openclaw gateway restart

第 6 步：验证配置

# 检查配置
openclaw config get acp

# 检查插件状态
openclaw plugins list | grep acpx

应该看到：

• ACP 配置正确显示
• acpx 插件状态为 enabled

第 7 步：测试 ACP 调用

创建一个简单的测试任务验证配置：

sessions_spawn({
  agentId: "claude",
  runtime: "acp",
  mode: "run",
  cwd: "~/workspace", // 使用你的工作目录
  task: "创建一个测试文件 acp-test.txt，内容为 'ACP 配置成功！'，然后用 cat 命令显示内容验证"
})

如果配置正确，应该能看到文件被成功创建。

使用方法

方式 1：AI 自动判断

当用户提出技术需求时，AI 自动判断是否需要调用 Claude Code：

// 简单任务 → AI 直接处理
// 复杂代码/调试 → 调用 Claude Code
// 需要持续迭代 → 创建 ACP 会话

方式 2：明确调用

用户明确要求使用 Claude Code：

sessions_spawn({
  agentId: "claude",
  runtime: "acp",
  mode: "run", // 一次性任务
  task: "具体任务描述",
  cwd: "$(openclaw config get agents.defaults.workspace)" // 使用配置的工作目录
})

如何找到正确的工作目录：

# 查看当前配置的工作目录
openclaw config get agents.defaults.workspace

# 或者使用相对路径
cwd: "~/.openclaw/workspace"

# 或者指定项目目录
cwd: "~/projects/my-project"

方式 3：持续会话

需要多轮对话的复杂任务：

sessions_spawn({
  agentId: "claude",
  runtime: "acp", 
  mode: "session", // 持续会话
  thread: true,    // 线程绑定
  task: "复杂项目任务"
})

常见问题和解决方案

问题 1：ACP runtime backend is not configured

原因： acpx 插件未正确启用
解决：

openclaw plugins enable acpx
openclaw gateway restart

问题 2：claude-code not found

原因： CLI 名称错误或未安装
解决：

# 正确的 CLI 名称是 claude
which claude
# 如果没有，重新安装
npm install -g @anthropic-ai/claude-code

问题 3：npm ENOTEMPTY 错误

原因： 安装冲突
解决：

rm -rf ~/.npm-global/lib/node_modules/@anthropic-ai/claude-code
npm install -g @anthropic-ai/claude-code

问题 4：Session history visibility is restricted

原因： 权限限制，无法查看 ACP 会话日志
解决： 这是正常的，通过其他方式验证结果（如检查文件是否创建）

问题 5：Permission denied by ACP runtime (acpx)

原因： acpx 插件权限模式未配置或配置错误
解决：

# 检查当前权限配置
openclaw config get plugins.entries.acpx

# 如果没有配置，在 ~/.openclaw/openclaw.json 中添加：
{
  "plugins": {
    "entries": {
      "acpx": {
        "enabled": true,
        "config": {
          "permissionMode": "approve-all"
        }
      }
    }
  }
}

# 重启 Gateway
openclaw gateway restart

问题 6：任务没有执行

原因： 工作目录或任务描述不清晰
解决：

• 明确指定 cwd 参数
• 任务描述要具体，包含验证步骤
• 使用 sessions_yield 等待结果

最佳实践

1. 任务描述要具体

❌ 错误："写个脚本"
✅ 正确："创建一个 Python 脚本 hello.py，打印 'Hello World'，然后执行它验证结果"

2. 指定工作目录（重要！）

必须指定 cwd 参数，否则 Claude Code 会在 Gateway 启动目录执行，通常不是你想要的位置。

sessions_spawn({
  agentId: "claude",
  runtime: "acp",
  cwd: "~/.openclaw/workspace", // 明确指定工作目录
  task: "在当前目录创建项目"
})

如何选择正确的 cwd：

# 查看配置的默认工作目录
openclaw config get agents.defaults.workspace

# 常用选项：
# ~/.openclaw/workspace  - OpenClaw 工作目录
# ~/projects            - 项目目录  
# ~/Documents           - 文档目录
# $(pwd)                - 当前目录

3. 包含验证步骤

task: "创建文件 test.txt，内容是 'Hello'，然后用 cat 命令显示内容验证"

4. 使用 sessions_yield 等待

// 提交任务后
sessions_yield({ message: "等待 Claude Code 完成..." })

5. 验证结果

不要只看工具返回，要实际检查：

// 检查文件是否真的创建了
read({ file_path: "/path/to/expected/file" })

适用场景

✅ 适合用 Claude Code

• 编写复杂代码（>50 行）
• 调试技术问题
• 批量文件操作
• 项目搭建和配置
• 需要多次迭代的开发任务
• 需要执行命令行操作

❌ 不适合用 Claude Code

• 简单的飞书操作
• 文档创建和编辑
• 消息发送
• 数据查询
• 一行代码的简单任务

示例用法

示例 1：创建 React 项目

sessions_spawn({
  agentId: "claude",
  runtime: "acp",
  mode: "run",
  cwd: "~/projects", // 替换为你的项目目录
  task: "创建一个新的 React 项目 my-app，安装依赖，创建一个简单的 Hello World 组件，然后运行 npm run build 验证项目可以正常构建"
})

示例 2：调试 Python 代码

sessions_spawn({
  agentId: "claude",
  runtime: "acp", 
  mode: "session",
  thread: true,
  cwd: "$(openclaw config get agents.defaults.workspace)", // 使用配置的工作目录
  task: "帮我调试这个 Python 脚本的错误：[贴入代码]。找出问题并修复，然后运行验证"
})

示例 3：批量文件处理

sessions_spawn({
  agentId: "claude",
  runtime: "acp",
  mode: "run",
  cwd: "~/Documents", // 替换为目标目录
  task: "批量重命名当前目录下所有 .txt 文件，在文件名前加上日期前缀 YYYY-MM-DD_，然后列出所有重命名后的文件"
})

故障排除检查清单

遇到问题时，按顺序检查：

1. ✅ Claude CLI 是否安装：claude --version
2. ✅ ACP 配置是否正确：openclaw config get acp
3. ✅ acpx 插件是否启用：openclaw plugins list | grep acpx
4. ✅ Gateway 是否重启：openclaw gateway restart
5. ✅ 任务描述是否具体
6. ✅ 工作目录是否正确
7. ✅ 是否使用了 sessions_yield 等待

配置文件模板

完整的 ~/.openclaw/openclaw.json ACP 部分：

{
  "acp": {
    "defaultAgent": "claude",
    "allowedAgents": ["claude"]
  },
  "plugins": {
    "entries": {
      "acpx": {
        "enabled": true
      }
    }
  }
}

总结

Claude Code 是强大的代码助手，但需要正确配置：

1. 安装 Claude CLI（名称是 claude）
2. 配置 ACP 设置
3. 启用 acpx 插件
4. 重启 Gateway
5. 使用具体的任务描述
6. 验证执行结果

配置完成后，AI 就能调用 Claude Code 处理复杂的编程任务了！

---

最后更新： 2026-03-16
适用版本： OpenClaw 2026.3.13+
依赖： @anthropic-ai/claude-code, acpx plugin