OpenClaw Claude Code 插件开发笔记

项目地址：GitHub

---

一、为什么要做这个插件

通过 Slack（或其他消息渠道）远程控制本机的 Claude Code，实现：

• 在手机上给 bot 发消息就能分析代码、执行任务
• 不需要坐在电脑前打开终端
• AI 助手（OpenClaw Agent）可以调用 Claude Code 来完成复杂的编码工作

核心思路：OpenClaw 作为消息网关，接收 Slack 消息 → 调用 Claude Code CLI → 返回结果

---

二、插件架构

2.1 三个工具

工具	权限模式	用途
claude_plan	plan（只读）	分析代码、审查架构、制定方案，不修改文件
claude_exec	bypassPermissions	执行编码任务，可读写文件、运行命令
claude_teams	bypassPermissions + teams	多 Agent 并行协作

2.2 安全模型（代码级强制执行）

┌─────────────────────────────────────────────┐
│  LLM (OpenClaw Agent)                       │
│  ↓ 调用工具                                  │
├─────────────────────────────────────────────┤
│  插件安全层（无法绕过）                       │
│  • allowedPaths: 白名单目录检查              │
│  • maxTimeoutSecs: 超时硬上限                │
│  • maxConcurrent: 并发限制                   │
│  • blockedPermissionModes: 禁用危险模式      │
├─────────────────────────────────────────────┤
│  Claude Code CLI                            │
│  --permission-mode plan/bypassPermissions   │
└─────────────────────────────────────────────┘

关键设计：allowedPaths 默认为空，必须显式配置才能使用。

2.3 核心文件结构

openclaw-claude-code/
├── index.ts                 # 插件入口，注册工具
├── openclaw.plugin.json     # 插件元数据和配置 schema
└── src/
    ├── shared.ts            # 核心逻辑：路径校验、spawn claude、日志
    ├── plan-tool.ts         # claude_plan 工具
    ├── exec-tool.ts         # claude_exec 工具
    └── teams-tool.ts        # claude_teams 工具

---

三、开发过程中遇到的问题与解决

3.1 Claude Code 二进制路径问题

问题： spawn ... ENOENT 错误

原因： Claude Desktop 把二进制安装在 ~/Library/Application Support/Claude/claude-code/<版本>/claude，路径包含空格，Node.js 的 spawn() 处理不当会报错。

解决： 在 resolveClaudeBin() 中按优先级查找：

1. $CLAUDE_BIN 环境变量
2. ~/bin/claude（推荐，创建符号链接）
3. Application Support 下的版本目录
4. PATH 中的 claude

3.2 工作目录不存在导致 ENOENT

问题： 用户请求的 workdir 不存在时，spawn 报 ENOENT，但错误信息显示的是 claude 路径，很误导。

解决： 在 validateWorkdir() 中先检查目录是否存在（实际上是检查是否在白名单内，白名单路径应该存在）。

3.3 权限模式不匹配

问题： --permission-mode full 报错，Claude Code 不认识这个值。

原因： Claude Code 2.x 的有效值是 acceptEdits | bypassPermissions | default | dontAsk | plan。

解决：

• claude_plan 使用 plan 模式
• claude_exec 和 claude_teams 使用 bypassPermissions 模式

3.4 认证问题

问题： Gateway 作为系统服务运行时，不继承 shell 的环境变量，Claude Code 报 “Not logged in”。

解决： 在插件 config 中添加 claudeOauthToken 配置项，通过 CLAUDE_CODE_OAUTH_TOKEN 环境变量传递给 Claude Code 子进程。

3.5 执行过程不可见

问题： 用户无法实时看到 Claude Code 的执行过程。

解决方案演进：

1. PTY + Remote Control → 用 node-pty 启动交互式 TUI，自动输入 /rc 获取监控链接。遇到三个阻塞问题：spawn-helper 无执行权限、bypassPermissions 确认弹窗、TUI 自动补全拦截 /rc 命令。弃用。
2. tmux 模式 → 在 tmux session 中运行 claude --print，返回 session 名称让用户 attach。问题：工具阻塞等待完成才返回，此时 session 已结束；且 tmux 内 claude 无输出（疑似环境问题）。弃用。
3. 日志文件模式（最终方案） → stdout/stderr 实时写入 /tmp/claude-logs/claude-<id>.log，用户可以 tail -f 监控

---

四、配置教程

4.1 安装插件

git clone https://github.com/Phoenizard/openclaw-claude-code.git
cd openclaw-claude-code
npm install
openclaw plugins install -l .
openclaw gateway restart

4.2 配置 ~/.openclaw/openclaw.json

{
  "plugins": {
    "entries": {
      "claude-code": {
        "enabled": true,
        "config": {
          "allowedPaths": [
            "~/your-project-a",
            "~/your-project-b"
          ],
          "maxTimeoutSecs": 600,
          "maxConcurrent": 2,
          "claudeOauthToken": "<your-oauth-token>"
        }
      }
    }
  },
  "agents": {
    "list": [
      {
        "id": "main",
        "default": true,
        "tools": {
          "allow": ["claude_plan", "claude_exec", "claude_teams"]
        }
      }
    ]
  }
}

4.3 Claude Code 二进制设置（推荐）

mkdir -p ~/bin
# 版本号会随更新变化，请替换为实际版本
ln -sf "$HOME/Library/Application Support/Claude/claude-code/<版本号>/claude" ~/bin/claude

---

五、使用方法

5.1 分析代码（只读）

在 Slack 中发送：

用 claude_plan 分析 ~/my-project 的项目架构

5.2 执行任务

用 claude_exec 在 ~/my-project 中添加单元测试

5.3 实时监控

工具返回结果会包含日志文件路径：

📋 Log file: /tmp/claude-logs/claude-c5bda15f.log
Run `tail -f /tmp/claude-logs/claude-c5bda15f.log` to monitor.

在终端运行：

tail -f /tmp/claude-logs/claude-*.log

5.4 推荐工作流：Plan → 审核 → Exec

1. Plan： 让 claude_plan 制定方案
2. 审核： 在 Slack 中阅读，确认合理
3. Exec： 让 claude_exec 执行方案

---

六、示例：神经网络回归项目

通过 Slack 远程调用插件，完成了一个完整的 PyTorch 神经网络回归项目：

project/
├── model.py            # RegressionNet: 1→32→32→1
├── dataset.py          # generate_data (多项式) + generate_sine_data (正弦)
├── train.py            # Adam + MSELoss
├── plot.py             # loss 曲线 + 预测对比图
├── main.py             # 多项式回归实验
├── test_sine.py        # 正弦回归实验
├── tests/              # pytest 单元测试（14 个全部通过）
└── README.md           # 安装说明

---

七、待改进

1. 错误信息更友好 — 目前有些错误（如 ENOENT）不够直观
2. 进度反馈 — 长任务执行时能分步返回中间结果
3. 提前返回日志路径 — 当前工具阻塞到任务完成才返回日志路径，理想情况是任务开始时就通知用户日志文件位置

---

八、总结

这个插件实现了：

• ✅ 通过 Slack 远程调用 Claude Code
• ✅ 安全的白名单目录控制
• ✅ 三种模式：只读分析 / 执行任务 / 多 Agent 协作
• ✅ 实时日志监控

核心价值：让 AI 助手能够调用专业的编码 Agent（Claude Code）来完成复杂的开发任务。