OpenClaw自定义中转站配置教程：从模型API接入到故障转移实战

最近我一直在折腾 OpenClaw 新版的部署，这项目是一个开源的多端自动化智能体框架，可以用自然语言驱动本地脚本、浏览器操作、文件管理和各类 API 调用。新版内核改了不少东西，连接层也重做了，但社区里被问得最多的问题反而是最基础的：自定义中转站到底怎么配？

我也不是一开始就搞明白的。翻了文档、看了日志、试了几种中转服务，总算把新版的配置逻辑理清楚了。这篇直接把我的配置方案、踩坑记录和排查经验全放出来，看完你基本能自己搞定。

1. 先搞清楚为什么要配中转站

1.1 不配中转站会遇到什么问题

OpenClaw 最核心的工作，是把 AI 能力接进来，然后根据用户指令去调度工具、执行脚本。它本身不内置大模型，需要对接外部模型 API。问题就出在这个“对接”上。

如果你直接用默认配置去连模型服务商，会遇到几个非常实际的情况：

• 某些模型服务商的接口在部分地区访问质量不稳定，请求经常超时或者断连，不是你本地网络的问题，是链路本身的问题。
• 你需要同时对接多个模型服务商，比如对话用一个平台，工具调用用另一个平台，如果每个平台单独配置密钥和地址，管理起来非常乱。
• 有些团队的模型服务商是在内网或自有网关后面的，OpenClaw 直接访问不了，必须通过内部中转。
• 出于安全和审计的考虑，你不想把各个服务商的密钥分别暴露给不同模块，而是放在一个统一入口后面。

简单说，中转站就是你模型流量的统一入口。OpenClaw 把请求发给中转站，中转站再把请求转发给真正的模型服务商。这样 OpenClaw 只需要认识一个地址、一个密钥，剩下的事情都交给中转层处理。

1.2 新版中转配置的设计思路

我对比了一下老版本，新版最大的变化是配置结构更清晰了。老版本把中转地址、密钥、模型路径都堆在同一个连接配置里，容易漏配，而且出了问题不好定位。新版把“模型服务商选择”“中转站地址”“请求路由策略”拆成了独立模块，配置项反而更直观。

还有一个细节，新版支持了“自动降级”机制。也就是说，你配置了多个中转站之后，如果第一个中转站不可用，OpenClaw 会自动切换到下一个可用节点。这个功能听起来很美好，但配置的时候有坑，后面我会专门讲。

2. 配置前的准备工作

2.1 确认你的 OpenClaw 版本

开始配置之前，一定先确认版本。老版本和新版的配置项字段名有差异，直接拿网上老教程复制粘贴大概率会报错。

在命令行执行：

openclaw --version

如果输出是 2.0 及以上版本，那就可以直接按这篇的配置来。如果你的版本在 2.0 以下，建议先升级，因为新版改了很多底层 API，老版本继续用自定义中转容易出兼容问题。

升级命令一般是这样：

openclaw update

或者去项目官网下载对应平台的新安装包。升级之后，先启动一次，让它生成默认配置文件，再继续操作。

提示：升级后第一次启动可能提示“发现新版配置文件”，不用手动处理，它会自动生成一份新的模板。但如果你之前手动改过配置，最好先备份老配置再来升级。

2.2 拿到中转站的三个关键信息

不管用什么中转服务，你都需要准备三样东西：

1. 中转站的 API 地址。格式一般是https://中转站域名/v1，注意有些中转站不需要带/v1，这个要看服务商的接入文档。
2. 中转站分配的密钥。通常是一串以sk-开头的字符串，与模型服务商平台的密钥格式一致。
3. 你想使用的模型名称标识。比如某个聚合平台上的模型 ID，并不一定跟原厂的模型名完全一样，必须以中转站提供方给的文档为准。

我习惯把这几个信息先写到记事本里，配置的时候直接复制粘贴，避免手敲出错。手敲密钥真的很容易错，而且错了之后报错信息还特别不明显。

2.3 确认配置文件位置

新版 OpenClaw 的配置文件默认位置如下：

• Linux / macOS：~/.openclaw/config.yaml
• Windows：%USERPROFILE%\.openclaw\config.yaml

如果你不知道自己的配置文件在哪，执行：

openclaw config --show

它会直接打印出当前生效的配置文件路径。这一步很重要，因为有些人用的是便携版，配置目录可能在安装目录下，不一定在用户目录里。

3. 新版配置文件逐项解析

3.1 找到模型连接段落

打开配置文件，你会看到类似这样的结构。我先展示一份包含中转站配置的精简版本：

