OpenClaw 接入

OpenClaw 支持自定义模型提供商。将 RouteFast 的地址、密钥和模型注册到 models.providers，再把默认模型设为完整的 provider/模型ID，即可按本页进行接入检查。

本教程适用于本机 CLI 和本机 Gateway。

1. 选择接入路线

先在 RouteFast.AI 创建对应分组的密钥，并按 API 参考 检查该密钥可访问的精确模型 ID。

配置项	GPT 路线	Claude 路线
RouteFast 密钥分组	OpenAI-ChatGPT	Anthropic-Claude
本页自定义 provider ID	routefast-gpt	routefast-claude
baseUrl	https://api.routefast.ai/v1	https://api.routefast.ai
OpenClaw api 适配器	openai-responses	anthropic-messages
对应请求端点	/v1/responses	/v1/messages
示例模型 ID	gpt-5.6-terra	claude-sonnet-5
完整模型引用	routefast-gpt/gpt-5.6-terra	routefast-claude/claude-sonnet-5
密钥变量名	ROUTEFAST_OPENAI_API_KEY	ROUTEFAST_ANTHROPIC_API_KEY

模型示例必须以你的密钥目录为准；不可用时，同时修改下面配置中的模型 id 和默认模型引用。name 只是 OpenClaw 界面的显示名称，不能代替模型 ID。

openai-completions 在 OpenClaw 中指 Chat Completions 适配器，不是 Responses 的别名。只有确认所用 RouteFast 路由支持 /v1/chat/completions 时，才把 GPT provider 的 api 改为 openai-completions；baseUrl 仍为 https://api.routefast.ai/v1。本页默认沿用 RouteFast 的 GPT Responses 路线。不要将完整的 /responses、/chat/completions 或 /messages 路径填进 baseUrl。官方适配器参考

2. 安装与初始化

安装入口是 OpenClaw 官方安装文档。截至 2026-09-11，Node 要求为 24.16+ 的 24.x，或 26.1+ 的 26.x，官方推荐 Node 26；后续要求以该文档为准。

macOS / Linux / WSL 可使用官方安装器，并先跳过自动引导：

curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash -s -- --no-onboard

该命令会下载并执行官方安装脚本；需要先审阅脚本时，从 安装器说明 查看内容和选项后再执行。已有 OpenClaw 时先查看版本，无需为接入重复安装。

自己管理 Node 的用户，包括原生 Windows PowerShell 用户，可使用 npm。先检查版本：

node --version
npm --version

npm 12 或 npm 11.16+：

npm install -g openclaw@latest --allow-scripts=openclaw

npm 11.15 及更早版本不支持上述选项，使用：

npm install -g openclaw@latest

Windows 原生安装与 WSL 是独立环境，请在实际运行 Gateway 的一侧完成安装、配置和密钥设置。桌面伴侣应用的安装与配对请参阅 Windows 官方说明 或官方安装页；本页不把桌面应用的登录当作 RouteFast 鉴权。

安装后运行：

openclaw --version
openclaw config file

全新安装可以先运行以下命令，只初始化配置、工作区和会话目录：

openclaw setup --baseline

已有有效配置时跳过初始化。若版本不识别 --baseline，先核对 openclaw setup --help 和 官方 Setup 文档，不要换成带 --reset 的命令。普通 openclaw onboard 会进入引导并可能验证模型连接，产生实际请求；也可以按下文手动配置后再测试。

3. 找到配置并备份

以 openclaw config file 输出为准，默认路径为：

• macOS / Linux / WSL：~/.openclaw/openclaw.json
• Windows：%USERPROFILE%\.openclaw\openclaw.json

自定义 OPENCLAW_CONFIG_PATH、OPENCLAW_STATE_DIR、OPENCLAW_HOME 或 profile 会影响实际路径。CLI 与 Gateway 必须使用同一套配置和状态目录。官方环境与路径说明

用编辑器修改前，为实际配置文件保留一份带日期的备份，例如 openclaw.json.before-routefast-20260911；名称已存在时换一个名称。如果配置使用 $include，还要备份实际被修改的包含文件。备份可能带有原有密钥，也应保存在受保护的本机目录。

