OpenClaw 配置 api 指南：从 API Key、baseUrl 到 models.providers 一次讲清

很多人把 OpenClaw 装好之后，真正卡住的不是安装命令，而是这一步：

• OpenClaw 配置 api 到底改哪个文件
• API Key 应该放环境变量，还是直接写进 openclaw.json
• baseUrl 应该写根域名，还是写到 /v1
• 为什么模型看起来配好了，聊天窗口还是不回

如果你搜的是 OpenClaw 配置 api，大概率不是想看概念介绍，而是想尽快把模型入口接通。这篇文章会直接围绕 OpenClaw 配置 api 的关键路径展开：先确认配置入口，再写 provider，再验证是否真的生效。

快速结论

• 截至 2026-03-22，OpenClaw 官方文档仍然把 models.providers 作为自定义 provider 和代理入口的标准写法
• 一篇靠谱的 API 接入配置，核心就 3 个字段：baseUrl、apiKey、api
• 如果你准备接第三方聚合入口，apiKey 更适合放环境变量，再在配置里用 ${ENV_NAME} 引用
• 配置改完以后，不能只看文件保存成功，还要跑 openclaw models status、openclaw models list，再去聊天里试 /model status
• 如果你已经设置了 agents.defaults.models 允许列表，这套接入即使写对了，也可能因为模型没进 allowlist 而直接被拦下

正式接入前，先确认你要改哪一层

先把一个常见误区说清楚。很多人以为这件事就是“把一个 Key 填进去”，但 OpenClaw 的模型入口其实分三层：

1. 向导层：openclaw onboard，适合第一次初始化
2. 命令层：openclaw models set、openclaw models status，适合切默认模型和查状态
3. 配置层：~/.openclaw/openclaw.json 里的 models.providers，适合真正长期维护

对绝大多数开发者来说，真正稳定的落点还是配置层。原因很简单：你需要的不只是“当前会话能用”，而是 Gateway 重启以后、聊天渠道切换以后、换模型以后依然能用。

OpenClaw 官方文档在 Model Providers 页面里写得很明确：models.providers 用来添加自定义 provider，或者添加 OpenAI / Anthropic 兼容代理入口；配置参考页也列出了 models.providers.*.api、apiKey、baseUrl、models 这些字段。这意味着只要你的上游支持兼容协议，这套接法就不需要改源码，直接走配置文件即可。

这里还要区分两类来源。第一类是 OpenClaw 自带 catalog 的内置 provider，比如 openai、anthropic，这种场景通常只要补认证信息，再挑一个模型即可；第二类是你自己增加的聚合入口、代理入口或局域网网关，这时才需要手动写 models.providers。很多人把这两类混在一起理解，才会出现“官方 provider 明明能选，为什么我还要手写 JSON”的疑惑。

如果你还没跑过初始化，建议先执行一次：

openclaw onboard
openclaw config file

前一个命令用来把工作区、网关端口和基础配置生成出来，后一个命令用来确认当前实际读的是哪份配置文件。很多人做这类接入失败，不是字段写错，而是改错了文件。

API 接入常见有三条路线

从实际使用场景来看，这件事也可以按“临时能用”和“长期稳定”分层来看：

如果你只是测试一下官方 provider，向导很省时间；如果你已经把 provider 配好，只是想在 Claude、GPT、DeepSeek 之间切换，那就用 CLI。
但如果你的目标是：

• 接一个统一的 API 中转入口
• 自己定义模型列表
• 让 Web UI、CLI、聊天渠道共用同一套配置

那 API 接入就应该直接落在 models.providers。这也是为什么很多“我明明切过模型，但新会话又恢复了”的问题，根源并不在切模型命令，而在默认 provider 没有配置好。

还有一个细节值得单独提一下。OpenClaw 官方文档强调模型引用按第一个 / 做切分，也就是 provider/model 这种结构。如果你接的是聚合入口，模型名里本身又带有额外斜杠，例如某些 OpenRouter 风格的模型 ID，就必须把 provider 前缀写全，不然 CLI 和聊天层会把你的输入解析错。这也是接入明明成功、但 /model 仍然切不过去的常见诱因。

用 api.clawsocket.com 做 OpenClaw 配置 api 的完整示例

下面给一套更适合国内开发者长期使用的写法。思路不是把 Key 硬编码进配置，而是把 Key 放进环境变量，再让 OpenClaw 从配置文件里引用它。

