OpenClaw 安装与 API 配置实战：gateway service missing 怎么处理

如果你不想给 OpenClaw、Codex、Claude Code 分别维护不同入口，可以直接使用 api.clawsocket.com。一套 Key 配一个统一 baseUrl，后面切模型、换工具都会省很多事。

很多人第一次接触 OpenClaw，真正卡住的往往不是“它是什么”，而是下面这几步：

OpenClaw 到底怎么安装
openclaw onboard 里每一步应该怎么选
第三方 API 到底写环境变量，还是改 openclaw.json
Web UI 能打开，但提示 gateway service missing 该怎么办

如果你正在搜这些问题，这篇文章就按一条最实用的路线来写：先把 OpenClaw 装上，再把初始化跑通，接着把 API 配好，最后把 gateway service missing 这类常见报错单独拆开处理。

OpenClaw 安装与 API 配置示意图 — 对大多数人来说，OpenClaw 真正难的不是安装命令本身，而是安装、Gateway、配置文件和模型入口之间的关系没有理顺。

快速结论

OpenClaw 先装 CLI，再跑 openclaw onboard，排错会简单很多
如果你只是想先把本机跑起来，初始化时可以先最小化选择，模型入口放到后面统一配置
OpenClaw 的长期配置核心文件通常是 ~/.openclaw/openclaw.json
如果你准备接第三方入口，最稳的方式通常是把 Key 放环境变量，再在配置里引用
遇到 gateway service missing，优先检查的不是模型，而是 Gateway 进程、端口、token 和当前配置文件是否一致

一、OpenClaw 是什么，为什么它和普通聊天工具不一样

OpenClaw 可以理解成一个本地运行的 AI Gateway 和 Agent 控制台。它不是只负责给你回一段文字，而是把模型、会话、工作区、技能和外部渠道放到同一套网关里管理。你可以把它想成一个“能实际接入文件、命令和工作流”的本地助手框架。

这也是为什么很多人刚开始会觉得它和普通聊天产品不太一样。普通聊天工具的重点是对话界面，OpenClaw 的重点则是“网关有没有起来、默认模型是不是可用、当前工作区和技能有没有配好”。如果这几层关系没理清楚，哪怕页面已经打开，后面也很容易出现 Gateway 不在线、模型不返回、会话不认配置这类问题。

从落地角度看，OpenClaw 更适合下面几类人：

想在本地或服务器上跑一个长期可用的 AI 助手
想把 GPT、Claude、Gemini 等模型放到同一套入口里管理
想做自动化、频道机器人、轻量 Agent 流程
想把终端工具和 Web 控制台串起来，而不是只停留在单次问答

二、安装前先把思路理顺

在开始安装之前，先把一件事讲清楚。很多“OpenClaw 安装失败”或者“gateway service missing”的问题，本质上不一定是安装命令错了，而是你把下面这四层混在一起了：

层级	作用	你需要确认什么
CLI	本机命令行工具	`openclaw --version` 能不能正常输出
Gateway	Web UI 和会话服务	本地端口有没有真正启动
配置文件	provider、model、workspace	当前实际读取的是哪份配置
上游 API	模型返回内容的来源	Key、`baseUrl`、协议是否配对

排错的时候，最好按这个顺序往下看。因为很多人一看到页面报错，就立刻去怀疑模型 API，其实问题更早，可能只是 Gateway 进程没启动，或者你改了配置文件但当前实例根本没读到。

三、OpenClaw 怎么安装

这部分不讲花哨路线，只讲最容易把 CLI 装起来的方式。

1. macOS / Linux

如果你用的是 macOS、Linux 或 Windows 下的 WSL，最省事的方式通常是脚本安装：

bash

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

安装完成后，先不要急着配置模型，先确认 CLI 是否已经可用：

bash

openclaw --version
openclaw --help

这两步都能正常返回，说明“安装层”基本是通的。接下来遇到的问题，就不该再按“没装上”去理解。

2. Windows

如果你在 Windows 上做长期使用，我更建议把思路放在稳定环境上，而不是只追求“命令能跑一次”。最常见的两条路线是：