下面每个 JSON 是需要合并的配置片段。保留原来的 gateway、channels、工作区、工具权限和其他 provider；已有同名字段时修改原值，不要重复追加整个 agents 或 models 对象。模型数组中保留仍在使用的其他条目。

4. 设置密钥

本页使用 OpenClaw 的环境变量 SecretRef：配置保存变量引用，真实密钥由 Gateway 进程读取。官方 SecretRef 说明

本机长期使用时，用编辑器打开全局环境文件 ~/.openclaw/.env；Windows 默认是 %USERPROFILE%\.openclaw\.env。自定义状态目录时，对应文件是该状态目录下的 .env。只添加你准备启用的路线；同时启用两条路线则分别填写对应分组的 Key：

ROUTEFAST_OPENAI_API_KEY=替换为OpenAI-ChatGPT分组的真实密钥
ROUTEFAST_ANTHROPIC_API_KEY=替换为Anthropic-Claude分组的真实密钥

变量名由本教程自定义，必须与 JSON 中 apiKey.id 完全一致。值只填密钥，不要加 Bearer。该 .env 是明文文件，不要提交到 Git、同步到公开目录或放在 agent 工作区里；macOS / Linux / WSL 可限制现有文件权限：

chmod 600 ~/.openclaw/.env

Windows 用文件属性中的安全权限限制访问。团队环境也可以由密码管理器、服务配置或容器 Secret 向实际 Gateway 进程注入这些变量，无需写入 .env。

临时测试可在启动 Gateway 的同一终端设置变量。例如 macOS / Linux / WSL 的 GPT 路线：

export ROUTEFAST_OPENAI_API_KEY="sk-routefast-..."

Windows PowerShell：

$env:ROUTEFAST_OPENAI_API_KEY="sk-routefast-..."

这是占位示例；直接把真实密钥写入命令可能进入 shell 历史，优先使用受保护文件或秘密注入。Claude 路线使用 ROUTEFAST_ANTHROPIC_API_KEY。临时变量仅影响当前终端及其后启动的子进程，不会更新已经运行的服务。

OpenClaw 通常优先使用 Gateway 已有的进程环境，再读取全局 .env。修改 .env 后仍使用旧 Key 时，检查服务启动环境中的同名变量。项目 .env 属于较低信任来源，不应作为 provider 凭证的唯一来源。官方变量加载规则

5. 合并模型配置

方案 A：GPT Responses

{
  "secrets": {
    "providers": {
      "routefast-env": {
        "source": "env"
      }
    }
  },
  "agents": {
    "defaults": {
      "model": {
        "primary": "routefast-gpt/gpt-5.6-terra"
      }
    }
  },
  "models": {
    "mode": "merge",
    "providers": {
      "routefast-gpt": {
        "baseUrl": "https://api.routefast.ai/v1",
        "api": "openai-responses",
        "apiKey": {
          "source": "env",
          "provider": "routefast-env",
          "id": "ROUTEFAST_OPENAI_API_KEY"
        },
        "models": [
          {
            "id": "gpt-5.6-terra",
            "name": "RouteFast GPT",
            "input": ["text"]
          }
        ]
      }
    }
  }
}

方案 B：Claude Messages

{
  "secrets": {
    "providers": {
      "routefast-env": {
        "source": "env"
      }
    }
  },
  "agents": {
    "defaults": {
      "model": {
        "primary": "routefast-claude/claude-sonnet-5"
      }
    }
  },
  "models": {
    "mode": "merge",
    "providers": {
      "routefast-claude": {
        "baseUrl": "https://api.routefast.ai",
        "api": "anthropic-messages",
        "apiKey": {
          "source": "env",
          "provider": "routefast-env",
          "id": "ROUTEFAST_ANTHROPIC_API_KEY"
        },
        "models": [
          {
            "id": "claude-sonnet-5",
            "name": "RouteFast Claude",
            "input": ["text"]
          }
        ]
      }
    }
  }
}

