OpenClaw 常用命令手册：gateway 端口与 LaunchAgent 配置速查

1. 为什么 gateway 命令总在关键时刻掉链子OpenClaw 的 gateway 是本地模型调用的入口默认监听127.0.0.1:18789所有 dashboard、tui、插件请求都从这里走。很多开发者装完 OpenClaw 后能跑通一次第二天再打开就报gateway not connected或ECONNREFUSED第一反应是重装其实九成问题出在端口被占、LaunchAgent 没加载、或者环境变量没传进常驻进程。这篇手册面向已经装好 OpenClaw 的 macOS 开发者聚焦三类高频操作gateway 启动与重启、端口占用排查、LaunchAgent 常驻配置。我会给出可直接复制的config.toml骨架、端口检测命令、plist 模板以及每一步的验证动作。你不需要从头读遇到哪类问题直接跳到对应小节即可。需要说明的是OpenClaw 本身是本地工具模型调用走的是你配置的 API 端点。如果你还没决定用哪家模型服务可以先把 gateway 跑起来再通过 TaoToken 的模型对话页面确认模型可用性最后把 key 写进配置。这样排查链路是分开的不会把「gateway 没起来」和「key 无效」混在一起。2. 前置TaoToken 与 OpenClaw 的接入关系OpenClaw 的模型层通过 OpenAI 兼容协议调用外部服务TaoToken 提供的就是这个兼容端点。你需要在 OpenClaw 的config.toml里填base_url和api_keygateway 启动后由它代理请求。先拿到 key打开 TaoToken 控制台的 API Keys 页面https://taotoken.net/console/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite新建一个 key复制保存。注意 key 只在创建时完整显示一次。然后确认端点地址。OpenClaw 的 provider 配置里base_url填https://taotoken.net/api不要带 UTM 参数否则部分 HTTP 客户端会把 query string 拼进请求路径导致 404。如果你还没装 OpenClaw先确认 Node 版本node -v # 需要 22.x 及以上版本不够就升级LaunchAgent 模式下低版本 Node 会出现进程启动后立即退出的情况日志里只留一行exited with code 1很难定位。3. 可复制配置config.toml 骨架与 LaunchAgent plist3.1 config.toml 最小可用骨架OpenClaw 的配置文件默认在~/.openclaw/config.toml。下面这份骨架可以直接改 key 后用[gateway] host 127.0.0.1 port 18789 log_level info [provider.taotoken] type openai-compatible base_url https://taotoken.net/api api_key sk-你的key default_model deepseek/deepseek-chat [plugins] memory-core true几个容易踩的点port不要改成 80 或 443macOS 下非 root 进程绑定低位端口会直接失败base_url结尾不要加/v1OpenClaw 会自己拼路径default_model的格式是provider/modelprovider 名要和上面[provider.taotoken]的段名一致。改完配置必须重启 gateway热加载不生效openclaw gateway restart3.2 LaunchAgent plist 模板LaunchAgent 的作用是让 gateway 在登录后自动常驻崩溃后由 launchd 拉起。plist 放在~/Library/LaunchAgents/ai.openclaw.gateway.plist?xml version1.0 encodingUTF-8? !DOCTYPE plist PUBLIC -//Apple//DTD PLIST 1.0//EN http://www.apple.com/DTDs/PropertyList-1.0.dtd plist version1.0 dict keyLabel/key stringai.openclaw.gateway/string keyProgramArguments/key array string/usr/local/bin/openclaw/string stringgateway/string stringrun/string /array keyRunAtLoad/key true/ keyKeepAlive/key true/ keyStandardOutPath/key string/Users/你的用户名/.openclaw/logs/gateway.log/string keyStandardErrorPath/key string/Users/你的用户名/.openclaw/logs/gateway.err.log/string keyEnvironmentVariables/key dict keyPATH/key string/usr/local/bin:/usr/bin:/bin/string /dict /dict /plistProgramArguments里的 openclaw 路径用which openclaw查出来再填Homebrew 装的一般是/usr/local/bin/openclaw或/opt/homebrew/bin/openclaw。KeepAlive设为 true 后手动kill进程会被立刻拉起调试时想彻底停掉要用launchctl bootout。加载 plistlaunchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/ai.openclaw.gateway.plist launchctl list | grep openclaw第二行输出里如果看到ai.openclaw.gateway且退出码为 0说明加载成功。4. 验证请求从端口到模型响应的完整链路4.1 确认端口监听lsof -nP -iTCP:18789 -sTCP:LISTEN正常输出会有一行openclaw进程占用 18789。如果没有任何输出说明 gateway 没起来先看日志tail -f ~/.openclaw/logs/gateway.log如果输出里是别的进程名比如某个 Node 脚本或旧版进程那就是端口冲突跳到第 5 节。4.2 用 curl 直接打 gatewaycurl -s http://127.0.0.1:18789/health返回{status:ok}说明 gateway 本身健康。再测模型链路curl -s http://127.0.0.1:18789/v1/chat/completions \ -H Content-Type: application/json \ -d { model: deepseek/deepseek-chat, messages: [{role:user,content:ping}] }如果这一步返回 401说明 key 没传进 gateway 进程检查config.toml里的api_key是否被 LaunchAgent 的环境变量覆盖。如果返回 404多半是base_url写错确认是https://taotoken.net/api而不是带/v1的地址。4.3 用 openclaw 自带命令验证openclaw status openclaw models statusstatus里重点看三行Gateway reachable、Port 18789、Sessions。models status会列出每个 provider 的连通性如果 TaoToken 那行显示unreachable先用上面的 curl 确认网络层没问题再查 key。想直接在浏览器里对话验证打开模型对话页面https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodelsutm_campaignrewrite选同一个模型发一条消息能正常回复说明 key 和端点都没问题问题就锁定在 OpenClaw 本地配置。5. 本篇常见错排查5.1 gateway not connected / ECONNREFUSED按这个顺序查不要跳步openclaw status lsof -nP -iTCP:18789 -sTCP:LISTEN openclaw logs --follow openclaw doctor --deepECONNREFUSED的本质是「端口没人监听」所以第二步是关键。如果lsof有输出但status还是 unreachable检查config.toml里的host是不是被改成了0.0.0.0而客户端连的是127.0.0.1两者在 macOS 上不一定互通。5.2 端口 18789 被占用lsof -nP -iTCP:18789 -sTCP:LISTEN拿到 PID 后确认是不是旧版 OpenClaw 残留ps -p PID -o command如果是旧进程先openclaw gateway stop再kill PID。如果占用者是无关程序改config.toml里的port为 18790 或其他高位端口然后重启。改端口后记得同步更新 dashboard 访问地址和任何硬编码了 18789 的脚本。5.3 LaunchAgent 加载了但进程反复重启launchctl print gui/$(id -u)/ai.openclaw.gateway看输出里的last exit code。如果是 78通常是ProgramArguments路径写错如果是 1看gateway.err.log最后 20 行。常见原因是 plist 里没配PATH导致 openclaw 内部调用node时找不到。5.4 修改配置后不生效LaunchAgent 模式下openclaw gateway restart有时只重启了前台进程launchd 托管的那个没动。稳妥做法launchctl bootout gui/$(id -u)/ai.openclaw.gateway launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/ai.openclaw.gateway.plist5.5 环境变量传不进常驻进程export DEEPSEEK_API_KEYxxx只对当前终端有效LaunchAgent 读不到。要么写进 plist 的EnvironmentVariables要么用launchctl setenv DEEPSEEK_API_KEY sk-xxxx后者需要重新登录或重启 gateway 才生效。更推荐直接把 key 写进config.toml少一层环境变量就少一个排查点。6. 长期编码与 Agent 场景的接入建议如果你把 OpenClaw 当日常编码助手或 Agent 运行时gateway 的稳定性比单次对话重要得多。几个实测下来有效的习惯配置改完统一走gateway restart不要手动 kill 进程plist 里KeepAlive保持 true让 launchd 兜底定期openclaw update并重启避免旧版本和新模型协议不兼容。需要长时间跑 Agent 任务的话建议单独申请一个 Coding Plan 专用的 keyhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite和日常对话的 key 分开这样额度消耗和排障互不干扰。接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite里面有各语言 SDK 的 base_url 填法和 OpenClaw 的config.toml字段能对上。最后提醒一个高频坑不要连续执行openclaw gateway多次。LaunchAgent 模式下每次调用都可能触发一次 bootstrap端口没释放就再起一个结果就是 18789 被两个进程抢日志里交替出现address already in use和gateway started。遇到状态混乱先launchctl bootout清干净再重新 bootstrap比反复 restart 有效。