OpenClaw

一、产品简介

OpenClaw 是一个自托管的 AI Agent 网关，可把 Telegram、Slack、Discord、WhatsApp、iMessage、WebChat 等消息入口连接到本机或服务器上的 Agent。通过 verahub-cn，OpenClaw 可以统一调用多种大模型，并把 verahub-cn 模型作为默认模型、备用模型或不同 Agent 的专用模型。适合以下场景：

想把 AI Agent 部署在自己的机器或服务器上
需要从聊天软件远程触发开发、运维、资料整理等任务
希望一个 Gateway 管理多个 Agent、渠道和会话
需要把 verahub-cn 作为 OpenAI-compatible 模型网关接入 OpenClaw

二、安装与基础启动

确保本机已有 Node 24，或至少 Node 22.19+。OpenClaw 推荐使用官方安装脚本，它会检测系统环境、安装依赖并启动 onboarding。

curl -fsSL https://openclaw.ai/install.sh | bash
openclaw onboard --install-daemon
openclaw gateway status

如果 Gateway 状态正常，再打开 Control UI：

openclaw dashboard

建议先确认基础 UI 可用，再配置 verahub-cn Provider，排障会更清晰。

三、准备 verahub-cn 信息

在 verahub-cn 控制台创建 API Key，并从模型列表复制需要使用的模型 ID。推荐先准备两个模型：

用途	示例模型
主模型	`claude-opus-4-8`、`gpt-5.5`、`kimi-k2.7-code`
备用模型	`deepseek-v4-pro`、`glm-5.2`、`MiniMax-M3`

四、配置 verahub-cn Provider

OpenClaw 可通过 models.providers.<providerId> 接入 OpenAI-compatible 网关。最直接的方式是编辑 OpenClaw 配置文件，把 verahub-cn 的 baseUrl、apiKey、api 和模型列表写到同一个 provider block 里。

baseUrl 必须写在 models.providers.verahub.baseUrl，不要写到 agents.defaults.models 或 auth profile 里。agents.defaults.models["provider/model"] 只控制可见性、别名和 per-model 参数，不能单独注册 runtime provider。

1. 修改 OpenClaw 配置

OpenClaw 配置通常位于：

~/.openclaw/openclaw.json

也可以先用命令确认当前实际配置文件路径：

openclaw config file

在现有配置基础上合并以下关键片段。关键点是：verahub-cn Provider 必须注册在 models.providers.verahub，默认模型再通过 agents.defaults.model 指向 verahub/模型ID。

{
  "models": {
    "mode": "merge",
    "providers": {
      "verahub": {
        "baseUrl": "https://api.vera-hub.cn/v1",
        "apiKey": "sk-xxxxxxxxxxxxxxxx",
        "api": "openai-completions",
        "models": [
          {
            "id": "claude-opus-4-8",
            "name": "Claude Opus 4.8"
          },
          {
            "id": "gpt-5.5",
            "name": "GPT 5.5"
          },
          {
            "id": "deepseek-v4-pro",
            "name": "DeepSeek V4 Pro"
          }
        ]
      }
    }
  },
  "agents": {
    "defaults": {
      "model": {
        "primary": "verahub/claude-opus-4-8",
        "fallbacks": ["verahub/deepseek-v4-pro", "verahub/gpt-5.5"]
      },
      "models": {
        "verahub/claude-opus-4-8": {
          "alias": "verahub-cn Claude Opus"
        },
        "verahub/deepseek-v4-pro": {
          "alias": "verahub-cn DeepSeek V4 Pro"
        },
        "verahub/gpt-5.5": {
          "alias": "verahub-cn GPT 5.5"
        }
      }
    }
  }
}

这是需要合并到现有配置中的核心片段，不建议直接覆盖整个 openclaw.json。保留 onboarding 已生成的渠道、Gateway、权限和本地状态配置。OpenClaw 的 config 写入命令对 models.providers、agents.defaults.models 等 map 有防覆盖保护，手动编辑时也要按“合并字段”的方式处理。

如果不想把 Key 明文写进 openclaw.json，也可以在配置里保留 apiKey: "${VERAHUB_API_KEY}"，再把 Key 放到 OpenClaw 服务能读取的环境变量或 ~/.openclaw/.env。本页主流程使用直接改配置文件，是为了本机部署时最少跳转、最容易排查。

如果偏好用命令写入，使用 --merge，避免覆盖已有 provider：

openclaw config set models.providers.verahub '{
  "baseUrl": "https://api.vera-hub.cn/v1",
  "apiKey": "sk-xxxxxxxxxxxxxxxx",
  "api": "openai-completions",
  "models": [
    { "id": "claude-opus-4-8", "name": "Claude Opus 4.8" },
    { "id": "gpt-5.5", "name": "GPT 5.5" },
    { "id": "deepseek-v4-pro", "name": "DeepSeek V4 Pro" }
  ]
}' --strict-json --merge