先准备环境变量：

export CLAWSOCKET_API_KEY="你的 API Key"
echo 'export CLAWSOCKET_API_KEY="你的 API Key"' >> ~/.zshrc
source ~/.zshrc

然后在 ~/.openclaw/openclaw.json 里写 provider。下面这份示例的重点，不是模型名字本身，而是你要看懂这套 provider 接法的骨架：

{
  agents: {
    defaults: {
      model: {
        primary: "clawsocket/gpt-5.4",
        fallbacks: ["clawsocket/claude-sonnet-4-6"]
      },
      models: {
        "clawsocket/gpt-5.4": { alias: "GPT 5.4" },
        "clawsocket/claude-sonnet-4-6": { alias: "Sonnet 4.6" }
      }
    }
  },
  models: {
    mode: "merge",
    providers: {
      clawsocket: {
        baseUrl: "https://api.clawsocket.com/v1",
        apiKey: "${CLAWSOCKET_API_KEY}",
        api: "openai-completions",
        models: [
          { id: "gpt-5.4", name: "GPT-5.4" },
          { id: "claude-sonnet-4-6", name: "Claude Sonnet 4.6" }
        ]
      }
    }
  }
}

这里可以把这套接法的 4 个关键点拆开理解：

• baseUrl：上游接口地址。如果你接的是 OpenAI 兼容中转，通常要写到 /v1
• apiKey：建议引用环境变量，不要把真实 Key 长期明文散落在文件里
• api：告诉 OpenClaw 该用哪套请求适配器。兼容 OpenAI chat/completions 的入口，常见就是 openai-completions
• models：把你实际允许调用的模型显式列出来，这样 openclaw models list 和聊天内切换都更清晰

官方配置参考还提到一个容易被忽略的点：空的 agent apiKey 或 baseUrl 会回退到 config 里的 models.providers；如果你想让配置完全覆盖 agent 目录下已有的 models.json，可以考虑 models.mode: "replace"。这类细节在长期接入场景里很重要，因为很多“改了不生效”的案例，本质上是 merge 后读到了旧 provider。

merge 和 replace 的选择，也决定了你排查问题的路径。如果你本机之前已经跑过别的 provider，或者旧的 agent 目录里还残留一份 models.json，那 merge 会把新旧信息拼在一起，优点是改动小，缺点是更容易把旧配置一并带进来；replace 更干净，但要求你对当前模型目录有把握。大多数用户第一次接第三方入口时，先用 merge 比较稳，等确认目录结构和 provider 命名没有历史包袱，再决定是否切到 replace。

OpenClaw 配置 api 之后，怎么确认它真的生效

一篇有用的接入教程，不该停在“把 JSON 贴出来”。更关键的是验证路径。官方 CLI 文档里已经给出三组非常实用的命令：

openclaw models list --plain
openclaw models status --plain
openclaw models status --probe

你可以这样理解：

• list 看的是 OpenClaw 现在认得哪些模型
• status 看的是当前默认模型和认证概览
• --probe 会做实时探测，适合判断 API Key 和上游接口是不是真的能通

回到聊天窗口，再做一轮会话级确认：

/model
/model list
/model status
/model clawsocket/gpt-5.4

如果 OpenClaw 配置 api 已经生效，你通常会看到两个变化：一是 /model list 里已经出现你自定义 provider 下的模型；二是 /model status 会显示当前 provider 的模型引用。如果 CLI 能看到模型，但聊天里切不过去，优先怀疑允许列表而不是 API 本身。

这里建议你把输出读得更细一点。openclaw models status 不只是告诉你“默认模型是谁”，它还会显示认证概览；如果某个 provider 缺凭证，官方文档说明它会出现 Missing auth 区块。换句话说，能列出模型，不代表运行时鉴权一定成功；能看到默认模型，也不代表请求一定会发到你想要的 baseUrl。把这两个层面拆开看，排错速度会快很多。

更稳的做法是把检查顺序固定下来：先看 provider 名称是否和配置文件一致，再看默认模型引用是不是你刚写进去的那条，接着确认 baseUrl 有没有被旧配置覆盖，收尾再用聊天内的 /model status 看会话层是否读到了同一条模型引用。这样做的好处是，一旦某一步结果对不上，你就能立刻判断问题是在配置文件、进程环境、还是会话状态，而不是在多个方向上来回猜。

