Gateway 索引

OpenClaw Gateway 是核心服务进程，负责路由、控制面和 Channel 连接。本页为 Gateway 相关文档的导航索引。

快速启动

openclaw gateway --port 18789
openclaw gateway status
openclaw channels status --probe

运行时模型

• 单个常驻进程，处理路由、控制面和 Channel 连接
• 单个多路复用端口，同时提供：
  • WebSocket 控制/RPC
  • HTTP API（OpenAI 兼容：/v1/models、/v1/chat/completions、/v1/responses）
  • Control UI 和 Hooks
• 默认绑定模式：loopback
• 默认端口：18789

配置文档

文档	内容
gateway-configuration	配置概览、常用任务、热重载
gateway-configuration-reference	完整字段参考（Models、MCP、Skills、Plugins、Browser、Gateway、Hooks、Cron、ACP、Secrets、Logging）
gateway-configuration-examples	可复制的完整配置示例
gateway-config-agents	Agent 默认值、多 Agent 路由、Session、Messages、Talk
gateway-config-channels	各 Channel 配置（WhatsApp、Telegram、Discord、Slack 等）
gateway-config-tools	工具策略、自定义 Provider、Base URL

运维文档

文档	内容
gateway-runbook	启动、服务生命周期、操作命令
gateway-secrets	SecretRef 合约、运行时快照、迁移操作
gateway-sandboxing	沙箱配置、Docker/SSH 后端、浏览器沙箱
gateway-heartbeat	定期心跳配置与行为
gateway-local-models	本地模型服务配置
gateway-auth	认证配置（token、password、trusted-proxy）

常用操作命令

# 状态检查
openclaw gateway status
openclaw status
openclaw health
openclaw channels status --probe
 
# 配置操作
openclaw config get agents.defaults.workspace
openclaw config set agents.defaults.heartbeat.every "2h"
openclaw config validate
openclaw doctor
openclaw doctor --fix
 
# 服务管理（macOS）
openclaw gateway install
openclaw gateway restart
openclaw gateway stop
 
# 日志
openclaw logs --follow

热重载模式

模式	行为
hybrid（默认）	安全变更热应用，关键变更自动重启
hot	仅热应用安全变更
restart	任何变更都重启
off	禁用文件监听

常见故障特征

特征	可能原因
refusing to bind gateway ... without auth	非 loopback 绑定但未配置认证
EADDRINUSE	端口冲突
Gateway start blocked: set gateway.mode=local	配置设为 remote 模式
unauthorized during connect	客户端与 Gateway 认证不匹配

OpenAI 兼容端点

• GET /v1/models — 返回 openclaw、openclaw/default、openclaw/<agentId>
• GET /v1/models/{id}
• POST /v1/embeddings
• POST /v1/chat/completions（默认禁用，需 gateway.http.endpoints.chatCompletions.enabled: true）
• POST /v1/responses

相关链接

• gateway-configuration — 配置入口
• gateway-runbook — 运维手册