直接在 PowerShell 安装并测试
通过 WSL2 进入 Linux 环境后再装 OpenClaw

如果你平时本来就做开发，后者往往更稳，因为后面很多依赖、脚本和终端行为都会更接近 Linux 环境。无论你走哪条路，装完以后都先看这两条命令：

bash

openclaw --version
openclaw --help

如果 CLI 都还没起来，就先别继续往下折腾 Gateway 和 API。

四、初始化为什么一定要跑 `openclaw onboard`

很多人装完以后马上去找 openclaw.json，这不是不行，但如果你还没跑过初始化，后面很多目录、token、默认工作区和 Gateway 参数其实都还没完全准备好。

更稳的做法是先执行：

bash

openclaw onboard

这一步通常会帮你做几件事：

生成或确认默认配置目录
准备工作区
设置本地 Gateway 地址和端口
引导你挑选上游模型或先跳过
生成 dashboard 访问链接和 token

如果你只是想先把 OpenClaw 跑起来，我建议用“先最小化初始化，再单独改模型入口”的思路。也就是：

工作区先用默认值
网关地址和端口先用默认值
渠道接入先不急着配
模型供应商如果拿不准，可以先跳过或先选最简单的一项

这样做的好处是，后面一旦报错，你更容易分辨问题是在 Gateway、配置文件，还是上游 API，而不是所有变量同时改动。

初始化完成后你要记住什么

openclaw onboard 跑完以后，通常有三样东西最值得立刻记下来：

当前 dashboard 地址
带 token 的访问链接
当前实际使用的配置目录

很多后续的 gateway service missing，其实是用户自己重新打开了一个不带 token 的地址，或者换了终端以后起了另一份实例，结果以为是同一个 Gateway 在报错。

OpenClaw dashboard ready 提示图 — 初始化结束后，不要只看页面弹出来了没有，更重要的是记住当前 Gateway 地址、token 和配置目录。

五、OpenClaw 的 API 配置应该怎么做

这一段是很多人真正卡住的地方。你可以把 OpenClaw 的模型接入分成两种思路：

只想让一个模型先跑起来
想把多个模型入口统一管理，后面继续切换

如果你属于第二种，最省事的路线通常是用统一入口。也就是先在 api.clawsocket.com 生成一把自己的 Key，然后把 OpenClaw 的默认 provider 指过去。这样做的好处是，今天你先用 GPT，明天想切 Claude 或 Gemini，不需要重新换一套完全不同的配置逻辑。

1. 先准备 API Key

你可以先把 Key 放到环境变量里：

bash

export CLAWSOCKET_API_KEY="你的 API Key"

如果你想长期生效，可以写进 ~/.zshrc：

bash

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

如果你用的是 PowerShell，可以先做当前会话验证，再决定是否写入持久配置。

把 Key 放环境变量的好处有两个。第一，不用把密钥散落在多个文件里；第二，后面如果你还要给 Codex、Claude Code 之类的工具接同一套入口，凭证管理会更统一。

2. 找到真正生效的配置文件

OpenClaw 这类工具最常见的问题之一，不是字段写错，而是改错文件。通常默认配置文件会在：

text

~/.openclaw/openclaw.json

如果你不确定当前到底读的是哪份，可以先用 OpenClaw 自己的命令确认，再动手改。这个动作比直接去用户目录里盲改更稳，因为它能避免你同时维护多份旧配置。

3. 一个更适合长期使用的 provider 示例

下面是一份比较适合统一入口思路的例子：

json5

{
  "agents": {
    "defaults": {
      "model": {
        "primary": "clawsocket/gpt-5.4",
        "fallbacks": ["clawsocket/claude-sonnet-4-6"]
      },
      "models": {
        "clawsocket/gpt-5.4": {},
        "clawsocket/claude-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" }
        ]
      }
    }
  }
}

这份配置最值得你看懂的是四个点：

baseUrl 决定请求往哪里发
apiKey 最好引用环境变量，不要长期明文散落
api 决定 OpenClaw 用哪套兼容协议去请求
primary 和 fallbacks 决定你平时默认先走哪个模型

