夜雨聆风最近很多小伙伴问，OpenClaw 的 Gateway 到底怎么用？官方文档全是英文，技术术语一堆，看得头大。
今天就给大家整理一份「零技术门槛」的 Gateway 操作指南，把官方文档翻译成大白话，所有命令直接复制就能用，新手也能5分钟启动，再也不用对着英文文档发愁啦！
先跟大家说个重点：Gateway 是 OpenClaw 的核心「总管家」，它不启动，OpenClaw 所有功能（收发消息、运行AI智能体）都用不了！所以不管你是用 WhatsApp、Telegram 、飞书、钉钉、微信还是其他渠道，先搞定 Gateway 再说～
一、先搞懂：Gateway 到底是什么？（新手必看）
不用记复杂的技术定义，记住3个核心作用就够了：
✅ 连接聊天渠道：稳定绑定 Telegram、WhatsApp、飞书等，负责消息收发
✅ 运行核心功能：AI智能体、API接口调用，全靠它后台支撑
✅ 提供管理入口：启动后能通过网页访问，可视化管理所有配置
一句话总结：Gateway 就是 OpenClaw 的「总管家」，必须一直运行，才能正常使用所有功能！
二、5分钟快速启动｜新手入门必看流程
全程复制命令，不用手动输入，跟着步骤来，保证一次成功！
基础信息（先记这 3 个）
默认端口：18789
本地访问地址：http://127.0.0.1:18789
配置文件路径：~/.openclaw/openclaw.json（Windows非WSL2路径：C:\Users\你的用户名\.openclaw\openclaw.json）
Step 1：启动 Gateway 服务
打开电脑终端（Windows用WSL2终端，Mac/Linux直接打开终端），复制下面的命令，选一个执行即可：
# 1. 基础启动（最常用，默认端口18789，新手首选）openclaw gateway --port 18789# 2. 带日志启动（排查问题用，能看到完整运行记录）openclaw gateway --port 18789 --verbose# 3. 端口被占用时强制启动（提示端口被占用时用，自动关掉旧进程）openclaw gateway --force
Step 2：验证服务是否正常启动
启动后，执行下面的命令，检查网关是否健康运行：
# 基础状态查询（新手首选，快速看是否运行）openclaw gateway status# 实时查看日志（出问题时必用，能找到报错原因）openclaw logs --follow
✅ 成功标志：返回结果里有「Runtime: running」和「RPC probe: ok」，就说明启动成功啦！
Step 3：验证聊天渠道是否可用
这一步很关键，确认你绑定的聊天渠道（比如WhatsApp）能正常收发消息：
# 主动探测所有渠道的连接状态openclaw channels status --probe
✅ 成功标志：每个渠道都显示「connected」，探测结果为正常，就可以正常使用啦！
三、核心基础规则｜看完再也不懵
新手不用死记硬背，记住这2个核心规则，能避免80%的问题！
1. 端口与访问规则（重点）
默认端口：18789，启动后本地访问地址：http://127.0.0.1:18789
访问限制：默认只能自己的电脑访问，外网/其他设备连不上（安全！）
端口优先级（哪个设置说了算）：命令里的--port > 系统环境变量 > 配置文件 > 默认18789
安全要求：如果要让其他设备访问，必须设置密码/访问令牌，否则会拒绝启动！
2. 配置自动更新（热重载）规则
改完配置文件后，网关会自动生效吗？默认是「懒人模式」，不用手动重启，具体看下面的表格：
模式 | 大白话解释 | 适用人群 |
|---|---|---|
hybrid（默认） | 能不重启就不重启，安全配置自动生效，需要重启的会自动重启 | 绝大多数新手、日常使用 |
off | 改配置不自动生效，必须手动重启网关 | 怕配置乱改影响运行的用户 |
hot | 只自动生效安全配置，需要重启的配置不改、不重启 | 不能中断服务的生产环境 |
restart | 改配置就自动重启网关，立刻全量生效 | 开发测试环境 |
### 具体操作步骤（新手必看，直接照做）
热重载的核心是「修改配置文件+生效」，全程不用复杂操作，分3步搞定，不同系统操作基本一致，重点记配置文件路径和修改方法即可～
Step 1：找到配置文件（关键！先找对文件）
热重载的模式的设置，全在 OpenClaw 的核心配置文件里，不同系统的文件路径如下，直接对应找就行：
✅ Mac/Linux 系统：路径固定为
~/.openclaw/openclaw.json（复制这个路径，终端里直接打开）✅ Windows 系统（WSL2）：和 Mac/Linux 路径一致
~/.openclaw/openclaw.json✅ Windows 系统（非WSL2）：路径为
C:\Users\你的用户名\.openclaw\openclaw.json（替换“你的用户名”为自己电脑的用户名）
小提醒：如果找不到文件，先执行openclaw gateway status，终端会显示配置文件的具体路径，跟着路径找就不会错！
Step 2：打开并修改配置文件（修改热重载模式）
找到文件后，可选择「图形化记事本」或「纯命令行」修改，下面重点补充纯命令行操作（适配Mac/Linux/Windows WSL2，新手也能直接复制命令），两种方式选一种即可：
方式1：纯命令行修改（推荐，不用切换窗口）
全程在终端操作，复制对应命令，一步步来，不用手动找文件、打开编辑器：
Mac/Linux/Windows WSL2 通用：用系统自带的 nano 编辑器（最简单，新手首选），直接执行命令打开配置文件
# 直接打开配置文件，无需手动找路径nano ~/.openclaw/openclaw.json命令行内修改模式： 打开后，按
Ctrl+W（查找），输入gateway，按 Enter 快速定位到"gateway": {}段落在
"gateway": {}里面，添加/修改热重载模式，直接复制下面的代码替换（按需改模式）："reload": {"mode": "hybrid"//可替换为 off、hot、restart，新手默认保留hybrid即可}修改后，按
Ctrl+O（保存），按 Enter 确认保存，再按Ctrl+X（退出编辑器），全程不用鼠标操作可选：用 vim 编辑器（适合有基础的用户）
# 用vim打开配置文件vim ~/.openclaw/openclaw.json# 打开后按 i 进入编辑模式，修改模式后，按 Esc，输入 :wq 保存并退出
方式2：图形化打开修改（原方法，保留供新手选择）
Mac/Linux 终端操作：复制下面的命令，直接在终端执行，就能打开配置文件编
# 用系统自带编辑器打开，新手首选nano ~/.openclaw/openclaw.json
Windows 操作：直接找到对应路径的
openclaw.json文件，右键选择「记事本」打开即可（不用装其他编辑软件）修改模式：在打开的文件里，找到
"gateway": {}这个段落，在里面添加/修改
"reload": {"mode": "你要设置的模式"}# 示例（默认hybrid模式，直接复制替换即可）"gateway": {"reload": {"mode": "hybrid" // 可替换为 off、hot、restart}}
保存退出： Mac/Linux（nano编辑器）：按
Ctrl+O保存，按Enter确认，再按Ctrl+X退出Windows（记事本）：点击左上角「文件」→「保存」，直接关闭即可
小提醒：命令行修改时，不要删错配置文件里的引号、逗号，若不小心改乱，执行 openclaw doctor就能自动修复格式错误～
Step 3：让修改生效（不用手动重启网关！）
根据你设置的模式，生效方式不同，新手重点记默认的hybrid模式即可：
✅ 模式为 hybrid（默认）：修改后无需任何操作，网关会自动检测配置变化，安全的配置立刻生效，需要重启的配置会自动重启网关，全程不用管
✅ 模式为 hot：和hybrid一样，自动生效安全配置，无需手动操作
✅ 模式为 restart：修改保存后，网关会自动重启，配置立刻全量生效，不用手动执行重启命令
✅ 模式为 off：修改后不会自动生效，必须手动执行重启命令，配置才会生效
# 手动重启网关（off模式专用）openclaw gateway restart
额外技巧：手动触发热重载（可选）
如果修改配置后，想立刻让配置生效（比如hybrid模式下想强制生效），可以执行下面的命令，手动触发一次热重载，不用重启网关：
# 手动触发热重载（所有模式通用）openclaw gateway call reload
小提醒：修改配置时，一定要注意格式正确，不要删错引号、逗号，否则网关会启动失败，遇到这种情况，执行 openclaw doctor 就能自动修复格式错误～
四、常用命令大全｜直接复制使用（按场景分类）
整理了最常用的命令，按使用场景分类，不用翻来翻去，需要时直接复制！
1. 网关状态查询（日常排查）
# 基础状态查询（快速确认是否运行）openclaw gateway status# 深度查询（排查深层问题用）openclaw gateway status --deep# 全量健康检查openclaw health
2. 网关生命周期管理（开机自启/重启/停止）
# 安装开机自启服务（重启电脑自动运行，推荐！）openclaw gateway install# 重启网关（改配置、出小问题时用）openclaw gateway restart# 停止网关openclaw gateway stop# 自动体检+修复（神器！遇到问题先跑这个）openclaw doctor
3. 日志与排障（出问题必用）
# 实时查看运行日志（能找到所有报错原因）openclaw logs --follow
五、进阶操作｜按需使用（新手可先跳过）
如果需要远程访问、多开网关，或者做开发测试，看下面的操作，普通人不用刻意学～
1. 远程访问网关（在外也能连）
安全提醒：绝对不要直接把网关端口暴露到公网，容易被攻击！优先用下面的安全方式～
首选：用 Tailscale 或 VPN，和网关设备连到同一个虚拟局域网，直接访问即可
备用（有服务器的用户）：SSH隧道，复制下面的命令（替换成自己的服务器信息）
ssh -N -L 18789:127.0.0.1:18789 你的服务器用户名@服务器IP2. 一台电脑多开网关（非必要不操作）
99%的用户只用1个网关就够了，只有需要隔离不同配置/渠道时才多开，必须满足4个「唯一」：
唯一的端口号
唯一的配置文件路径
唯一的数据存储目录
唯一的AI智能体工作空间
多开示例（直接复制，修改路径和端口即可）：
# 第一个网关实例OPENCLAW_CONFIG_PATH=~/.openclaw/a.jsonOPENCLAW_STATE_DIR=~/.openclaw-a openclaw gateway --port 19001# 第二个网关实例OPENCLAW_CONFIG_PATH=~/.openclaw/b.jsonOPENCLAW_STATE_DIR=~/.openclaw-b openclaw gateway --port 19002
3. 开发者模式（开发测试用）
# 初始化开发环境openclaw --dev setup# 启动开发模式网关（默认端口19001）openclaw --dev gateway --allow-unconfigured# 查看开发模式状态openclaw --dev status
六、常见报错排查｜90%的问题都能解决
遇到报错别慌，对照下面的表格，一键解决，新手也能轻松排障！
报错原文 | 大白话解释 | 解决办法 |
|---|---|---|
refusing to bind gateway ... without auth | 外网可访问，但没设密码/令牌，系统拒绝启动 | 1. 设置密码/令牌；2. 改回本地访问配置 |
another gateway instance is already listening | 端口被占用，已有一个网关在运行 | 用 openclaw gateway --force 强制启动，或换端口 |
unauthorized during connect | 密码/令牌输错，和网关设置不一致 | 检查并修改密码/令牌，确保完全一致 |
channels status --probe 显示 disconnected | 聊天渠道掉线，没登录成功 | 执行 openclaw channels login 渠道名（比如飞书：feishu） |
七、新手避坑终极提醒
❌ 不要随便暴露网关端口到公网，远程访问优先用VPN/SSH隧道
✅ 遇到问题先做两步：① 执行 openclaw doctor 自动修复；② 看日志找报错
❌ 不要多开网关，99%的用户1个就够，多开容易搞混配置
✅ 改配置不用手动重启，默认的hybrid模式会自动生效/重启
最后说一句
Gateway 看似复杂，但只要跟着这份指南，复制命令、按步骤操作，新手也能轻松搞定。如果还有其他报错，或者某个步骤看不懂，评论区留言，我会一一回复～
觉得有用的话，记得点赞收藏，下次用的时候直接找，不用再翻官方文档啦！❤️