model: provider: relay base_url: https://api.example-relay.com/v1 api_key: ${OPENCLAW_API_KEY} default_model: claude-3.5-sonnet-relay timeout: 60 relay: enabled: true failover: true endpoints: - url: https://api.example-relay.com/v1 weight: 10 - url: https://backup.example-relay.com/v1 weight: 5 health_check: interval: 120 request_path: /models

这里每个字段的作用我逐一说明。

model.provider表示使用哪种连接模式。新版里常见的值有direct（直连模型服务商）和relay（中转站模式）。我们要做自定义中转，这里就填relay。

model.base_url是中转站的基础地址。注意，OpenClaw 会在请求时自动拼接/chat/completions路径，所以base_url只需要写到根路径那一级。如果你填成https://xxx/v1/chat/completions，反而会拼出错误的 URL，这是我刚开始踩得最痛的坑。

model.api_key填中转站给的密钥。我建议不要直接把密钥明文写进配置文件，而是先用环境变量占位。比如填${OPENCLAW_API_KEY}，然后在系统环境变量里设置好OPENCLAW_API_KEY。这样配置文件即使被同步到网盘、代码仓库，也不会泄露密钥。

model.default_model填默认使用的模型标识。这个标识一定要以中转站服务商给的模型列表为准。有时候你以为填gpt-4o就行，但中转站那边可能映射成了gpt-4o-custom-2025，填错了启动时能过，实际发请求会 404。

timeout是请求超时时间，单位秒。默认一般是 30。但从实际体验看，模型推理本来就需要时间，如果你在跑长文本生成或者复杂工具调用任务，30 秒很容易不够。我一般设到 60 甚至 90，宁可等得久一点，也不要动不动超时中断。

3.2 后端节点配置细节

新版relay.endpoints是一个中转站节点列表，可以填多个。每个节点有url和weight两个属性。

weight是权重值，默认是 1。OpenClaw 会按照权重比例把请求分配到不同节点。我举个例子：节点 A 的 weight 是 10，节点 B 的 weight 是 5，那么每 3 次请求里大约有 2 次走 A、1 次走 B。

但这里有个关键细节，failover: true只代表“自动故障转移”，跟“负载均衡”是两回事。故障转移说的是节点 A 不可用的时候，请求自动落到节点 B；而负载均衡是在所有节点都健康的情况下，按权重分发流量。所以如果你只配置了一个节点，不要以为有了 failover 就万事大吉。

另外，health_check是节点健康检查。OpenClaw 会每隔一段间隔去请求一次中转站的/models接口，来判断节点是否可用。如果你的中转站服务商不支持/models接口，可以把request_path改成/v1/models，具体以对方文档为准。

注意：health_check的时间间隔不要设太短，比如 10 秒一次。中转站不是专门为你一个人服务的，频率太高容易被限流。一般 120 秒是比较合适的起步值。

4. 三种常见中转方案的配置示例

4.1 云中转服务商

这是最省事的配置方式，适合个人用户快速跑起来。你在某个模型聚合平台上注册账号，转账充值，拿到密钥，然后就能用一个地址访问多个模型服务商。

配置示例：

model: provider: relay base_url: https://api.unified-example.com/v1 api_key: sk-example-1234567890 default_model: gpt-4o timeout: 60

这里只要注意两点。第一，确认中转服务商要求的base_url是否带/v1，不要想当然。第二，确认模型标识，因为有些聚合平台会把模型名改成自己的格式。

我见过最典型的错误是：在聚合平台上选了“智能对话模型”，复制出来的模型 ID 是一串乱码或者专属代号，结果用户拿原厂的模型名去填，一直报模型不存在。

4.2 企业内部统一网关

如果你所在团队自己有模型接入网关，那么 OpenClaw 走企业内部网关会安全很多。典型的网关会统一鉴权、记录日志、控制访问权限。

配置时通常只需要把base_url指向内部网关域名，并且把密钥换成由内部管理平台生成的令牌。如果网关要求额外的请求头，OpenClaw 也支持自定义 headers 配置：

model: provider: relay base_url: https://gateway.internal.example.com/v1 api_key: sk-internal-token default_model: internal-llm-pro timeout: 90 headers: X-Gateway-Token: "内部网关签发的令牌" X-Tenant-ID: "your-tenant-id"

这个自定义 headers 功能在新版里很实用。因为很多企业的网关并不只是用标准 Authorization 头，还会检查租户 ID 或者应用 ID。

我第一次配企业网关的时候，没加X-Tenant-ID，请求返回 403。日志里只写了“forbidden”，我看半天没搞明白到底哪里错了，后来把网关返回的响应体完整打印出来才发现是缺了租户标识。

4.3 本地自建轻量转发

如果你手头有云服务器，也可以自己搭一个轻量转发层。这样做的目的通常不是为了省key钱，而是为了保证 OpenAI 兼容接口格式的统一，或者加一层缓存。