2. 确认实际读取的 baseUrl

baseUrl 的配置归属是 models.providers.verahub.baseUrl。OpenClaw 会把自定义 provider 写入 agent 目录下的生成态 models.json，但排障时先看当前 openclaw.json 的 models.providers，再检查 agent 侧是否还有旧生成结果。先用 OpenClaw 自己的配置命令检查全局配置：

openclaw config get models.providers.verahub --json

再检查 agent 侧是否存在生成态模型配置：

find "${OPENCLAW_AGENT_DIR:-$HOME/.openclaw/agents}" \
  -path '*/agent/models.json' \
  -exec sh -c 'echo "## $1"; grep -n "verahub\\|baseUrl\\|apiKey" "$1" || true' sh {} \;

如果 openclaw.json 已经是新地址，但 models.json 中还能看到旧的 baseUrl，说明 agent 侧保留了旧 provider row 或旧生成结果。此时先重启 Gateway；如果仍不更新，再重新生成该 agent 的模型目录或移除旧的 verahub provider row，让它从当前 openclaw.json 重新生成。

五、验证接入

1. 检查模型列表

openclaw models list

如果列表中出现 verahub/... 模型，说明 provider 已被识别。models list 是只读检查，不会自动重写 models.json。也可以直接跑一个最小模型探测，确认当前生效的 provider、Key 和 baseUrl 能真实发起请求：

openclaw infer model run \
  --local \
  --model verahub/claude-opus-4-8 \
  --prompt "Reply with exactly: pong" \
  --json

2. 打开控制台测试

openclaw dashboard

在 Control UI 中发送：

请用一句话说明你当前使用的模型和可用工具。

如果 OpenClaw 能正常响应，并且 verahub-cn 控制台出现调用记录，说明配置成功。

六、推荐配置策略

场景	配置建议
日常消息助手	使用 `MiniMax-M3`、`glm-5.2` 或 `deepseek-v4-pro` 作为 primary
编程 Agent	使用 `claude-opus-4-8`、`gpt-5.5`、`gpt-5.4` 或 `deepseek-v4-pro`
重要自动化	配置 `fallbacks`，避免单模型失败导致任务中断
多 Agent	给不同 Agent 指定不同 `verahub/model-id`，例如 `verahub/kimi-k2.7-code`、`verahub/glm-5.2` 或 `verahub/MiniMax-M3`
排障阶段	先只配置 Web Control UI，不急着接 Telegram / Slack

七、常见问题

模型列表里没有 verahub 前缀

检查 models.mode 是否为 merge
检查 provider 是否写在 models.providers.verahub
检查 agents.defaults.models 是否加入了 verahub/模型ID
重启 Gateway 或重新生成 agent 模型目录后再查看

401 或认证失败

确认 models.providers.verahub.apiKey 是 verahub-cn API Key
如果用了 ${VERAHUB_API_KEY}，确认 Gateway 进程能读取这个环境变量
回到 verahub-cn 控制台确认 Key 没有被删除或禁用

我改了 openclaw.json，但请求仍然走旧地址

先运行 openclaw config get models.providers.verahub --json 看全局配置
再检查 agent 目录下的 models.json 是否保留旧的 verahub.baseUrl
重启 Gateway；若仍不更新，重新生成 agent 模型目录或移除旧 provider row

请求失败或 endpoint not found

OpenAI-compatible 接入必须使用 https://api.vera-hub.cn/v1
检查 api 是否为 openai-completions
检查模型 ID 是否与 verahub-cn 模型列表一致

八、参考链接

OpenClaw 文档：https://docs.openclaw.ai/
OpenClaw GitHub：https://github.com/openclaw/openclaw

对话型 AI

编程开发

技术工程

翻译场景

一、产品简介

二、安装与基础启动

三、准备 verahub-cn 信息

四、配置 verahub-cn Provider

1. 修改 OpenClaw 配置

2. 确认实际读取的 baseUrl

五、验证接入

1. 检查模型列表

2. 打开控制台测试

六、推荐配置策略

七、常见问题

八、参考链接

​一、产品简介

​二、安装与基础启动

​三、准备 verahub-cn 信息

​四、配置 verahub-cn Provider

​1. 修改 OpenClaw 配置

​2. 确认实际读取的 baseUrl

​五、验证接入

​1. 检查模型列表

​2. 打开控制台测试

​六、推荐配置策略

​七、常见问题

​八、参考链接

一、产品简介

二、安装与基础启动

三、准备 verahub-cn 信息

四、配置 verahub-cn Provider

1. 修改 OpenClaw 配置

2. 确认实际读取的 baseUrl

五、验证接入

1. 检查模型列表

2. 打开控制台测试

六、推荐配置策略

七、常见问题

八、参考链接