如果你只看表面，很容易觉得这只是“贴一段 JSON”。但从长期维护角度看，这段配置真正解决的是一件更现实的事：以后你要继续换模型、扩模型、换工具时，不需要重新发明接入方式。

六、`gateway service missing` 到底是什么意思

这是参考文里提到的典型问题，也是很多用户真正会搜的报错。

你可以把 gateway service missing 理解成一句更直白的话：当前页面、会话或命令预期能找到一个可用的 Gateway 服务，但它现在没找到，或者找到了一个状态不完整的 Gateway。它通常不是单纯的“API Key 错了”，而更像下面几类问题里的某一种：

Gateway 进程根本没启动
启动了，但监听地址或端口和当前页面不是同一个
你打开的是不带 token 的地址
openclaw onboard 生成的是一份配置，而你后来又手动起了另一份实例
配置文件改过，但 Gateway 没有重启，旧进程仍在读旧配置

这也是为什么我前面一直强调，排查顺序应该是 CLI、Gateway、配置文件、上游 API，而不是一看到这句报错就去改模型名。

七、遇到 `gateway service missing` 时，按这个顺序排查

1. 先确认 Gateway 有没有真正起来

很多人只看到浏览器页面能打开，就以为 Gateway 已经正常。其实浏览器能打开一个地址，不代表后面的服务状态完整。更稳的做法是回到终端，重新执行和 Gateway 相关的启动或状态检查命令，确认当前会话里真的有一个运行中的 OpenClaw 实例。

如果你刚跑完 openclaw onboard，最简单的思路反而不是继续猜，而是先重新打开一轮 dashboard，让 CLI 自己把当前地址和 token 打出来。这样你能立刻确认自己打开的是不是同一份实例。

2. 再确认你访问的是不是正确地址

如果你手动复制过地址，或者收藏过旧链接，很容易出现这种情况：浏览器里打开的是上一次的本地地址，但这次启动的 Gateway 端口已经变化，或者 token 已经不是之前那份。

这时要做的不是重装 OpenClaw，而是直接以当前终端输出为准。不要相信浏览器历史记录，也不要默认 127.0.0.1:18789 一定还是同一个实例。

3. 检查配置文件是不是当前实例正在读取的那份

OpenClaw 的配置一旦开始手动修改，最怕的就是你改的是 ~/.openclaw/openclaw.json，但现在实际运行的却是另一个工作区下的历史配置，或者某个旧实例还没退出。这样页面表现出来就会像是 Gateway 状态不对，实际上是配置上下文已经分叉了。

如果你最近刚改过 provider、端口、模型列表，最稳的动作就是改完以后重新拉起 Gateway，不要指望旧进程自动理解你新写进去的字段。

4. 最后才看上游 API 和模型配置

只有前面三层都确认没问题了，再去看上游 API 是否可用。因为如果 Gateway 本身没起来，或者页面连的是旧实例，你此时再反复改 baseUrl、apiKey、模型名，只会把变量越改越乱。

这一点特别重要。很多用户在 gateway service missing 的状态下顺手把 provider 也改了，结果等 Gateway 真修好以后，又开始遇到第二轮模型问题，最后自己也分不清到底是哪一步坏了。

八、OpenClaw 常见问题

1. 为什么 Web UI 能打开，但就是不出字

先别急着怀疑模型。更常见的情况是 Gateway 在线，但 provider 没配好，或者当前默认模型不在允许列表里。对 OpenClaw 来说，“页面打开”和“上游能返回”是两层不同的问题。

2. API Key 应该直接写进 `openclaw.json` 吗

能写，但不建议长期这么做。更稳的方式通常是写进环境变量，再在配置文件里引用。这样后面换 Key、换机器、给别的工具复用入口时都会更方便。

3. 为什么我明明改了 `openclaw.json`，页面还是老样子

优先怀疑两件事。第一，你改的不是当前实例真正读取的那份配置；第二，Gateway 还没重启，旧进程仍然拿着旧配置在跑。这两种情况在 OpenClaw 里都很常见。

4. 什么时候适合直接用统一入口