两条路线可同时保存在 models.providers 中，共用一个 secrets.providers.routefast-env；agents.defaults.model.primary 只能选择一个默认值。不要把未填写环境变量的另一条 provider 也复制进去。

本页将输入声明为文本，仅用于首次验证。配置没有填写价格、上下文窗口、输出上限、推理能力或 compat 功能标志：OpenClaw 的默认或目录元数据不代表 RouteFast 的实际限额与计费。确认所选模型和协议支持某项能力后，再按官方字段说明调整。尤其不要因模型名称像 GPT 或 Claude，就直接启用图片、搜索、严格工具 schema 或特定推理参数。官方自定义模型注册说明

models.mode: "merge" 会合并目录。已有 ~/.openclaw/agents/<agentId>/agent/models.json 中同名 provider 的非空 baseUrl 可能优先于主配置；发现旧地址时先备份并检查对应 agent 的旧条目。不要通过删除整个 agent 状态目录解决覆盖问题。官方合并优先级

6. 校验并启动本机 Gateway

先在实际运行 Gateway 的环境中校验：

openclaw config validate
openclaw models status

第一条检查当前版本配置 schema；第二条查看默认模型与凭证来源。两者通过都不等于模型请求成功。models status --probe 会发真实请求，本页不把它放入基础检查。官方配置校验、Models CLI

全新安装还需要本机 Gateway 设置。将以下对象合并到配置顶层：

{
  "gateway": {
    "mode": "local",
    "bind": "loopback",
    "auth": {
      "mode": "token"
    }
  }
}

再生成本机 Gateway 令牌并校验：

openclaw doctor --generate-gateway-token
openclaw config validate

这组配置和命令面向全新安装。已有安装应保留有效的 Gateway 认证，确认仍使用本机 loopback 监听即可。Gateway 令牌用于本地 UI/CLI 连接 OpenClaw，与 RouteFast API Key 是两种不同凭证；不要互相填用。本页不启用 LAN、公网隧道或无认证访问。官方 Gateway 运行说明

首次测试可以在当前终端以前台模式启动：

openclaw gateway run

保持该终端运行，在另一终端检查并打开界面：

openclaw gateway status
openclaw tui

如果已经安装了 OpenClaw 管理的后台 Gateway 服务，修改配置或环境文件后使用以下命令生效，无需再启动第二个前台进程：

openclaw gateway restart
openclaw gateway status

仅用 export 设置 Key 后重启服务，仍可能读不到变量；后台服务应使用上面的全局 .env 或其自身秘密注入来源。若由 Docker 或其他 supervisor 管理，按实际管理方式重启。官方 Gateway 管理入口

前台测试通过且希望改为后台运行时，先用 Ctrl+C 停止前台 Gateway，再按官方说明执行 openclaw gateway install；它会安装并启动本机服务。

7. 先文本，再工具

在 TUI 中新建测试会话并检查当前选择：

/new
/model status

默认模型应是上面配置的完整 routefast-gpt/... 或 routefast-claude/... 引用。若会话保留了旧模型，可以显式选择：

/model routefast-gpt/gpt-5.6-terra

Claude 则使用 /model routefast-claude/claude-sonnet-5。再发送：

只回复“连接测试成功”，不要调用任何工具。

收到完整回答后，到 RouteFast 用量记录中核对时间、模型和费用。这是实际模型请求，可能产生费用。能打开 TUI 只说明本地客户端可连接 Gateway；openclaw models list 中出现模型只说明 OpenClaw 有对应目录记录，不证明该 Key 有权限或当前上游可用。官方 TUI、官方模型选择

文本通过后，在不含私密数据的测试工作区内准备一份简短文本，按 OpenClaw 的工具权限设置只授予该测试需要的读取权限，再请求模型读取它并返回首行。检查界面里确实出现工具调用、工具结果和最终回答，而不只是模型声称“已读取”。提示词本身不能限制文件或命令权限。

