OpenClaw

• 官方主页：openclaw.ai
• 安装文档：docs.openclaw.ai/start/getting-started
• 模型 / 网关配置：docs.openclaw.ai/concepts/model-providers
• 协议类型：OpenAI 兼容（Chat Completions）/ Anthropic Messages

安装

OpenClaw 以 npm 包形式分发，运行时依赖 Node.js。系统要求：推荐 Node.js 24（也支持 Node 22.19+），可用 node --version 查看当前版本。Windows 用户也可使用原生 Hub 桌面应用，详见官方 Windows 文档。

以下是官方推荐的安装方式，其余写法以官方安装文档为准。

安装脚本（推荐）

macOS / Linux：

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

Windows（PowerShell）：

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

npm 备选（需先安装 Node.js 22.19+）

npm install -g openclaw@latest

安装完成后用 openclaw --version 确认。随后运行引导向导并安装后台服务（Gateway 守护进程）：

openclaw onboard --install-daemon

向导会引导你选择模型提供商、填写 API Key 并配置 Gateway。本文档将在向导之外，演示如何把模型提供商手动指向 TokenBay。

对接 TokenBay

OpenClaw 把每个模型来源抽象为 provider，模型引用统一写成 provider/model 的形式。要接入 TokenBay，只需在配置文件 ~/.openclaw/openclaw.json 中通过 models.providers.<id> 新增一个自定义 provider（OpenAI 兼容代理），把它的 baseUrl 指向 TokenBay、apiKey 设为你的 TokenBay 密钥，再把默认模型 agents.defaults.model.primary 设为 tokenbay/<模型名> 即可。

Base URL 注意：OpenClaw 的 openai-completions 适配器会在 baseUrl 之后自动追加 /chat/completions。因此这里要填写带 /v1 的 OpenAI 风格地址 https://api.tokenbay.com/v1，最终实际请求为 https://api.tokenbay.com/v1/chat/completions。 这是 OpenClaw 配置的特例——TokenBay 网关本身的 Base URL 是 https://api.tokenbay.com（不带路径），由客户端自行拼接 endpoint，OpenClaw 的 /v1 正是这一拼接的一部分。

1. 获取 API Key

登录 TokenBay 控制台 → API 密钥 → 创建密钥。复制以 sk- 开头的完整字符串。明文仅显示一次，离开页面后无法再查看。

2. 配置环境变量

OpenClaw 配置文件支持用 ${VAR_NAME} 引用环境变量，因此推荐把密钥放进环境变量，避免明文写进配置文件。OpenClaw 会读取父进程环境变量，也会读取当前目录的 .env 与全局的 ~/.openclaw/.env。

需要写入的变量：

macOS / Linux（zsh 或 bash）

把下面一行追加到 ~/.zshrc 或 ~/.bashrc，然后执行 source ~/.zshrc 让其生效：

export TOKENBAY_API_KEY="sk-XXXXXXX"

Windows（PowerShell，写入用户级环境）

[Environment]::SetEnvironmentVariable('TOKENBAY_API_KEY','sk-XXXXXXX','User')

Windows（CMD）

setx TOKENBAY_API_KEY "sk-XXXXXXX"

PowerShell 与 CMD 的写法都是永久化用户环境变量，需要新开一个终端窗口（并重启 Gateway）才会读到。

也可以直接写进 OpenClaw 的全局 env 文件 ~/.openclaw/.env：

TOKENBAY_API_KEY=sk-XXXXXXX

3. 在配置文件中注册 TokenBay provider

配置文件位于 ~/.openclaw/openclaw.json（用户级，全局生效）。Gateway 会监听该文件并自动热重载改动。把下面的 models 段合并进配置：

