OpenClaw本地服务连接失败的五大原因及解决步骤：一、检查服务是否启动，执行openclaw status并用openclaw start --mode local启动；二、确认config.yaml中gateway.bind_address为0.0.0.0；三、排查18789端口占用并释放或更换端口；四、确保gateway.auth.token存在且有效；五、Docker部署时检查-p端口映射及容器内监听状态。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 免费无限量使用 DeepSeek R1 模型☜☜☜
如果您尝试访问 OpenClaw 本地服务，但浏览器提示 “This site can’t be reached 127.0.0.1 refused to connect”，则说明客户端已发起连接请求，但 OpenClaw 核心服务未在指定端口监听或未能正常启动。以下是解决此问题的步骤：
一、检查 OpenClaw 服务是否已启动
OpenClaw 未运行是导致连接被拒绝的最直接原因。服务进程缺失将使 127.0.0.1:18789（默认仪表板端口）完全不可达。
1、在终端执行 openclaw status 查看当前运行状态。
2、若显示 inactive 或 command not found，需先确保已正确安装并初始化：运行 openclaw init 完成基础配置。
3、手动启动服务：openclaw start --mode local，注意避免遗漏 --mode local 参数。
二、验证监听地址是否为 0.0.0.0
OpenClaw 默认可能绑定到 127.0.0.1，该地址仅允许本机进程访问，在 Docker 或某些系统配置下会导致外部（包括本机浏览器）无法建立连接。
1、打开配置文件 ~/.openclaw/config.yaml。
2、查找 gateway.bind_address 字段，确认其值为 0.0.0.0 而非 127.0.0.1。
3、若字段不存在，手动添加一行：bind_address: 0.0.0.0，并确保缩进与同级字段一致。
4、保存后重启服务：openclaw restart。
三、排查端口占用冲突
18789 端口被其他进程占用时，OpenClaw 启动会失败且不报显式错误，表现为服务看似运行但实际未监听。
1、Linux/macOS 执行：lsof -i :18789 或 netstat -tuln | grep 18789。
2、Windows 执行：netstat -ano | findstr :18789。
3、若发现 PID 占用，使用 kill -9 [PID]（Linux/macOS）或 taskkill /PID [PID] /F（Windows）终止进程。
4、也可临时更换端口：在 config.yaml 中添加 gateway.port: 18790，然后访问 http://127.0.0.1:18790。
四、确认 Gateway 认证配置完整
OpenClaw 在启用认证模式时，若缺少有效 token，会拒绝启动网关，从而导致连接被拒，日志中常出现 refusing to bind gateway without auth。
1、检查 ~/.openclaw/config.yaml 中 gateway.auth.token 是否存在且非空。
2、若未设置，生成新 token：openclaw gateway token generate，并将输出结果填入配置文件对应位置。
3、确保 token 行末无多余空格或换行符——YAML 对空白字符极其敏感。
4、执行 openclaw gateway auth verify 验证配置有效性。
五、检查 Docker 容器网络绑定（Docker 部署场景）
当 OpenClaw 以容器方式运行时，宿主机访问 127.0.0.1 实际指向容器内部，而容器内服务若未正确暴露端口，则连接必然失败。
1、确认运行命令中包含端口映射参数，例如：-p 18789:18789。
2、检查容器日志：docker logs [container_id]，搜索关键词 listening on 或 ERR。
3、进入容器内部验证监听：docker exec -it [container_id] sh，再执行 netstat -tuln | grep 18789。
4、若容器内无 netstat，改用 ss -tuln | grep 18789 替代。
