/docs/guides/OPENCLAW_README.zh.md

name, description

name	description
openclaw-claude-tap-setup	Configure and launch claude-tap as a local proxy for OpenClaw integration. Use when setting up claude-tap with OpenClaw, troubleshooting API proxy issues, or managing trace collection in an OpenClaw environment.

Claude Tap 设置指南（OpenClaw 集成必读）

English version: Claude Tap Setup Guide.

背景

OpenClaw 可以通过 claude-tap 这样的本地代理 trace 模型 API 请求。配置完成后，发往指定模型 provider 的所有 API 请求都会先转发到本地代理，再由本地代理转发到上游端点，同时记录请求和响应用于调试。

重要：把 openclaw.json 中 provider 的 baseUrl 指向本地代理后，必须确保代理进程正在运行。否则 API 请求会 connection refused，导致整个 OpenClaw 服务不可用。

配置

1. openclaw.json 中的 claude-tap 配置

在 ~/.openclaw/openclaw.json 的 models.providers.<provider> 下增加指向本地代理的 baseUrl。Anthropic 示例：

{
  "models": {
    "providers": {
      "anthropic": {
        "baseUrl": "http://127.0.0.1:8787",
        "api": "anthropic-messages",
        "models": [
          {
            "id": "claude-sonnet-4-6",
            "name": "Claude Sonnet 4.6 (via claude-tap)",
            "api": "anthropic-messages",
            "reasoning": false,
            "input": ["text", "image"],
            "cost": {
              "input": 0,
              "output": 0,
              "cacheRead": 0,
              "cacheWrite": 0
            },
            "contextWindow": 200000,
            "maxTokens": 8192
          }
        ]
      }
    }
  }
}

关键字段：

• baseUrl：必须指向 claude-tap 监听的地址和端口，默认是 http://127.0.0.1:8787
• 其他字段：按需配置模型参数

2. 启动 claude-tap

配置 openclaw.json 后，必须先启动 claude-tap，再启动 OpenClaw。

仅 API 代理（无前端）

nohup claude-tap \
  --tap-port 8787 \
  --tap-host 127.0.0.1 \
  --tap-no-launch \
  --tap-no-open \
  > ~/.openclaw/logs/claude-tap.log 2>&1 &

API 代理 + 实时查看器前端

nohup claude-tap \
  --tap-port 8787 \
  --tap-host 127.0.0.1 \
  --tap-no-launch \
  --tap-no-open \
  --tap-live \
  --tap-live-port 8788 \
  > ~/.openclaw/logs/claude-tap.log 2>&1 &

参数说明：

参数	说明
--tap-port 8787	API 代理监听端口；必须与 openclaw.json baseUrl 中的端口一致
--tap-host 127.0.0.1	绑定到 loopback 地址；仅允许本地访问，不暴露到网络
--tap-no-launch	只启动代理；不启动 Claude CLI 客户端
--tap-no-open	退出时不自动打开 HTML 报告
--tap-live	启用实时 trace viewer 前端
--tap-live-port 8788	实时 viewer 前端端口

安全提示：必须指定 --tap-host 127.0.0.1，确保代理和前端都只监听 loopback 地址。若不指定该参数，--tap-no-launch 模式默认绑定 0.0.0.0，会把端口暴露到公网。

3. 验证 claude-tap 正在运行

# 检查端口是否监听
ss -tlnp | grep -E "8787|8788"

# 期望输出（两个端口都应绑定到 127.0.0.1 且处于 LISTEN 状态）：
# LISTEN  0  128  127.0.0.1:8787  0.0.0.0:*  users:(("claude-tap",...))
# LISTEN  0  128  127.0.0.1:8788  0.0.0.0:*  users:(("claude-tap",...))
# 如果看到 0.0.0.0:8787，说明端口已公开暴露；立即停止
# 并使用 --tap-host 127.0.0.1 重新启动

# 测试代理连通性
curl -s -o /dev/null -w "%{http_code}" http://127.0.0.1:8787/
# 404 表示代理正在运行（根路径没有 handler 是预期行为）

# 检查进程
ps aux | grep claude-tap | grep -v grep

4. 访问实时查看器前端

因为绑定到 127.0.0.1，实时 viewer 只能从本机访问：http://127.0.0.1:8788

远程访问请使用 SSH 端口转发：

ssh -L 8788:127.0.0.1:8788 user@remote-host

然后在本地浏览器打开 http://127.0.0.1:8788。

启动 / 重启顺序（关键）

1. 启动 claude-tap（端口 8787）
2. 验证端口正在监听（ss -tlnp | grep 8787，确认 LISTEN 状态）
3. 验证代理连通性（curl http://127.0.0.1:8787/，期望 404）
4. 以上两项都通过后，再重启 OpenClaw gateway

绝不要在 claude-tap 未就绪时重启 gateway。重启 gateway 前必须确认 claude-tap 端口正在监听，并且代理可达。

如果顺序反了、代理没启动，或跳过验证，所有通过代理路由的模型 API 调用都会失败（connection refused），实际效果就是服务不可用。

故障排查

API 服务不可用 / 无法调用模型

1. 检查 claude-tap 进程是否存在：ps aux | grep claude-tap
2. 检查端口是否监听：ss -tlnp | grep 8787
3. 如果未运行，按上面的步骤启动 claude-tap
4. 重启 OpenClaw gateway

移除 claude-tap

从 ~/.openclaw/openclaw.json 删除 baseUrl 字段，或删除整个自定义 provider block，让 OpenClaw 直接连接 provider 官方 API。然后重启 gateway。

日志

• claude-tap 日志：~/.openclaw/logs/claude-tap.log
• Trace 文件默认保存到：./.traces/