我试过比较简单的方案是用 Nginx 做反向代理，配置大概是这样：

location /v1/ { proxy_pass https://upstream-model.example.com/v1/; proxy_set_header Authorization $http_authorization; proxy_set_header X-Backend-Key "后端key"; }

这样 OpenClaw 的base_url指向https://你的域名/v1，密钥填你自己的 API 密钥，Nginx 会透传给上游。

自建方案的好处是可控，坏处是运维成本上来了。如果你就一个人跑着玩，我建议直接用云中转，别自建。别高估自己维护服务的精力，除非你有现成的服务器和监控体系。

5. 配置完成后的验证方法

5.1 用内置命令测试连通性

配置好之后，先别急着跑复杂任务。OpenClaw 自带一个连接测试命令：

openclaw doctor

这个命令会依次检查配置格式、密钥格式、网络连通性、中转站接口可用性。如果哪一步有问题，它会用比较清晰的提示标出来。

我自己的习惯是：改完配置一定跑一次openclaw doctor，看到“all checks passed”才继续。这个方法能帮你过滤掉 80% 的低级配置错误。

5.2 手动发一个最小请求

有时候doctor检查的是连通性，不代表模型调用就真的能通。我建议再手动发一个最小请求，验证真实推理链路。最简单的办法是直接用curl：

curl -X POST https://api.example-relay.com/v1/chat/completions \ -H "Authorization: Bearer sk-example-123" \ -H "Content-Type: application/json" \ -d '{ "model": "gpt-4o", "messages": [{"role": "user", "content": "hi"}] }'

如果返回了一段 JSON，里面有choices字段，说明中转站的接口是通的。如果返回的是 404 或者提示模型不存在，那就要检查model字段的值，或者直接去中转站的模型列表页复制一个合法的模型名。

5.3 用对话命令验证完整链路

接口通了之后，再进入 OpenClaw 的交互模式，跑一次真实的对话：

openclaw

然后在提示符里输入：

你说一句话试试

如果 OpenClaw 能正常回复，并且日志里显示请求通过你的中转站地址发出，那自定义中转配置就算基本成功了。这时候建议看一眼/models接口的文档，顺手确认一下默认模型的实际名称。

6. 我踩过的配置坑（新手必看）

6.1 地址末尾多了一个斜杠引发的血案

配置项base_url里面，末尾的/真的很重要。OpenClaw 内部拼路径时是直接用字符串拼接的，不会帮你处理斜杠。

如果你填：

https://api.example-relay.com/v1/

而 OpenClaw 拼接出：

https://api.example-relay.com/v1//chat/completions

某些中转站会把双斜杠当成非法路径，直接返回 404。有些服务器会容错，但你不能赌它一定容错。标准做法是：base_url末尾不带斜杠。

我在这个问题上折腾了半个多小时，最后抓请求日志才发现 URL 长了一截。这种问题特别隐蔽，因为一眼望过去，配置貌似没啥毛病。

6.2 密钥里的特殊字符必须处理

中转站生成的密钥有时候会包含+、/、=之类的字符。如果你把密钥直接填在 YAML 文件里，/和某些组合会被 YAML 解析器误解。

解决办法有两个：

• 整个密钥用双引号包起来：api_key: "sk-xxx+yyy/zzz="
• 更推荐的方式：用环境变量引用，比如${OPENCLAW_API_KEY}，然后在环境变量里放原始值

我推荐第二种。因为 YAML 的转义规则在不同解析器下不完全一致，你用双引号包了可能没问题，但别人复制你的配置时不一定会注意引号是否完整。环境变量一劳永逸。

6.3 模型名填了名称版本号但中转站用的是 ID

这是个很常见的坑。很多中转平台为了统一管理模型，给模型起了一套内部 ID，比如gpt-4o-new、sonnet-0709-v2。你用原厂的模型名去填，根本找不到。

每次配置新中转站，都先去它的文档页面，找到“模型列表”那一页，复制它展示的那个 ID 和名称，而不是凭记忆填。

6.4 多个中转节点之间的超时设置不一致

failover看似是自动故障转移，但如果两个节点响应速度差异太大，OpenClaw 默认的请求超时时间又是同一个，那很可能会出现节点 A 在 60 秒超时后还没等到响应，节点 B 却早就在 3 秒内返回了，但请求还在被 A 卡着。

我建议如果各节点延迟差距明显，就把timeout拉到 90 秒以上，并且在relay段里单独设置每个节点的请求超时参数。目前新版支持节点级配置，可以把慢节点的超时时间放长，快节点的超时时间放短。别以为这只是小事，真实场景里非常影响使用体验。

7. 常见问题与排查实录

7.1 401 Unauthorized

看到 401，第一反应就是密钥有问题。排查顺序：

1. 密钥是否复制完整，有没有多余空格。
2. 密钥是否被 YAML 解析破坏，比如没加引号导致的特殊字符吞掉。
3. 密钥在环境变量里是否生效。设置完环境变量后，要重启 OpenClaw 进程，别指望热加载。
4. 中转站的密钥是否绑定了 IP 白名单。如果绑了白名单，而你本机 IP 不在里面，也会 401。

7.2 404 Not Found

这个一般是路径或模型名不对。排查顺序：

1. 抓请求日志，看看实际请求的完整 URL，有没有双斜杠，有没有多拼一层路径。
2. 确认模型名是否跟中转站提供的完全一致。
3. 确认你在中转站账户里有没有开通对应模型的权限。有些平台每个模型需要单独开通，没开通就返回 404。

7.3 请求超时

如果请求卡住直到超时，先区分是网络不通还是接口响应慢。用 curl 手动发请求，测量一下实际耗时：

curl -w "耗时: %{time_total}s" -X POST https://api.example-relay.com/v1/chat/completions ...

如果中转站本身响应就要 30 秒以上，那 OpenClaw 的 timeout 设成 30 肯定不够。把 timeout 调到 90 或 120 再试。如果中转站响应很快，但 OpenClaw 仍然超时，那问题可能在 DNS 解析或本地代理环境上，建议检查系统网络设置。

7.4 返回格式不合法

OpenClaw 依赖标准格式来解析模型返回结果。如果你用的中转站做了很多格式转换，结果可能看起来正常，但 OpenClaw 解析失败。这时候日志一般会提示invalid response format或类似信息。

解决办法：优先选择兼容主流格式的中转服务。如果确实要用，可以看看中转站有没有“协议模式”开关，有的话切换到兼容模式。

7.5 如何抓 OpenClaw 的请求日志

排查问题最有效的方式就是看日志。新版 OpenClaw 默认会输出简要日志，但要看到请求级信息，需要开启调试模式：

openclaw --log-level debug

在 debug 模式下，所有出站请求的 URL、状态码、响应头都会打印出来。我配置自定义中转时，基本都开着 debug 模式，调通之后再关掉。建议新手也这么做，能省大量猜测的时间。

8. 进阶技巧与经验心得

8.1 多中转站容灾配置参考

如果你对可用性要求比较高，可以参考下面这套配置：

model: provider: relay api_key: ${OPENCLAW_API_KEY} default_model: gpt-4o timeout: 90 relay: enabled: true failover: true endpoints: - url: https://relay-a.example.com/v1 weight: 10 - url: https://relay-b.example.com/v1 weight: 5 - url: https://relay-c.example.com/v1 weight: 1

权重越大，被分配到的请求越多。把最稳定的节点放在第一位并给一个大权重，其余节点作为兜底。我一般习惯把备用节点的权重设得小一点，但不要设成 0，否则故障转移时它也可能被跳过。

8.2 环境变量管理密钥的一点建议

用环境变量虽然安全，但自己在终端里 export 很容易忘。我建议在.bashrc或.zshrc里写：

export OPENCLAW_API_KEY="sk-example-xxx"

如果你用 Windows，就在系统环境变量里新增OPENCLAW_API_KEY，然后重启终端。配置完记得验证：

echo $OPENCLAW_API_KEY

确保能正确打印密钥，再去重启 OpenClaw。

8.3 定期检查中转站健康状态

配置好之后也不是一劳永逸。中转站可能因为账户余额不足、服务商调整域名等原因突然不可用。我的习惯是每周跑一次：

openclaw doctor

顺手看看日志里有没有大量超时记录。如果发现某个中转站连续几次检查不通过，该换就换，别等到项目正在跑关键任务时才掉链子。

8.4 后续可以扩展的方向

配置好自定义中转站之后，你还可以进一步折腾：

• 对接多个模型服务商，按任务类型自动路由。比如简单任务用响应快的轻量模型，复杂任务用更强的推理模型。
• 加上请求缓存。如果经常问重复的问题，在中转层加一层语义缓存，能省不少模型调用费用。
• 接入监控面板，把所有模型请求耗时、成功率、费用汇总成一个看板。这个对团队协作尤其有意义。

我自己目前就在用 OpenClaw 搭配多中转节点跑自动化任务，实际用下来，最大的感受是：自定义中转配置本身不难，难的是搞清楚每个字段的作用，以及在你自己的网络环境和服务商之间找到最合理的参数组合。只要配置正确，OpenClaw 的模型调用就能变得非常顺滑，基本感觉不到中转层的存在。

如果再遇到配置问题，别急着改参数，先看日志，再用 curl 手动测，一步一步缩小范围。这套排查思路比死记硬背任何教程都管用。