Claude Code Setup & Usage Skill

# 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 步：检查环境

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

### 第 2 步：安装 Claude Code CLI

```bash
# 清理可能的冲突
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 配置：

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

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

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

```bash
# 安装 acpx 插件
openclaw plugins install acpx

# 启用插件
openclaw plugins enable acpx

# 重启 Gateway
openclaw gateway restart
```

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

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

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

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

**权限模式说明：**
- `approve-all`: 自动批准所有权限请求（推荐用于开发）
- `approve-reads`: 只批准读取操作
- `deny-all`: 拒绝所有操作

配置后必须重启 Gateway：
```bash
openclaw gateway restart
```

### 第 6 步：验证配置

```bash
# 检查配置
openclaw config get acp

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

应该看到：
- ACP 配置正确显示
- acpx 插件状态为 `enabled`

### 第 7 步：测试 ACP 调用

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

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

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

## 使用方法

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

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

### 方式 2：明确调用
用户明确要求使用 Claude Code：

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

**如何找到正确的工作目录：**
```bash
# 查看当前配置的工作目录
openclaw config get agents.defaults.workspace

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

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

### 方式 3：持续会话
需要多轮对话的复杂任务：

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

## 常见问题和解决方案

### 问题 1：ACP runtime backend is not configured
**原因：** acpx 插件未正确启用
**解决：**
```bash
openclaw plugins enable acpx
openclaw gateway restart
```

### 问题 2：claude-code not found
**原因：** CLI 名称错误或未安装
**解决：**
```bash
# 正确的 CLI 名称是 claude
which claude
# 如果没有，重新安装
npm install -g @anthropic-ai/claude-code
```

### 问题 3：npm ENOTEMPTY 错误
**原因：** 安装冲突
**解决：**
```bash
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 插件权限模式未配置或配置错误
**解决：**
```bash
# 检查当前权限配置
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 启动目录执行，通常不是你想要的位置。

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

**如何选择正确的 cwd：**
```bash
# 查看配置的默认工作目录
openclaw config get agents.defaults.workspace

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

### 3. 包含验证步骤
```javascript
task: "创建文件 test.txt，内容是 'Hello'，然后用 cat 命令显示内容验证"
```

### 4. 使用 sessions_yield 等待
```javascript
// 提交任务后
sessions_yield({ message: "等待 Claude Code 完成..." })
```

### 5. 验证结果
不要只看工具返回，要实际检查：
```javascript
// 检查文件是否真的创建了
read({ file_path: "/path/to/expected/file" })
```

## 适用场景

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

### ❌ 不适合用 Claude Code
- 简单的飞书操作
- 文档创建和编辑
- 消息发送
- 数据查询
- 一行代码的简单任务

## 示例用法

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

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

### 示例 3：批量文件处理
```javascript
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 部分：

```json
{
  "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