工具测试只验证该模型、协议与这次操作；文件编辑、命令执行、MCP、浏览器、图片及消息渠道需要按实际用途分别验证。已有 agent 的工具限制应按最小需求调整，不要为了连接成功全局关闭权限检查。官方工具与 agent 权限

常见问题

现象	优先检查
Invalid config、未知字段	运行 openclaw config validate，核对本机版本和报错路径；检查重复对象、逗号及引号，保留备份后逐项修正。
SecretRef 未解析或缺少密钥	apiKey.id 与环境变量名是否一致；routefast-env 是否声明为 source: "env"；运行 Gateway 的用户和状态目录是否正确。
终端可用，服务不可用	服务读不到当前 shell 的变量，或服务中旧变量优先；检查全局 .env，重启实际服务。
401 / 403	确认 Key 有效且属于该模型分组；区分本机 Gateway 认证错误与 RouteFast 上游错误，二者凭证不同。
404 或返回网页	核对 API 域名、baseUrl 及适配器；GPT 的 /v1 不要漏写或重复，Claude 使用根 URL。
模型不存在或不可访问	用当前 Key 检查 RouteFast 模型目录；保证 provider 中的 id 与默认引用后半段相同。
Model is not allowed	检查当前 agent 的 modelPolicy.allow；如需新增，只把目标 provider/模型ID 加入已有规则，保留其他限制。
改了默认模型但会话未变	用 /model status 检查会话固定选择，使用 /model default 清除该会话固定模型，或显式选本页模型；检查 per-agent 模型覆盖。
仍访问旧地址	检查实际配置路径、profile、运行中的旧 Gateway，以及对应 agent models.json 的合并优先级。
文本可用，工具或流式失败	记录失败阶段、模型、适配器、客户端版本和脱敏错误；先缩小为一次读取工具测试，再按错误确认具体协议字段，不要复制未知 compat 开关。
429、超时或上游错误	检查 RouteFast 用量、余额、限额和上游状态，降低并发；反复重试可能继续消耗配额。

当前官方把模型别名/参数与允许列表分开：agents.defaults.models 不单独注册自定义模型，允许列表使用 modelPolicy.allow。官方记录该独立允许列表自 v2026.8.1 引入；旧版本和未迁移配置可能仍有旧模型表限制，按本机 schema 和迁移说明处理，不能只照抄新版字段。官方模型规则与迁移

需要进一步诊断时可运行 openclaw doctor 或查看 openclaw logs --follow。分享日志前移除 API Key、Gateway token、用户消息和文件内容。doctor --fix 可能修改配置，先阅读修复建议并备份；不要将修复命令当作普通只读检查。

恢复原配置

先停止正在进行的测试，对照备份恢复原来的默认模型及相关每模型设置，再移除不再需要的 routefast-gpt / routefast-claude provider。若建立了 routefast-env 秘密来源，只有在没有其他引用时才移除它。已有新改动时按字段恢复，避免整份备份覆盖后续设置；也检查本次手动修改过的 agent models.json。

移除 .env 或服务秘密来源中本次添加的变量。当前 shell 的临时值可这样清理：

unset ROUTEFAST_OPENAI_API_KEY ROUTEFAST_ANTHROPIC_API_KEY

PowerShell：

Remove-Item Env:ROUTEFAST_OPENAI_API_KEY -ErrorAction SilentlyContinue
Remove-Item Env:ROUTEFAST_ANTHROPIC_API_KEY -ErrorAction SilentlyContinue

完成后运行 openclaw config validate，重新启动实际 Gateway，再用 openclaw models status 和会话 /model status 确认恢复。若原提供商还需登录或密钥，按其原有认证方式处理。仅删除 RouteFast provider 却保留默认模型引用，会留下不可用的配置。

官方文档

• OpenClaw：安装
• OpenClaw：Setup CLI
• OpenClaw：自定义 provider 与 Base URL 字段
• OpenClaw：自定义 provider 注册概念
• OpenClaw：环境变量
• OpenClaw：SecretRef
• OpenClaw：配置 CLI
• OpenClaw：模型 CLI