> ## Content Index > Fetch the complete content index at: https://tbbbk.com/llms.txt > Use this file to discover other available public pages before exploring further. # OpenClaw gateway 命令与排错指南（2026）：status、restart、probe 怎么用 - URL: https://tbbbk.com/openclaw-gateway-commands-troubleshooting-guide-2026/ - Published: 2026-03-12T04:25:42.000Z - Updated: 2026-03-20T05:24:53.000Z - Description: OpenClaw 没回复、Dashboard 连不上、改完配置没生效，到底该先敲 `openclaw status`、`openclaw gateway status` 还是 `openclaw gateway restart`？这篇把最常用的 gateway 命令和排错顺序一次讲透。 - Author: TuBaiBai - Tags: OpenClaw, 折腾日记, #Import 2026-07-20 07:13 装 OpenClaw 的时候，很多人觉得最烦的是安装。真用久了你就会发现，安装反而只是开胃菜，后面那些“昨天还好好的，今天突然不回了”的时刻，才是真的折磨人。 我自己就踩过这种坑。面板昨天还能开，今天直接连不上；Telegram 明明已经接好了，突然开始装死；配置我也改了，重启我也重启了，结果它还是一副半死不活的样子。那种时候人很容易急，手会比脑子快，第一反应基本都是：**先 `restart` 一把再说。** 问题是，OpenClaw 很多时候不是“重启次数不够”，而是你第一步就查错地方了。尤其是这几个命令，名字长得太像：`openclaw status`、`openclaw gateway status`、`openclaw gateway restart`、`openclaw gateway`。真到出问题那一刻，脑子一乱，特别容易敲混。 所以这篇我不想写成那种四平八稳的命令手册。那种文章适合收藏，真救火时反而不一定顶用。我更想聊点实战里的东西：OpenClaw 没回复时我第一步查什么，`status` 和 `gateway status` 到底差在哪，什么时候该重启，什么时候不该瞎重启，以及 `openclaw gateway` 和 `openclaw gateway restart` 为什么压根不是一回事。 如果你之前看过我写的 [《OpenClaw 常用命令大全（2026）》](https://tbbbk.com/openclaw-cli-commands-guide)，那篇更像“大全”；这一篇我想写得更像“救火顺序表”。就盯着一个问题：**OpenClaw 出状况时，到底先敲哪条命令，才不至于把自己越修越乱。** ## 先记住一句最重要的话 如果你今天只想先记住一句，我希望是这句： > **OpenClaw 出问题时，先看 `status`，再看 `gateway status`，再看日志，别一上来就 `restart`。** 这话看着像废话，但真到自己机器抽风的时候，最容易忘掉的偏偏就是这种废话。 很多人不是不会排错，而是一上来顺序就乱了。顺序一乱，后面就很容易开始瞎猜，越猜越偏。 ## OpenClaw gateway 到底是什么？ 不用把它想得太复杂，你把它当成 OpenClaw 的中枢就行。 消息怎么进来、会话怎么跑、Dashboard 能不能打开、节点和自动化功能稳不稳定，很多东西都绕不过 gateway。官方文档说得也很直接：**Gateway 本质上就是 OpenClaw 的 WebSocket server**，channels、nodes、sessions、hooks 这些能力，背后都靠它串起来。 所以现实里只要你遇到这几种情况，第一反应都应该先看 gateway，而不是先怀疑人生： - 机器人突然不回复了 - Dashboard / Control UI 打不开 - 改完配置感觉没生效 - 节点、浏览器、自动化相关功能突然不正常 - 服务看着还活着，但就是哪里不对 也正因为它太核心了，很多人一出问题就想重装。我现在基本不会这么干。大多数时候，**先把 gateway 这层查明白，比瞎重装有用得多。** ## 我现在排 OpenClaw，基本都先走这三步 这部分我想放前面，因为它比后面那堆命令解释更有用。 我现在只要碰到 OpenClaw 抽风，基本都会先跑这三条： ```bash openclaw status openclaw gateway status openclaw logs --follow ``` 别嫌它土，这套顺序我自己已经用很多次了。真遇到问题时，能先把方向摆正，比背十条命令都管用。 ### 第一步：`openclaw status` ```bash openclaw status ``` 这条看的是**整体状态**，不是只看 gateway。 我这边实测下来，它会把这些内容直接给你： - Dashboard 地址 - OS / Node 版本 - Gateway 是否可达 - Gateway service 是否在 running - Sessions / Agents 情况 - Channels 状态 - Security audit 提示 - 更新提示 为什么第一步先跑它？很简单，因为很多时候你压根不知道问题到底出在哪一层。 比如“OpenClaw 今天怎么不回我了”，这句话背后可能是： - gateway 挂了 - channel 掉了 - session 卡住了 - service 没起来 - 配置有警告 - 甚至只是你查错了目标 这时候最亏的做法，就是先脑补一个原因，然后直接冲过去改配置、重启服务，甚至重装。`openclaw status` 的价值，不是一步到位解决问题，而是先把方向摆正。 所以如果你只想记一条“出事先敲什么”的命令，我会选它。 ### 第二步：`openclaw gateway status` ```bash openclaw gateway status ``` 第一步看完大盘，第二步就该盯住 gateway 本身了。 我这边实测输出里，最值得看的几行是： - `Service: systemd (enabled)` - `Gateway: bind=loopback (127.0.0.1), port=18789` - `Probe target: ws://127.0.0.1:18789` - `Dashboard: http://127.0.0.1:18789/` - `Runtime: running` - `RPC probe: ok` 这些行平时看着挺碎，真出问题的时候一个比一个值钱。 #### `Service` 说明你现在这个 gateway 是不是作为后台服务在跑。Linux 一般是 systemd，macOS 常见是 launchd。 #### `bind / port` 告诉你 gateway 实际绑在哪儿、跑在哪个端口。 比如我这里是 `loopback + 18789`，意思就是它只监听本机回环地址，本机外的机器不能直接连。 #### `Probe target` CLI 现在到底在探测哪个 WebSocket 地址。 这个地方特别容易被忽略，但经常能救命。因为有些问题根本不是 gateway 没起来，而是**你查错目标了**。你以为自己在看本地，结果 probe 探的是另一个地址，后面的判断自然全歪。 #### `Dashboard` Dashboard / Control UI 对应的地址。面板连不上时，先看这里是不是你以为的那个入口。 #### `Runtime` 进程现在是不是活着。 #### `RPC probe` 这是整条命令里我最看重的一个信号。 很多人会被“进程还在”这件事骗到。服务活着，不代表 gateway RPC 一定正常。`RPC probe: ok` 才说明它真的能连、能响应。 所以如果你怀疑 gateway 出问题，先看 `gateway status`，通常比闭眼 `restart` 更靠谱。 ### 第三步：`openclaw logs --follow` ```bash openclaw logs --follow ``` 这一步是很多人最懒得做、但其实最值钱的一步。 很多问题不是不会修，而是**根本没看日志**。 你可以一边开着： ```bash openclaw logs --follow ``` 一边自己再发一条测试消息，然后盯着输出看。通常很快就能看出到底是哪一层出问题： - 有没有消息真的进来 - 有没有 auth 错误 - 有没有 routing 问题 - 有没有 RPC 异常 - 有没有模型调用报错 - 有没有 channel 侧报 401 / 403 之类的问题 有时候你在那儿想半天，以为是配置写错了，结果日志里早就把答案写明白了。很多所谓“玄学问题”，本质上只是你没开日志。 ## 什么时候该用 `openclaw gateway restart` 现在再说重启，就顺了。 ```bash openclaw gateway restart ``` 这条命令当然常用，但也真的很容易被滥用。 它的作用其实很简单：**重启后台服务**。 如果你已经安装了 OpenClaw service，那么平时改完配置、插件、某些需要重新加载的设置，`restart` 就是很高频的一条命令。 我自己通常在这几种情况下用它： - 改了配置，需要重新加载 - 文档明确写了“改完要 restart” - 服务虽然还活着，但状态明显不对 - 我已经看过状态和日志，确认值得重启试一下 注意最后这条。重点不是“重启有用”，而是**先看过状态和日志，再决定要不要重启**。 很多人一出问题就先 restart，重启三遍还不行，最后才想起来看日志。这个顺序其实是反的。真想省时间，最该省掉的不是日志，而是那些没意义的重启。 ## 很多人最容易搞混的：`openclaw gateway restart` 和 `openclaw gateway` 这俩一定要单独讲，不然新手很容易混。 ### `openclaw gateway restart` ```bash openclaw gateway restart ``` 它操作的是**后台服务**。 如果你已经装了 service，这就是正常维护路径的一部分。敲完命令它就结束，不会占住你当前终端。 ### `openclaw gateway` ```bash openclaw gateway # 或者 openclaw gateway run ``` 这条不是去重启你现有的后台 service，而是**在你当前终端里前台运行一个 gateway 进程**。 这两个命令看起来只差一点字，实际适用场景完全不同： - `restart`：适合平时维护后台服务 - `gateway`：适合临时调试、看前台输出 如果你已经把 OpenClaw 装成长期运行的服务，平时真没必要老手动敲 `openclaw gateway`。这就像家里热水器明明一直开着，你每次洗澡前还非要重新生火，折腾半天，方向还容易跑偏。 ## 别硬背命令，记住它们各自该在什么时候出场 上面说的是排查顺序。下面这部分，我想换个更实用的角度：别把它当考试背诵，而是记住“什么场景下该叫谁上场”。 ## 1）`openclaw status` ```bash openclaw status ``` **适合场景：** - 你还不确定问题到底出在哪一层 - 机器人突然没回复 - 想先快速看一眼整体状态 **一句话理解：** 先看大盘，别急着猜。 ## 2）`openclaw gateway status` ```bash openclaw gateway status ``` **适合场景：** - 怀疑 gateway 服务本身有问题 - Dashboard 连不上 - 想确认 Runtime、Probe、Dashboard 地址到底对不对 **一句话理解：** 它不是看“OpenClaw 整体咋样”，而是看“gateway 自己现在到底活没活、通没通”。 ## 3）`openclaw gateway restart` ```bash openclaw gateway restart ``` **适合场景：** - 改完配置之后 - 确认服务状态确实有问题，准备重启试试 - 某些配置或插件官方明确要求 restart **一句话理解：** 它是维护命令，不是万能修复键。 ## 4）`openclaw gateway start` ```bash openclaw gateway start ``` **适合场景：** - 你之前把 service 停了 - 服务没启动，现在要把它拉起来 **一句话理解：** 需要开机，不需要解释。 ## 5）`openclaw gateway stop` ```bash openclaw gateway stop ``` **适合场景：** - 你想彻底停掉现有服务 - 怀疑端口冲突，准备重新拉起 - 想走一套干净的 stop → start **一句话理解：** 别乱 kill，能正常 stop 就正常 stop。 ## 6）`openclaw gateway probe` ```bash openclaw gateway probe ``` 这条很多人平时不常用，但它其实挺好用。 官方文档对它的定位很直接：**debug everything**。 它会去探测： - 本地 localhost / loopback gateway - 你配置过的 remote gateway（如果有） 所以如果你有多套 gateway、远程模式、Tailscale、SSH 转发，或者你怀疑“是不是我查错了目标”，这条命令通常比 `gateway status` 更适合做全链路确认。 **一句话理解：** 当你觉得问题已经不只是“服务起没起”那么简单时，就该让 `probe` 上场了。 ## 真实排错时，我一般怎么走 光知道命令名其实没多大用，关键是顺序别乱。 下面这几个场景，是我自己觉得最常见、也最容易把人带沟里的。 ## 场景一：OpenClaw 没回复 先跑： ```bash openclaw status openclaw gateway status openclaw logs --follow ``` 为什么这么排？ ### 先 `openclaw status` 先确认是不是全局层面已经有异常。 如果这里已经明显显示 Gateway、Channels、Sessions 某层不对，你马上就有方向了。 ### 再 `openclaw gateway status` 确认 gateway 服务到底活没活，`RPC probe` 到底通不通。 很多时候你会在这里直接看到： - `Runtime: stopped` - `RPC probe: failed` - bind / port 跟你预期不一致 - Dashboard 地址不对 ### 最后 `openclaw logs --follow` 这一步就是抓现行。 你再手动发一条测试消息，同时看日志，通常马上就能知道： - 消息到底有没有进来 - 是不是 auth 问题 - 是不是路由问题 - 是不是模型调用挂了 如果这三步走完你还完全没头绪，那再往 `doctor` 和 channel 配置那边看也不迟。 ## 场景二：怀疑 gateway 本身挂了 可以按这个顺序： ```bash openclaw gateway status openclaw gateway restart openclaw gateway status ``` 重点就一句：**先看，再重启，再确认。** 别一上来就先按重启键。 如果第一次 `gateway status` 就已经显示 `Runtime: running` 且 `RPC probe: ok`，那你大概率不该继续把时间浪费在 gateway 本身，而应该去看 channel、配对策略、日志、认证或配置。 相反，如果它本来就不对，再 `restart` 就很合理。重启后再跑一次 `gateway status`，确认它到底有没有恢复，而不是靠感觉猜。 ## 场景三：改完配置没生效 很多时候不是你改错了，而是**这类配置本来就要 restart 才生效**。 先直接： ```bash openclaw gateway restart ``` 如果 restart 之后还是不对，再接着看： ```bash openclaw gateway status openclaw logs --follow openclaw doctor ``` 别把“配置没生效”和“配置一定写错了”直接画等号。很多时候只是你没 reload 到位，先确认这一层，再谈是不是写错。 ## 场景四：想查得更全一点 ```bash openclaw gateway probe ``` 如果你在本地、远程、SSH 转发、Tailscale 这些模式之间切来切去，或者你怀疑自己连错 gateway 了，这条命令会很有价值。 它的思路不是“只看这一个服务”，而是把可疑目标一起探一遍。所以当 `gateway status` 已经不够解释现象的时候，`probe` 往往比继续瞎猜更省事。 ## 几个很常见的异常，可以这样理解 ## 1）`Runtime: stopped` 这说明服务没起来，或者起来之后又掉了。 优先去看： ```bash openclaw gateway status openclaw logs --follow openclaw doctor ``` 这种时候先别想着重装。很多情况只是 service、配置或者启动条件有问题，不一定是系统已经烂了。 ## 2）`RPC probe: failed` 这个很关键。 它通常意味着：**服务层面看起来像在跑，但 Gateway RPC 没正常工作。** 这时候我会优先怀疑： - URL / 端口不对 - token / password 没对上 - bind 模式有问题 - gateway 虽然活着，但没有正常响应 RPC 这个状态下，单看“进程存在”没太大意义。你要的不是“它还在”，而是“它能正常工作”。 ## 3）`Gateway start blocked: set gateway.mode=local` 这个报错官方文档里直接写出来了。 意思就是你本地 gateway mode 没设成 `local`，所以它不给你启动。 这种情况别硬怼命令，先回去看配置。配置条件不满足，你多敲几次 `start` 也不会突然变好。 ## 4）`refusing to bind gateway ... without auth` 这通常出现在你想把 gateway 绑定到非 loopback 地址，但又没配好 token 或 password。 说白了，官方就是不想让你裸奔把接口暴露出去。这个限制其实挺合理，别嫌它烦。 ## 5）`another gateway instance is already listening` / `EADDRINUSE` 经典端口冲突。 通常说明： - 已经有一个 gateway 在跑 - 或者别的进程占了同一个端口 这种时候别边骂边继续开新实例，先把现有状态查清楚。很多人不是不会处理端口冲突，而是处理方式太着急。 ## Dashboard 连不上时，我一般怎么查 如果你遇到的是 Dashboard / Control UI 打不开、连不上，或者一直 unauthorized，我一般会跑这几条： ```bash openclaw gateway status openclaw status openclaw logs --follow openclaw doctor ``` 重点看四件事。 ### 1）Dashboard 地址是不是你以为的那个 `openclaw gateway status` 里会直接给你 `Dashboard: http://...`。 很多人其实不是面板坏了，而是连错了地址。尤其是本地、远程、Tailscale、SSH 转发混着用的时候，这个问题特别常见。 ### 2）Probe target 对不对 你得确认 CLI 现在探测的，是不是你想查的那个 gateway。 ### 3）auth 有没有对上 如果日志里冒出 `unauthorized`、`gateway connect failed` 这种字眼，那就优先怀疑 token / password 或连接目标不一致。 ### 4）是不是 gateway 活着，但 UI 没走对认证流程 这类问题光看浏览器页面通常很难猜，还是得回到 `gateway status` 和日志。 ## 一份够用的 OpenClaw gateway 速查表 如果你懒得看长文，至少把下面这份记下来： ```bash # 看整体状态 openclaw status # 看 gateway 服务状态 openclaw gateway status # 启动后台服务 openclaw gateway start # 停止后台服务 openclaw gateway stop # 重启后台服务 openclaw gateway restart # 做更完整的 gateway 探测 openclaw gateway probe # 前台运行 gateway（适合调试） openclaw gateway # 实时看日志 openclaw logs --follow ``` ## 最后说几句我自己踩坑后的结论 我现在排 OpenClaw 问题，已经很少一上来就想着重装了。不是因为我突然变多厉害了，而是坑踩多之后发现，很多问题真没复杂到那个份上。 大多数时候，其实都跑不出这条线： 1. `openclaw status` 2. `openclaw gateway status` 3. `openclaw logs --follow` 这三步走完，八成问题就已经有方向了。后面到底要不要 `restart`，要不要 `doctor`，要不要继续去查 channel 配置，心里会清楚很多。 所以如果你以前也老被这些命令名绕晕，我的建议其实很简单：**别想着一次把 OpenClaw 所有命令全背下来，先把 gateway 这一层吃透。** 真正常用、真能救火的，往往也就是这几条。 如果你想把 OpenClaw 的日常操作命令也一起补全，可以接着看我之前那篇 [《OpenClaw 常用命令大全（2026）》](https://tbbbk.com/openclaw-cli-commands-guide)；如果你还在折腾国内网络、模型和基础环境，那篇 [《OpenClaw 国内使用完整指南》](https://tbbbk.com/openclaw-china-mainland-setup-guide) 也值得顺手翻一下。三篇连起来，安装、使用、排错这条线基本就串起来了。