图标样例 原始文档

Gateway 导读

模型提供商认证：API Key 还是 OAuth？先分清场景再动手

这一页只讲模型提供商（Anthropic、OpenRouter 等）的认证方式，不是网关连接的认证。长期运行的网关首选 API Key，用 `export <PROVIDER>_API_KEY` 或写入 `~/.openclaw/.env` 即可。最容易搞错的是：OAuth 模式的 auth profile 不支持 SecretRef 凭证（`keyRef`/`tokenRef` 会被拒绝），且 Anthropic 的 Claude CLI 复用路径已恢复，但 API Key 仍是更稳定的选择。

先讲这一页到底在解决什么

模型提供商认证：API Key 还是 OAuth？先分清场景再动手

这一页只讲模型提供商（Anthropic、OpenRouter 等）的认证方式，不是网关连接的认证。长期运行的网关首选 API Key，用 `export <PROVIDER>_API_KEY` 或写入 `~/.openclaw/.env` 即可。最容易搞错的是：OAuth 模式的 auth profile 不支持 SecretRef 凭证（`keyRef`/`tokenRef` 会被拒绝），且 Anthropic 的 Claude CLI 复用路径已恢复，但 API Key 仍是更稳定的选择。

原文共 13 节，先看 Start Here 路径：/gateway/authentication 查看官方原文

第一步

🏠 先记住一个大原则：Gateway 长住时，API key 往往最省心

官方这里一上来就说得很实在。长期跑的 Gateway，最可预测的通常就是 API key。

🗝

API key

像一把固定的门卡，放在 gateway host 上，比较直来直去，也最容易保持稳定。

🧾

OAuth

像按正规流程办入场手续。不是不好，而是要和供应商的账号体系对得上。

🎟

setup-token

像 Claude 订阅票那一类门票。能用，但要看规则和风险提示。

📌

一句话

能拿 API key，就先把门卡放稳。别一开始就让系统去猜复杂门禁。

最稳的做法

🔑 把钥匙放在 gateway host 上，而不是把它记在嘴上

官方给的第一套推荐流程很像“先把钥匙放到房间里，再让值班员自己取”。

1. 在供应商控制台申请 key

像先去办一张新门卡，再带回家。

2. 放到 gateway host

门卡要放在真正跑 openclaw gateway 的那台机器上，不是放在别人的包里。

export <PROVIDER>_API_KEY="..."

这像临时把门卡挂在墙上，方便当前这一趟先用。

~/.openclaw/.env

如果 Gateway 是长期值班的，官方更建议把钥匙放进这本固定的小抽屉里。

命令翻译

🧪 这些检查命令，像值班员先试试门卡好不好使

别把它们看成纯命令。它们其实是在确认“这把钥匙真的能开门”。

🔍

openclaw models status

像值班员先看一眼：“门卡在不在？有没有快过期？”

🩺

openclaw doctor

像请体检医生再扫一遍整套门禁和房间状态。

📎

onboarding 也能存 key

如果你不想自己手动摆抽屉，openclaw onboard 也能帮你把钥匙收好。

📌

一句话

先放钥匙，再验门卡，再让系统值班。

特殊门票

🎫 setup-token 像“Claude 订阅票”，但官方提醒你别把它当万能钥匙

这部分要看得很清楚。能用，不代表每次都适合用。

claude setup-token

像在 Claude 那边先拿一张订阅票，准备带回来给 OpenClaw 用。

openclaw models auth setup-token --provider anthropic

像把那张票轻轻塞进 OpenClaw 的门禁夹里。

openclaw models auth paste-token --provider anthropic

如果票是在别的机器上拿的，就手动抄回来，再贴到对应位置。

警告

官方特别提醒：这是兼容路线，不是无条件推荐路线。政策风险要自己确认。

命令翻译

🏁 Claude CLI 迁移，像“把老门卡换到新门卫体系里”

如果机器上已经有 Claude CLI，还能把现成登录状态迁过去，不必重新从头贴票。

🚚

openclaw models auth login --provider anthropic --method cli --set-default

像把旧门卡搬进 OpenClaw 的新门禁柜里，还顺手把默认通道改好。

✉️

openclaw onboard --auth-choice anthropic-cli

像新手引导直接问：“你是想沿着 Claude CLI 这条路走吗？”

🧭

默认模型也会跟着变

官方说明会把默认模型切到 claude-cli/...，并把相关 allowlist 也补上。

📌

一句话

能搬就搬，但搬完要记得把默认路也一起改好。

最后总结

🎈 把这页压成一句最短的话

Authentication 就是在给 Gateway 配门卡：长住时先用 API key，复杂门票像 setup-token 要谨慎，检查命令则是在提醒你钥匙有没有真的放对、拿对。

下一页如果你想看“系统开机后，后台小火车怎么跑”，就去 /gateway/background-process。