OpenClaw 安装和 API 设置

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',
      },
    },
  },
}

关键字段：

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 或其它安全的服务环境读取密钥。

故障排查