尧图网站建设 
1. openclaw gateway 网关到底在链路里干什么openclaw gateway 网关是一个长期驻留的本地进程它把底层协议连接Baileys、Telegram 等和上层客户端调用隔离开。你可以把它理解成小区门口的传达室外面来的快递客户端请求先到传达室登记传达室再按门牌号路由规则把包裹送到具体住户渠道适配层住户处理完把回执交回传达室最后原路返回给快递员。没有这个中间层每个客户端都得自己记住所有住户的门牌号和作息时间一旦某个渠道重连或掉线调用方就得跟着改代码。它对外暴露两类接口跑在同一个端口上。一类是控制与事件 WebSocket默认监听 127.0.0.1:18789负责连接握手、事件推送和 RPC 调用另一类是 HTTP 服务复用同一端口提供 /v1/chat/completions、/v1/responses、/tools/invoke 这几个路径。也就是说你既可以用 WebSocket 长连接订阅事件也可以用普通 HTTP 请求发一条消息网关内部会把两种入口统一收敛到同一套路由逻辑上。适合谁用如果你已经在本地把 openclaw 跑起来了能收到消息、能触发回复但说不清楚请求从哪进、从哪出或者遇到「消息发出去了但没回应」「日志里看不到路由命中」这类问题那这篇就是给你写的。我试过在排查一个渠道静默失败的问题时把网关日志级别调到 verbose才看清请求其实卡在路由匹配阶段根本没进到渠道适配层。理解网关的位置能让你在出问题时快速判断是入口、路由还是出口的锅。网关自身启动后会持续运行遇到致命错误以非零退出码退出方便 supervisor 捕获并重启。这个设计意味着它不追求「永不崩溃」而是追求「崩溃后能被快速拉起」所以生产环境一定要配守护进程后面会讲。2. 启动 openclaw gateway 前的配置与端口准备在敲启动命令之前先把配置文件理清楚。网关默认读取 ~/.openclaw/openclaw.json你也可以用环境变量 OPENCLAW_CONFIG_PATH 指向自定义路径。这个文件里跟网关运行最相关的几块是端口、热重载模式和认证。热重载由 gateway.reload.mode 控制有三个取值。hybrid 是默认值它会尝试热应用安全配置遇到重大配置变更时触发重启off 则完全禁止热重载所有改动都得手动重启服务。我建议本地开发用 hybrid改完配置不用反复重启但如果你的配置里有端口、认证这类敏感项改完还是手动重启一次更稳妥避免热重载过程中出现短暂的认证空窗。端口方面默认 18789 同时承载 WebSocket 和 HTTP。Canvas 静态文件服务默认在 18793如果你不需要它可以用 canvasHost.enabledfalse 或设置环境变量 OPENCLAW_SKIP_CANVAS_HOST1 禁用少占一个端口。认证是默认开启的你必须配置 gateway.auth.token 或 gateway.auth.password 中的一种。客户端连接时要发送匹配的 connect.params.auth.token 或 connect.params.auth.password否则握手会被拒。这一步经常被忽略导致「服务起来了但客户端连不上」。下面是一份可复制的最小配置片段路径就是 ~/.openclaw/openclaw.json{ gateway: { port: 18789, reload: { mode: hybrid }, auth: { token: local-dev-token-please-change } }, canvasHost: { enabled: false } }如果你想把配置放到别处启动前设置export OPENCLAW_CONFIG_PATH/your/path/openclaw.json注意 token 别用示例里的默认值本地也建议换一个随机串。配置写好后先别急着启动用openclaw gateway status看一眼当前有没有残留进程占着 18789有的话后面启动会报端口冲突。3. 可复制的 gateway 启动命令与参数说明启动命令本身不复杂关键是理解每个参数在什么场景下用。基础启动openclaw gateway --port 18789这条命令会以前台方式拉起网关日志直接打到终端。适合第一次跑通时观察启动过程。如果你要排查问题加上 --verboseopenclaw gateway --port 18789 --verbose--verbose 会输出 debug/trace 级别日志路由匹配、连接握手、事件分发这些细节都能看到。排查「请求没转发出去」时这个参数基本是必开的。如果端口被占用又不想手动去找进程可以用 --forceopenclaw gateway --port 18789 --force--force 会终止可能已占用该端口的进程然后重新启动。这个参数在本地反复调试时很省事但别在共享环境里随便用它可能误杀别人的进程。生产环境建议交给 supervisor 管理比如 systemd。网关正常停止/重启接收 SIGTERM错误退出码为非 0supervisor 捕获后自动拉起。一个简化的 systemd unit 片段[Service] ExecStart/usr/local/bin/openclaw gateway --port 18789 Restarton-failure RestartSec3 EnvironmentOPENCLAW_CONFIG_PATH/etc/openclaw/openclaw.jsonRestarton-failure 配合非零退出码就能实现崩溃自愈。日志轮转交给 journald 或 logrotate避免日志无限增长。启动后你会看到类似 Runtime: running 的输出。如果卡在启动阶段先看终端最后几行通常是配置解析失败或端口冲突。配置解析失败会明确告诉你哪个字段有问题端口冲突则提示 address already in use这时用 --force 或换端口。4. 一次完整的请求转发验证与日志确认光启动成功不算完得实际发一条请求看它有没有走完「入口 → 路由 → 渠道 → 返回」整条链路。先确认网关状态openclaw gateway status正常输出里会有 Runtime: running 和 Connectivity probe: ok。如果 probe 不是 ok说明网关自身起来了但底层连接有问题先解决这个再发请求。接着用 HTTP 接口发一条 chat completions 请求。假设你的 token 是 local-dev-token-please-changecurl -s http://127.0.0.1:18789/v1/chat/completions \ -H Content-Type: application/json \ -H Authorization: Bearer local-dev-token-please-change \ -d { model: default, messages: [ {role: user, content: ping} ] }如果返回里带了 choices 字段和内容说明请求成功走完了整条链路。如果返回 401是认证没对上如果返回 404 或路由相关错误是路径或模型名没匹配上。想确认路由到底命中了哪条规则开另一个终端跟日志openclaw logs --follow然后在日志里找这次请求的 trace。你会看到请求进入网关、匹配到某条路由、转发给对应渠道、渠道返回、网关回写响应这一串记录。路由命中那行通常会带上匹配的规则名或渠道标识这就是你要的「路由命中确认」。渠道就绪情况可以单独查openclaw channels status --probe如果某个渠道显示未就绪那即使路由命中了请求也会在转发到渠道这一步失败。所以完整的验证顺序是网关 status 正常 → channels status 就绪 → 发请求 → 日志确认路由命中 → 收到响应。5. 常见报错排查401、local proxy failed 与路由不命中排障时先分清错误发生在哪一层。下面几个是我实际遇到过的典型情况。401 Unauthorized。这是认证层的问题跟路由和渠道无关。检查三处配置文件里 gateway.auth.token 或 gateway.auth.password 是否设置客户端发送的 connect.params.auth.token 或 Authorization 头是否与配置一致如果用了环境变量覆盖配置路径确认加载的是你改的那份文件。常见坑是改了配置但没重启hybrid 模式下认证类变更可能没热应用手动重启一次即可。local proxy failed。这个报错通常出现在网关尝试把请求转发给底层渠道时本地连接建立失败。先看 channels status --probe确认目标渠道是否就绪再看网关日志里转发那一步的具体错误常见原因是渠道进程没起来、端口不对或渠道配置里的地址写错。如果渠道本身依赖外部网络确认本地网络能通但不要用任何非正规的网络工具走正常网络配置即可。reading choices 相关报错。这类错误一般发生在解析响应阶段说明请求已经转发出去、渠道也返回了但返回体结构不符合预期。检查渠道返回的原始内容看是不是空响应或错误结构。有时是模型名没匹配上渠道返回了错误对象而不是正常的 choices 数组。对照日志里渠道返回的原始 payload就能定位是渠道侧的问题还是网关解析的问题。路由不命中。表现是请求发出去了日志里没有路由命中记录或者命中了默认规则但没到目标渠道。检查请求里的 model 字段和路径是否与配置中的路由规则匹配。路由规则通常按 model 或路径前缀匹配写错一个字符就会落到默认分支。开 --verbose 后日志会打印实际参与匹配的规则列表对照着改。OAuth 相关报错。如果渠道用了 OAuth 认证报错往往跟 token 过期或回调地址不匹配有关。检查渠道配置里的 OAuth 凭据和回调地址确认与你在渠道侧登记的一致。token 过期的话重新走一次授权流程。排查时记住一个原则先看错误发生在哪一层再看那一层的配置。401 看认证local proxy failed 看渠道连接reading choices 看响应解析路由不命中看匹配规则。分层定位比盲目改配置快得多。6. 把网关接进你的调用链从本地验证到稳定运行本地跑通之后下一步是让它稳定地待在调用链里。如果你用的是 Claude Code 这类编码工具或者 Cline、Codex 这类客户端接入时要把三件套配全Base URL、Key、Model ID。Base URL 指向网关的 HTTP 入口比如 http://127.0.0.1:18789/v1Key 用你在 gateway.auth.token 里配的值Model ID 填你路由规则里定义的模型名。三者缺一要么连不上要么路由不命中。如果你需要长期跑编码或 Agent 任务可以考虑用 Coding Plan 来管理调用配额和模型切换把网关作为统一入口客户端只管发请求路由和渠道切换交给网关处理。这样换模型或加渠道时客户端配置不用动。验证模型是否正常工作可以直接用模型对话页面发一条测试消息确认返回正常后再接进正式流程。接入文档里有各客户端的详细配置示例照着填 Base URL、Key、Model ID 即可。API Key 在控制台的 API Keys 页面管理建议按用途分多个 Key方便排查和回收。最后说个实用技巧网关日志是你最好的朋友。把 openclaw logs --follow 常开在一个终端里发请求时盯着日志看路由命中那行比任何猜测都快。稳定运行的关键不是配置多复杂而是每次改动后都用一次完整请求验证链路确认入口、路由、渠道、返回四段都通。 openclaw gateway网关运行详解：从启动到请求转发的完整链路
1. openclaw gateway 网关到底在链路里干什么openclaw gateway 网关是一个长期驻留的本地进程它把底层协议连接Baileys、Telegram 等和上层客户端调用隔离开。你可以把它理解成小区门口的传达室外面来的快递客户端请求先到传达室登记传达室再按门牌号路由规则把包裹送到具体住户渠道适配层住户处理完把回执交回传达室最后原路返回给快递员。没有这个中间层每个客户端都得自己记住所有住户的门牌号和作息时间一旦某个渠道重连或掉线调用方就得跟着改代码。它对外暴露两类接口跑在同一个端口上。一类是控制与事件 WebSocket默认监听 127.0.0.1:18789负责连接握手、事件推送和 RPC 调用另一类是 HTTP 服务复用同一端口提供 /v1/chat/completions、/v1/responses、/tools/invoke 这几个路径。也就是说你既可以用 WebSocket 长连接订阅事件也可以用普通 HTTP 请求发一条消息网关内部会把两种入口统一收敛到同一套路由逻辑上。适合谁用如果你已经在本地把 openclaw 跑起来了能收到消息、能触发回复但说不清楚请求从哪进、从哪出或者遇到「消息发出去了但没回应」「日志里看不到路由命中」这类问题那这篇就是给你写的。我试过在排查一个渠道静默失败的问题时把网关日志级别调到 verbose才看清请求其实卡在路由匹配阶段根本没进到渠道适配层。理解网关的位置能让你在出问题时快速判断是入口、路由还是出口的锅。网关自身启动后会持续运行遇到致命错误以非零退出码退出方便 supervisor 捕获并重启。这个设计意味着它不追求「永不崩溃」而是追求「崩溃后能被快速拉起」所以生产环境一定要配守护进程后面会讲。2. 启动 openclaw gateway 前的配置与端口准备在敲启动命令之前先把配置文件理清楚。网关默认读取 ~/.openclaw/openclaw.json你也可以用环境变量 OPENCLAW_CONFIG_PATH 指向自定义路径。这个文件里跟网关运行最相关的几块是端口、热重载模式和认证。热重载由 gateway.reload.mode 控制有三个取值。hybrid 是默认值它会尝试热应用安全配置遇到重大配置变更时触发重启off 则完全禁止热重载所有改动都得手动重启服务。我建议本地开发用 hybrid改完配置不用反复重启但如果你的配置里有端口、认证这类敏感项改完还是手动重启一次更稳妥避免热重载过程中出现短暂的认证空窗。端口方面默认 18789 同时承载 WebSocket 和 HTTP。Canvas 静态文件服务默认在 18793如果你不需要它可以用 canvasHost.enabledfalse 或设置环境变量 OPENCLAW_SKIP_CANVAS_HOST1 禁用少占一个端口。认证是默认开启的你必须配置 gateway.auth.token 或 gateway.auth.password 中的一种。客户端连接时要发送匹配的 connect.params.auth.token 或 connect.params.auth.password否则握手会被拒。这一步经常被忽略导致「服务起来了但客户端连不上」。下面是一份可复制的最小配置片段路径就是 ~/.openclaw/openclaw.json{ gateway: { port: 18789, reload: { mode: hybrid }, auth: { token: local-dev-token-please-change } }, canvasHost: { enabled: false } }如果你想把配置放到别处启动前设置export OPENCLAW_CONFIG_PATH/your/path/openclaw.json注意 token 别用示例里的默认值本地也建议换一个随机串。配置写好后先别急着启动用openclaw gateway status看一眼当前有没有残留进程占着 18789有的话后面启动会报端口冲突。3. 可复制的 gateway 启动命令与参数说明启动命令本身不复杂关键是理解每个参数在什么场景下用。基础启动openclaw gateway --port 18789这条命令会以前台方式拉起网关日志直接打到终端。适合第一次跑通时观察启动过程。如果你要排查问题加上 --verboseopenclaw gateway --port 18789 --verbose--verbose 会输出 debug/trace 级别日志路由匹配、连接握手、事件分发这些细节都能看到。排查「请求没转发出去」时这个参数基本是必开的。如果端口被占用又不想手动去找进程可以用 --forceopenclaw gateway --port 18789 --force--force 会终止可能已占用该端口的进程然后重新启动。这个参数在本地反复调试时很省事但别在共享环境里随便用它可能误杀别人的进程。生产环境建议交给 supervisor 管理比如 systemd。网关正常停止/重启接收 SIGTERM错误退出码为非 0supervisor 捕获后自动拉起。一个简化的 systemd unit 片段[Service] ExecStart/usr/local/bin/openclaw gateway --port 18789 Restarton-failure RestartSec3 EnvironmentOPENCLAW_CONFIG_PATH/etc/openclaw/openclaw.jsonRestarton-failure 配合非零退出码就能实现崩溃自愈。日志轮转交给 journald 或 logrotate避免日志无限增长。启动后你会看到类似 Runtime: running 的输出。如果卡在启动阶段先看终端最后几行通常是配置解析失败或端口冲突。配置解析失败会明确告诉你哪个字段有问题端口冲突则提示 address already in use这时用 --force 或换端口。4. 一次完整的请求转发验证与日志确认光启动成功不算完得实际发一条请求看它有没有走完「入口 → 路由 → 渠道 → 返回」整条链路。先确认网关状态openclaw gateway status正常输出里会有 Runtime: running 和 Connectivity probe: ok。如果 probe 不是 ok说明网关自身起来了但底层连接有问题先解决这个再发请求。接着用 HTTP 接口发一条 chat completions 请求。假设你的 token 是 local-dev-token-please-changecurl -s http://127.0.0.1:18789/v1/chat/completions \ -H Content-Type: application/json \ -H Authorization: Bearer local-dev-token-please-change \ -d { model: default, messages: [ {role: user, content: ping} ] }如果返回里带了 choices 字段和内容说明请求成功走完了整条链路。如果返回 401是认证没对上如果返回 404 或路由相关错误是路径或模型名没匹配上。想确认路由到底命中了哪条规则开另一个终端跟日志openclaw logs --follow然后在日志里找这次请求的 trace。你会看到请求进入网关、匹配到某条路由、转发给对应渠道、渠道返回、网关回写响应这一串记录。路由命中那行通常会带上匹配的规则名或渠道标识这就是你要的「路由命中确认」。渠道就绪情况可以单独查openclaw channels status --probe如果某个渠道显示未就绪那即使路由命中了请求也会在转发到渠道这一步失败。所以完整的验证顺序是网关 status 正常 → channels status 就绪 → 发请求 → 日志确认路由命中 → 收到响应。5. 常见报错排查401、local proxy failed 与路由不命中排障时先分清错误发生在哪一层。下面几个是我实际遇到过的典型情况。401 Unauthorized。这是认证层的问题跟路由和渠道无关。检查三处配置文件里 gateway.auth.token 或 gateway.auth.password 是否设置客户端发送的 connect.params.auth.token 或 Authorization 头是否与配置一致如果用了环境变量覆盖配置路径确认加载的是你改的那份文件。常见坑是改了配置但没重启hybrid 模式下认证类变更可能没热应用手动重启一次即可。local proxy failed。这个报错通常出现在网关尝试把请求转发给底层渠道时本地连接建立失败。先看 channels status --probe确认目标渠道是否就绪再看网关日志里转发那一步的具体错误常见原因是渠道进程没起来、端口不对或渠道配置里的地址写错。如果渠道本身依赖外部网络确认本地网络能通但不要用任何非正规的网络工具走正常网络配置即可。reading choices 相关报错。这类错误一般发生在解析响应阶段说明请求已经转发出去、渠道也返回了但返回体结构不符合预期。检查渠道返回的原始内容看是不是空响应或错误结构。有时是模型名没匹配上渠道返回了错误对象而不是正常的 choices 数组。对照日志里渠道返回的原始 payload就能定位是渠道侧的问题还是网关解析的问题。路由不命中。表现是请求发出去了日志里没有路由命中记录或者命中了默认规则但没到目标渠道。检查请求里的 model 字段和路径是否与配置中的路由规则匹配。路由规则通常按 model 或路径前缀匹配写错一个字符就会落到默认分支。开 --verbose 后日志会打印实际参与匹配的规则列表对照着改。OAuth 相关报错。如果渠道用了 OAuth 认证报错往往跟 token 过期或回调地址不匹配有关。检查渠道配置里的 OAuth 凭据和回调地址确认与你在渠道侧登记的一致。token 过期的话重新走一次授权流程。排查时记住一个原则先看错误发生在哪一层再看那一层的配置。401 看认证local proxy failed 看渠道连接reading choices 看响应解析路由不命中看匹配规则。分层定位比盲目改配置快得多。6. 把网关接进你的调用链从本地验证到稳定运行本地跑通之后下一步是让它稳定地待在调用链里。如果你用的是 Claude Code 这类编码工具或者 Cline、Codex 这类客户端接入时要把三件套配全Base URL、Key、Model ID。Base URL 指向网关的 HTTP 入口比如 http://127.0.0.1:18789/v1Key 用你在 gateway.auth.token 里配的值Model ID 填你路由规则里定义的模型名。三者缺一要么连不上要么路由不命中。如果你需要长期跑编码或 Agent 任务可以考虑用 Coding Plan 来管理调用配额和模型切换把网关作为统一入口客户端只管发请求路由和渠道切换交给网关处理。这样换模型或加渠道时客户端配置不用动。验证模型是否正常工作可以直接用模型对话页面发一条测试消息确认返回正常后再接进正式流程。接入文档里有各客户端的详细配置示例照着填 Base URL、Key、Model ID 即可。API Key 在控制台的 API Keys 页面管理建议按用途分多个 Key方便排查和回收。最后说个实用技巧网关日志是你最好的朋友。把 openclaw logs --follow 常开在一个终端里发请求时盯着日志看路由命中那行比任何猜测都快。稳定运行的关键不是配置多复杂而是每次改动后都用一次完整请求验证链路确认入口、路由、渠道、返回四段都通。