OpenClaw 配置 api 最容易踩的 4 个坑

1. 改了配置，却不是当前正在读取的文件

这在 API 接入场景里非常常见。尤其是你同时有多个 agent、多个工作区，或者之前跑过向导，实际生效文件未必是你手改的那份。最稳的动作是先执行 openclaw config file 和 openclaw models status，确认当前读取路径和默认模型。

2. API Key 已经更新，但 Gateway 进程还拿着旧环境变量

你在 shell 里 source ~/.zshrc 不代表已运行的 Gateway 进程也同步拿到了新 Key。遇到这种情况，这套接入看起来像是“文件没问题，但请求一直失败”。更稳的做法是更新环境变量后重启 Gateway，再重新看 models status --probe。

3. 模型已经存在，但被 allowlist 拦住了

截至 2026-03-22，OpenClaw 中文模型文档里仍明确写着：如果设置了 agents.defaults.models，它就会成为 /model 的允许列表。不在列表里的模型会直接返回 Model "provider/model" is not allowed。这类问题和 provider 配置不是一回事，但表现出来很像“接口挂了”，所以排查时要把它单独拎出来看。

4. 把所有 provider 都按同一种 baseUrl 规则写

做这类接入时，不要形成“所有上游都加 /v1”的惯性。像 OpenAI 兼容聚合入口通常要写 /v1，但某些原生 provider 不走这套规则。OpenClaw 官方 provider 文档里就专门提醒过：不同 provider 的 baseUrl 约定并不相同，照抄别家示例很容易把接口路径写错。

什么时候该用命令，什么时候该继续改配置

把这件事拆开看，会更清楚一点：

• 你只是临时对比两个模型的效果，用 /model
• 你想改默认模型，用 openclaw models set
• 你要做完整的 OpenClaw 配置 api，用 openclaw.json 里的 models.providers

这个顺序很重要。因为 /model 和 models set 解决的是“选哪个模型”，而 OpenClaw 配置 api 解决的是“这些模型从哪个 provider 进来、用什么鉴权、请求发到哪”。两者是同一条链路上的不同层次，不能互相替代。

如果你准备长期把 GPT、Claude、Gemini 这类模型都放到一个统一入口里，配置文件路线通常更省事。你只需要维护一套 Key 管理方式、一套 baseUrl、一组模型映射，后面无论切默认模型还是扩充模型目录，心智成本都会低很多。

如果你本身就管理多把 Key，还可以顺手利用官方文档提到的轮换变量规则。以 provider 为前缀的 <PROVIDER>_API_KEYS、<PROVIDER>_API_KEY_1 这类环境变量，可以在部分 provider 上做顺序轮换。它不是所有场景都必需，但在高并发或多人共用网关时很有价值，因为你不用把所有压力都压在一把 Key 上，也更容易把额度和错误排查分开。

对团队环境来说，这一步提前设计好，后面迁移模型时会轻松很多。

OpenClaw 配置 api 常见问题

为什么我已经能打开 dashboard，模型还是不返回

Dashboard 能打开，只能说明 Gateway 起来了，不代表这套接入一定正确。真正决定是否能出字的，是 provider 的 apiKey、baseUrl、api 适配器，以及你选中的模型是否在允许列表里。

Key 放环境变量还是写死在配置里

日常开发更推荐环境变量。原因不复杂：换 Key、换机器、换 provider 时都更好维护，而且不会把真实凭证散落到多个配置备份里。你可以在配置文件里保留 ${CLAWSOCKET_API_KEY} 这类占位符，让 OpenClaw 在运行时解析。

为什么 list 能看到模型，聊天里却切换失败

优先检查 agents.defaults.models。官方文档已经说明，这一段会变成 allowlist。也就是说，provider 配好了，只代表“OpenClaw 能认识这个模型”；allowlist 没放行，聊天层照样不会让它跑。

接完以后，还需要再跑 openclaw onboard 吗

如果你的基础配置已经生成，通常不需要反复重跑。onboard 更适合初始化；真正长期维护，还是回到 openclaw.json 和 openclaw models status 这条线更直接。

参考资料

• OpenClaw 官方文档：Model Providers
• OpenClaw 官方文档：Models CLI（中文）
• OpenClaw 官方文档：Models 概念（中文）
• OpenClaw 官方文档：Configuration Reference