{
  "agents": {
    "defaults": {
      "model": { "primary": "tokenbay/claude-sonnet-4.6" }
    }
  },
  "models": {
    "providers": {
      "tokenbay": {
        "baseUrl": "https://api.tokenbay.com/v1",
        "apiKey": "${TOKENBAY_API_KEY}",
        "api": "openai-completions",
        "timeoutSeconds": 600,
        "models": [
          { "id": "claude-sonnet-4.6", "name": "Claude Sonnet 4.6", "input": ["text", "image"] },
          { "id": "claude-opus-4.8",   "name": "Claude Opus 4.8",   "input": ["text", "image"] },
          { "id": "claude-haiku-4.5",  "name": "Claude Haiku 4.5",  "input": ["text", "image"] }
        ]
      }
    }
  }
}

若不想引用环境变量，也可以把 apiKey 直接写成明文 "sk-XXXXXXX"（注意配置文件安全）。

备选：直接用 CLI 写入。 不想手动编辑 JSON 时，可用一行命令写值：

openclaw config set models.providers.tokenbay.baseUrl "https://api.tokenbay.com/v1"
openclaw config set models.providers.tokenbay.api "openai-completions"
openclaw config set models.providers.tokenbay.apiKey "${TOKENBAY_API_KEY}"

配置优先级：~/.openclaw/openclaw.json 是用户级全局配置；当前工作目录下的 .env 会优先于全局 ~/.openclaw/.env 提供环境变量（两者都不会覆盖进程中已存在的变量）。

4. 推荐模型

模型引用使用 provider/model，即在 TokenBay 模型名前加 tokenbay/ 前缀。常用选择：

tokenbay/ 后面的部分即 TokenBay 模型 ID，直接透传上游。要让某个模型可被选择，必须把它的 id 加入上文 models.providers.tokenbay.models[] 列表。完整可用列表见 模型清单。

注意：TokenBay 的模型名称中版本号仅接受小数点形式（如 claude-sonnet-4.6、claude-opus-4.8），不要写成连字符形式（claude-sonnet-4-6）。OpenClaw 内置插件示例里常见的连字符写法（如 opencode/claude-opus-4-6）只适用于那些插件，自定义 tokenbay provider 必须与 TokenBay 模型 ID 完全一致。

5. 进阶配置

把凭证、默认模型、可选模型白名单与超时设置合并到一份完整配置中。长任务（复杂推理、长上下文）耗时较长，可调大超时上限：

{
  "agents": {
    "defaults": {
      "timeoutSeconds": 600,
      "model": {
        "primary": "tokenbay/claude-sonnet-4.6",
        "fallbacks": ["tokenbay/claude-haiku-4.5"]
      },
      "models": {
        "tokenbay/claude-sonnet-4.6": { "alias": "Sonnet" },
        "tokenbay/claude-opus-4.8": { "alias": "Opus" },
        "tokenbay/claude-haiku-4.5": { "alias": "Haiku" }
      }
    }
  },
  "models": {
    "providers": {
      "tokenbay": {
        "baseUrl": "https://api.tokenbay.com/v1",
        "apiKey": "${TOKENBAY_API_KEY}",
        "api": "openai-completions",
        "timeoutSeconds": 600,
        "models": [
          { "id": "claude-sonnet-4.6", "name": "Claude Sonnet 4.6", "input": ["text", "image"], "contextWindow": 200000, "maxTokens": 8192 },
          { "id": "claude-opus-4.8",   "name": "Claude Opus 4.8",   "input": ["text", "image"], "contextWindow": 200000, "maxTokens": 8192 },
          { "id": "claude-haiku-4.5",  "name": "Claude Haiku 4.5",  "input": ["text", "image"], "contextWindow": 200000, "maxTokens": 8192 }
        ]
      }
    }
  }
}

说明：

• models.providers.tokenbay.timeoutSeconds 控制单次 provider HTTP 请求（连接、收发、流式）的超时；agents.defaults.timeoutSeconds 控制整个 Agent 运行的超时上限。provider 超时不能突破整体运行超时，两者都要调大长任务才不会被中断。
• 一旦设置了 agents.defaults.models，它会成为 /model 与会话切换的白名单：只有列在其中的模型可被选用。