如果你只是临时测试一个单独模型，当然可以先走最短路径；但如果你已经知道自己后面还要继续切 GPT、Claude、Gemini，或者你手里本来就在同时用多个 Agent 工具，那一开始就把入口统一到 api.clawsocket.com 这类方案里，维护成本会低很多。

九、一条更稳的使用顺序

如果你不想在安装和排错阶段来回折腾，建议按这条顺序来：

先把 CLI 装好，确认 openclaw --version 正常
跑一次 openclaw onboard，把 Gateway 和 dashboard 起起来
记住当前 dashboard 地址、token 和配置目录
再去接 API Key 和 provider，不要把所有变化堆到第一次初始化里
如果页面报 gateway service missing，先回头看 Gateway，再看配置文件，最后才看上游 API

这条顺序看起来比“直接把所有参数一次填完”慢一点，但实际更省时间。因为它把问题拆开了。你每走一步，都能明确知道当前验证的是哪一层。

总结

如果把这篇文章压缩成一句话，真正有用的 OpenClaw 实操思路其实很简单：先把 CLI 装好，再跑 openclaw onboard，然后把模型入口单独配置，最后把 gateway service missing 当成 Gateway 层问题去排，而不是一上来就反复改模型。

对长期使用来说，更稳的做法通常是把 API 凭证收口到环境变量，再通过 api.clawsocket.com 这种统一入口接进 OpenClaw。这样你今天解决的是 OpenClaw，明天继续接 Codex、Claude Code、Gemini，也不用把整套配置思路重做一遍。

参考资料

参考文章：OpenClaw安装、配置API、常见问题最全详细教程

OpenClaw 安装与 API 配置实战：gateway service missing 怎么处理 ​

快速结论 ​

一、OpenClaw 是什么，为什么它和普通聊天工具不一样 ​

二、安装前先把思路理顺 ​

三、OpenClaw 怎么安装 ​

1. macOS / Linux ​

2. Windows ​

四、初始化为什么一定要跑 openclaw onboard ​

初始化完成后你要记住什么 ​

五、OpenClaw 的 API 配置应该怎么做 ​

1. 先准备 API Key ​

2. 找到真正生效的配置文件 ​

3. 一个更适合长期使用的 provider 示例 ​

六、gateway service missing 到底是什么意思 ​

七、遇到 gateway service missing 时，按这个顺序排查 ​

1. 先确认 Gateway 有没有真正起来 ​

2. 再确认你访问的是不是正确地址 ​

3. 检查配置文件是不是当前实例正在读取的那份 ​

4. 最后才看上游 API 和模型配置 ​

八、OpenClaw 常见问题 ​

1. 为什么 Web UI 能打开，但就是不出字 ​

2. API Key 应该直接写进 openclaw.json 吗 ​

3. 为什么我明明改了 openclaw.json，页面还是老样子 ​

4. 什么时候适合直接用统一入口 ​

九、一条更稳的使用顺序 ​

总结 ​

参考资料 ​

OpenClaw 安装与 API 配置实战：gateway service missing 怎么处理

快速结论

一、OpenClaw 是什么，为什么它和普通聊天工具不一样

二、安装前先把思路理顺

三、OpenClaw 怎么安装

1. macOS / Linux

2. Windows

四、初始化为什么一定要跑 `openclaw onboard`

初始化完成后你要记住什么

五、OpenClaw 的 API 配置应该怎么做

1. 先准备 API Key

2. 找到真正生效的配置文件

3. 一个更适合长期使用的 provider 示例

六、`gateway service missing` 到底是什么意思

七、遇到 `gateway service missing` 时，按这个顺序排查

1. 先确认 Gateway 有没有真正起来

2. 再确认你访问的是不是正确地址

3. 检查配置文件是不是当前实例正在读取的那份

4. 最后才看上游 API 和模型配置

八、OpenClaw 常见问题

1. 为什么 Web UI 能打开，但就是不出字

2. API Key 应该直接写进 `openclaw.json` 吗

3. 为什么我明明改了 `openclaw.json`，页面还是老样子

4. 什么时候适合直接用统一入口

九、一条更稳的使用顺序

总结

参考资料