OpenClaw

安装 OpenClaw，并通过自定义 OpenAI-compatible provider 调用 TokenHub。

OpenClaw 可以通过 models.providers 接入自定义 OpenAI-compatible 服务。创建一个本地名称为 tokenhub 的自定义 provider，配置 Base URL、API Key、协议适配器和模型目录即可。

本教程使用的 TokenHub endpoint 是 https://us-api.tokenhub.com/v1/chat/completions，示例模型引用为 tokenhub/gpt-4.1。

适合场景

OpenClaw 适合构建带 Gateway 网关、消息渠道、Skills、浏览器自动化和长期运行任务的个人 AI 助手。你可以先在 Control UI 中验证普通对话，再连接 Telegram、WhatsApp、Discord 等渠道。

可以先查看 OpenClaw 官方展示案例了解常见工作流。配置 TokenHub 时，以 OpenClaw 自定义 provider 文档中的 models.providers 结构为准。

安装 OpenClaw

OpenClaw 当前需要官方文档支持的 Node.js 版本。安装前先检查：

node --version

macOS 或 Linux 可使用官方安装脚本：

curl -fsSL https://openclaw.ai/install.sh | bash

Windows PowerShell：

iwr -useb https://openclaw.ai/install.ps1 | iex

确认 CLI 可用：

openclaw --version

准备 TokenHub 凭证

在 TokenHub 工作台创建 API Key，并从模型列表选择支持 OpenAI Chat Completions 的真实 Model ID。下面以 gpt-4.1 为例；如果你的工作区没有这个模型，请同时替换配置中的模型 ID、显示名称和能力参数。

把密钥保存到 ~/.openclaw/.env：

TOKENHUB_API_KEY=your-local-tokenhub-key

不要把真实 Key 写进项目仓库或直接写死在 openclaw.json。OpenClaw Gateway 可能由 launchd、systemd 或 Docker 托管；只有交互式终端里的 export 通常不会被这些后台进程读取。

配置自定义 TokenHub provider

在 ~/.openclaw/openclaw.json 中合并下面的配置：

{
  models: {
    mode: 'merge',
    providers: {
      tokenhub: {
        baseUrl: '__API_BASE_URL__/v1',
        apiKey: '${TOKENHUB_API_KEY}',
        api: 'openai-completions',
        models: [
          {
            id: 'gpt-4.1',
            name: 'TokenHub / gpt-4.1',
            reasoning: false,
            input: ['text'],
            contextWindow: 128000,
            maxTokens: 8192,
          },
        ],
      },
    },
  },
  agents: {
    defaults: {
      model: {
        primary: 'tokenhub/gpt-4.1',
      },
    },
  },
}

关键字段：

配置项	作用
`models.mode: "merge"`	保留 OpenClaw 已有 provider 和模型目录。
`models.providers.tokenhub`	创建名为 `tokenhub` 的自定义 provider ID。
`baseUrl`	TokenHub OpenAI-compatible Base URL，必须包含 `/v1`。
`apiKey`	从 Gateway 环境读取 `TOKENHUB_API_KEY`，不在配置中保存明文。
`api: "openai-completions"`	使用 `/v1/chat/completions` 协议适配器。
`models[].id`	TokenHub 模型列表中的裸 Model ID，不带 provider 前缀。
`agents.defaults.model.primary`	选择模型时使用完整的 `tokenhub/<model-id>` 引用。

contextWindow、maxTokens、reasoning 和 input 必须与实际模型能力匹配。视觉模型可把 input 改成 ["text", "image"]；不要照抄不符合模型真实限制的参数。

如果 openclaw.json 已经包含 Gateway、渠道、Skills 或其它 Agent 设置，请只合并上述字段，不要覆盖整个文件。

重启并验证 provider

保存配置后重启 Gateway：

openclaw gateway restart

确认 OpenClaw 能读取自定义 provider 和模型：

openclaw models list --provider tokenhub
openclaw models set "tokenhub/gpt-4.1"

检查 Gateway 状态：

openclaw gateway status

打开 Control UI：

openclaw dashboard

先发送只读提示：

请用三句话介绍当前工作区。不要修改文件，不要执行写入命令，也不要调用外部渠道。

成功返回后，到 TokenHub 请求日志确认 Model ID、/v1/chat/completions endpoint、token 用量和计费分组。

临时环境变量验证

如果只是从当前终端启动 OpenClaw 做一次排错，可以临时导出：

export TOKENHUB_API_KEY="sk-..."
openclaw gateway restart

这只适合验证 Key。长期运行的 Gateway 仍应从 ~/.openclaw/.env 或其它安全的服务环境读取密钥。

常见问题

现象	处理方式
401 或认证失败	确认 `~/.openclaw/.env` 中存在有效的 `TOKENHUB_API_KEY`，然后重启 Gateway。
请求发往错误地址	检查 `models.providers.tokenhub.baseUrl` 是否为 `https://us-api.tokenhub.com/v1`。
404 或模型找不到	`models[].id` 使用裸 Model ID；默认模型只添加一次前缀，例如 `tokenhub/gpt-4.1`。
请求打到 `/v1/responses`	确认 provider 的 `api` 是 `openai-completions`，不要配置成 `openai-responses`。
图片没有传给模型	只有实际支持视觉的模型才能把 `input` 配置为 `["text", "image"]`。
Control UI 可打开但没有回复	运行 `openclaw gateway status`，再检查 provider、Key、Base URL 和 TokenHub 请求日志。
终端可用但守护进程报 401	临时 `export` 不会自动进入 launchd、systemd 或 Docker；把 Key 写入 `~/.openclaw/.env` 后重启 Gateway。