1. OpenClaw Gateway 服务是什么本地部署运维场景拆解OpenClaw Gateway 是 OpenClaw 框架里的统一入口服务你可以把它理解成整个 AI 助手系统的“前台总机”外部渠道Telegram、飞书、Discord、微信等的消息先到它这里由它完成认证、会话查询、路由决策再转发给内部的 AI 引擎或技能系统。它本身不负责“思考”但所有请求都得从它手里过一遍所以它的启动、停止、监控直接决定了整套系统能不能稳定对外服务。这篇文章面向的是本地部署与运维场景不是“点一下就能跑”的玩具教程。我会把可复制的启动/停止命令、systemd 单元配置、健康检查脚本、日志监控方案都摊开讲并且给出验证 Gateway 状态与端口连通性的具体动作。适合已经在本地或内网跑 OpenClaw、需要把它做成常驻服务的人也适合刚接手一套 Gateway 部署、需要快速搞清楚“它到底活没活着”的运维同学。我试过在一台 4C8G 的内网机器上把 Gateway 从“手动前台跑”改成 systemd 托管中间踩过端口占用、优雅关闭超时、日志写满磁盘这几个坑。下面按“先能起来、再能停干净、最后能看见”的顺序来每一步都尽量给你能直接粘贴的命令。先明确几个核心检索词方便你对照自己的场景OpenClaw Gateway 启动命令、Gateway 停止与优雅关闭、Gateway 健康检查与端口连通性验证、systemd 托管 Gateway 服务。这几个词基本覆盖了本地运维最常搜的问题。在动手之前先确认你的环境里有这几样东西OpenClaw CLI 已安装openclaw --version能输出版本号、配置文件默认在~/.openclaw/config.yaml、日志目录/var/log/openclaw/可写。如果这些还没就绪后面的命令会直接报错所以先花两分钟确认。openclaw --version ls -la ~/.openclaw/ ls -ld /var/log/openclaw/三条都正常返回再往下走。如果openclaw命令找不到说明 CLI 没进 PATH先解决安装问题别急着配 systemd——服务托管的前提是命令本身能跑通。2. TaoToken 前置准备给 Gateway 配好模型出口Gateway 负责路由但真正干活的 AI 引擎需要一个模型出口。本地部署时很多人会把模型请求指向 TaoToken 的兼容接口这样 Gateway 的路由层不用改只改下游模型地址就行。这一步属于“前置准备”不做也能启动 Gateway但启动后 AI 请求会失败所以建议一起配好。TaoToken 的 API 地址是https://taotoken.net/api兼容 OpenAI 风格的调用方式。你需要在控制台创建一个 API Key然后把它写进 OpenClaw 的模型配置里。注意API Key 属于敏感信息别直接写进会提交到 Git 的配置文件用环境变量注入更稳妥。先拿 Key进入控制台创建密钥复制出来只显示一次。然后配置模型出口。OpenClaw 的模型配置通常也在~/.openclaw/config.yaml里找到models或ai_engine段落按下面这样填# ~/.openclaw/config.yaml 片段模型出口指向 TaoToken ai_engine: provider: openai-compatible base_url: https://taotoken.net/api api_key: ${TAOTOKEN_API_KEY} # 从环境变量读取别硬编码 model: claude-sonnet-4-5 # 按你实际可用的模型 ID 填 timeout: 60000 # AI 场景建议 60s 以上这里有个关键点base_url结尾不要多加/v1具体以你所用模型 ID 的调用规范为准api_key用${TAOTOKEN_API_KEY}占位实际值通过环境变量传。systemd 单元里会用EnvironmentFile注入后面第 3 节会写全。把 Key 写进一个只有 root 可读的环境文件sudo mkdir -p /etc/openclaw sudo tee /etc/openclaw/gateway.env /dev/null EOF TAOTOKEN_API_KEYsk-你的实际密钥 OPENCLAW_GATEWAY_AUTH_TOKEN换成32位以上随机串 EOF sudo chmod 600 /etc/openclaw/gateway.env sudo chown root:root /etc/openclaw/gateway.envOPENCLAW_GATEWAY_AUTH_TOKEN是 Gateway 自己的认证令牌和模型 Key 是两回事别混用。生成随机串可以用openssl rand -hex 32。配好之后先别急着 systemd用前台方式验证一次模型出口通不通export TAOTOKEN_API_KEYsk-你的实际密钥 openclaw gateway start --log-level debug前台启动后另开一个终端发一条测试请求下一节给具体命令。如果日志里出现模型调用成功、没有 401说明前置准备到位。确认后再 CtrlC 停掉进入 systemd 托管。需要提醒的是TaoToken 在这里的角色是“模型出口”不是“替代 Gateway”。Gateway 的路由、会话、认证逻辑仍然由 OpenClaw 自己负责两者职责别搞混。如果你只是想让 Gateway 先跑起来、暂时不接模型也可以跳过本节但第 4 节的验证请求会拿不到 AI 响应。3. 可复制配置systemd 单元 启动停止命令手动前台跑只适合调试生产或长期本地部署必须交给 systemd 托管否则 SSH 一断服务就没了。这一节给你完整的 systemd 单元文件、启动/停止/重启命令以及优雅关闭的超时配置。先写单元文件/etc/systemd/system/openclaw-gateway.service[Unit] DescriptionOpenClaw Gateway Service Documentationhttps://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content Afternetwork-online.target redis.service Wantsnetwork-online.target [Service] Typesimple Useropenclaw Groupopenclaw WorkingDirectory/home/openclaw EnvironmentFile/etc/openclaw/gateway.env ExecStart/usr/local/bin/openclaw gateway start --config /home/openclaw/.openclaw/config.yaml ExecStop/usr/local/bin/openclaw gateway stop --timeout 60 Restarton-failure RestartSec5 TimeoutStopSec90 KillModemixed KillSignalSIGTERM LimitNOFILE65535 # 日志交给 journald同时保留文件日志 StandardOutputjournal StandardErrorjournal SyslogIdentifieropenclaw-gateway [Install] WantedBymulti-user.target几个参数值得单独说。ExecStop里带了--timeout 60意思是给优雅关闭最多 60 秒TimeoutStopSec90是 systemd 层面的兜底超过 90 秒还没退就强杀。KillModemixed保证 SIGTERM 先发给主进程让它有机会走完“停止接收新请求 → 等待在途请求 → 持久化会话”的流程。Restarton-failure让进程异常退出后自动拉起但正常systemctl stop不会触发重启。写完单元文件重载并启动sudo systemctl daemon-reload sudo systemctl enable openclaw-gateway sudo systemctl start openclaw-gateway sudo systemctl status openclaw-gateway --no-pagerstatus里看到active (running)就说明起来了。如果看到failed先别慌第 5 节有对照排查。日常启停命令整理成一张表方便你复制操作命令说明启动sudo systemctl start openclaw-gateway后台常驻停止sudo systemctl stop openclaw-gateway触发优雅关闭重启sudo systemctl restart openclaw-gateway配置变更后使用查看状态sudo systemctl status openclaw-gateway看 active/failed开机自启sudo systemctl enable openclaw-gateway写入 multi-user.target取消自启sudo systemctl disable openclaw-gateway维护时用实时日志sudo journalctl -u openclaw-gateway -f排障首选如果你不想用 systemdOpenClaw 自带的命令也能管openclaw gateway start --daemon # 后台启动 openclaw gateway stop --timeout 60 # 优雅停止 openclaw gateway restart # 重启 openclaw gateway status # 查看状态但--daemon方式没有开机自启和崩溃拉起长期跑还是推荐 systemd。两者别同时用否则会出现“systemd 以为自己在管实际进程是手动拉起的”这种混乱状态。配置文件里和启停相关的几个参数也贴一下方便你对照调整gateway: port: 18789 host: 0.0.0.0 auth_token: ${OPENCLAW_GATEWAY_AUTH_TOKEN} max_connections: 1000 request_timeout: 60000 session: storage: redis # 多实例或重启保持会话时用 redis ttl: 3600 logging: level: info format: json output: /var/log/openclaw/gateway.log monitoring: enabled: true metrics_port: 9090 health_check_path: /health改完配置记得sudo systemctl restart openclaw-gatewaysystemd 不会自动感知文件变化。4. 验证请求与成功结果健康检查 端口连通性服务起来不等于能用。这一节给你三个层次的验证进程层、端口层、业务层。三层都过才算真正“Gateway 状态正常”。第一层进程和 systemd 状态systemctl is-active openclaw-gateway systemctl is-enabled openclaw-gateway期望输出active和enabled。如果is-active返回activating卡住多半是启动时在等依赖比如 Redis 没起来看 journalctl 日志定位。第二层端口连通性。Gateway 默认监听 18789监控指标在 9090ss -lntp | grep -E 18789|9090 curl -s -o /dev/null -w %{http_code}\n http://127.0.0.1:18789/healthss能看到 LISTEN 状态curl期望返回200。如果curl返回000说明端口没通回到第 5 节排查。注意host: 0.0.0.0时本机用127.0.0.1测外部机器用内网 IP 测别用localhost混着来。第三层业务层验证。带认证令牌请求健康检查并确认组件状态TOKEN$(grep OPENCLAW_GATEWAY_AUTH_TOKEN /etc/openclaw/gateway.env | cut -d -f2) curl -s -H Authorization: Bearer $TOKEN http://127.0.0.1:18789/health | jq .成功返回类似{ status: healthy, version: 1.2.0, uptime: 3600, components: { database: healthy, redis: healthy, ai_engine: healthy } }重点看components.ai_engine是不是healthy。如果它是unhealthy说明第 2 节的模型出口没配通Gateway 本身活着但干不了活。再发一条真实请求验证端到端curl -s -X POST http://127.0.0.1:18789/v1/chat \ -H Authorization: Bearer $TOKEN \ -H Content-Type: application/json \ -d {message:ping,session_id:test-001} | jq .拿到带reply字段的响应说明从 Gateway 到模型出口整条链路通了。如果返回 401是令牌不对返回 502/504是下游模型出口不通返回choices相关解析错误多半是模型响应格式和 Gateway 预期不一致检查base_url和模型 ID。把健康检查做成脚本方便定时跑#!/usr/bin/env bash # /usr/local/bin/openclaw-healthcheck.sh set -euo pipefail TOKEN$(grep OPENCLAW_GATEWAY_AUTH_TOKEN /etc/openclaw/gateway.env | cut -d -f2) CODE$(curl -s -o /tmp/oc_health.json -w %{http_code} \ -H Authorization: Bearer $TOKEN \ http://127.0.0.1:18789/health) if [ $CODE ! 200 ]; then echo UNHEALTHY: http_code$CODE exit 1 fi STATUS$(jq -r .status /tmp/oc_health.json) echo Gateway status: $STATUS [ $STATUS healthy ]加进 crontab 每分钟跑一次失败时配合告警* * * * * /usr/local/bin/openclaw-healthcheck.sh || logger -t openclaw-health Gateway healthcheck failed监控指标也可以直接抓一眼curl -s http://127.0.0.1:9090/metrics | grep -E openclaw_(requests_total|active_sessions|errors_total)看到openclaw_requests_total在涨、openclaw_errors_total不涨基本可以放心。5. 本篇常见错排查401、端口占用、优雅关闭超时这一节按真实报错来每个都给你症状、定位命令、修复动作。排障时优先看journalctl -u openclaw-gateway -n 100 --no-pager90% 的问题日志里直接写了。报错一401 Unauthorized症状curl /health或业务请求返回 401日志里出现auth failed或invalid token。原因通常是三种请求没带Authorization头、令牌值和配置文件不一致、环境变量没被 systemd 读到。定位# 确认 systemd 实际读到的环境变量 sudo systemctl show openclaw-gateway -p Environment # 确认配置文件里的 auth_token 占位符 grep auth_token ~/.openclaw/config.yaml修复确保/etc/openclaw/gateway.env里的OPENCLAW_GATEWAY_AUTH_TOKEN和请求头里的值完全一致注意别带多余空格改完daemon-reloadrestart。如果配置文件里写的是硬编码令牌而环境变量是另一个值以环境变量为准环境变量覆盖优先级更高。报错二端口占用 / local proxy failed症状启动即退出日志出现address already in use或bind: permission denied如果前面挂了反向代理可能看到local proxy failed。定位sudo ss -lntp | grep 18789 sudo lsof -i :18789如果是旧进程没退干净先sudo systemctl stop openclaw-gateway确认端口释放再启。如果是别的程序占了 18789改 Gateway 端口gateway: port: 18790改完记得同步改反向代理和健康检查脚本里的端口。permission denied一般是端口小于 1024 且没用 root 或CAP_NET_BIND_SERVICE换高位端口最省事。报错三优雅关闭超时systemd 强杀症状systemctl stop卡很久日志出现graceful shutdown timeout, force killing或者TimeoutStopSec到期后进程被 SIGKILL。原因是在途请求太多、下游模型响应慢60 秒没等完。定位sudo journalctl -u openclaw-gateway | grep -i shutdown\|timeout修复分两步一是把ExecStop的--timeout和TimeoutStopSec一起调大比如 120/150二是从根上减少长请求把request_timeout和模型出口超时对齐避免请求无限挂起。如果会话存储用的是memory关闭时会话会丢改成redis能持久化重启后现场还在。报错四reading choices 解析失败症状业务请求返回 500日志里出现reading choices或cannot read property of undefined。这通常不是 Gateway 本身的问题而是模型出口返回的 JSON 结构和 Gateway 预期不一致。定位sudo journalctl -u openclaw-gateway -n 50 --no-pager | grep -i choices修复检查base_url是否指向了正确的兼容接口模型 ID 是否拼写正确以及返回体里是否真的有choices字段。可以先用 curl 直接打模型出口确认原始返回curl -s https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer $TAOTOKEN_API_KEY \ -H Content-Type: application/json \ -d {model:claude-sonnet-4-5,messages:[{role:user,content:hi}]} | jq .choices如果这里就报错问题在模型出口配置不在 Gateway。报错五OAuth / 认证回调失败如果你在 Gateway 前面接了带 OAuth 的入口可能遇到回调地址不匹配。这类问题先确认回调 URL 和实际访问域名一致再检查反向代理有没有透传X-Forwarded-Proto和Host头。Nginx 里补上proxy_set_header Host $host; proxy_set_header X-Forwarded-Proto $scheme; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;排查完记得把临时开的--log-level debug关掉debug 日志量很大容易把磁盘写满。6. 日志监控与长期运维把 Gateway 变成可观测服务服务能起能停只是及格线长期运维的关键是“出问题之前就能看见”。这一节把日志、指标、告警串起来给你一套本地可落地的最小可观测方案。日志方面systemd 已经通过 journald 收集了 stdout/stderr同时配置文件里还写了文件日志/var/log/openclaw/gateway.log。两者各有用途journald 适合按服务查文件日志适合用 jq 做结构化分析。先确认日志在写sudo journalctl -u openclaw-gateway -n 20 --no-pager tail -n 20 /var/log/openclaw/gateway.log | jq -c {ts:.timestamp,level:.level,msg:.message}如果文件日志没生成检查/var/log/openclaw/的属主是不是openclaw用户systemd 单元里Useropenclaw时它得有写权限。日志轮转必须配否则 JSON 日志几天就能把磁盘写满。用 logrotatesudo tee /etc/logrotate.d/openclaw-gateway /dev/null EOF /var/log/openclaw/gateway.log { daily rotate 14 size 100M compress delaycompress missingok notifempty copytruncate create 0640 openclaw openclaw } EOFcopytruncate很关键它复制后清空原文件不需要重启进程就能继续写。配完手动验证一次sudo logrotate -d /etc/logrotate.d/openclaw-gateway-d是 dry-run只打印不执行确认没报错再去掉-d。指标方面Gateway 在 9090 暴露 Prometheus 格式。本地最小方案是 Prometheus Grafana但如果你只想快速看趋势用一条命令也能盯watch -n 5 curl -s http://127.0.0.1:9090/metrics | grep -E openclaw_(requests_total|errors_total|active_sessions|request_duration_seconds_count)重点盯三个信号openclaw_errors_total持续增长说明有稳定错误源openclaw_active_sessions只涨不跌可能是会话没清理openclaw_request_duration_seconds的 P99 突然抬高通常是下游模型出口变慢。告警不用一上来就上重型系统先用 cron 健康检查脚本兜底# 每 2 分钟检查一次连续失败写系统日志 */2 * * * * /usr/local/bin/openclaw-healthcheck.sh || logger -t openclaw-health healthcheck failed at $(date -Is)再配合journalctl -t openclaw-health就能回溯失败时间点。等规模上来再把 Prometheus 的openclaw_errors_total和openclaw_request_duration_seconds接进 AlertManager。长期运维还有几个容易忽略的点。一是令牌轮换OPENCLAW_GATEWAY_AUTH_TOKEN建议 30 天换一次换的时候先更新环境文件、再restart避免请求方还在用旧令牌。二是配置版本化~/.openclaw/config.yaml和 systemd 单元都进 Git改之前先 commit出问题能快速回滚。三是定期做恢复演练手动stop再start确认会话用 redis 存储时能恢复、健康检查能重新变绿。最后给一个日常巡检清单贴在你自己的运维笔记里# 1. 服务状态 systemctl is-active openclaw-gateway # 2. 端口监听 ss -lntp | grep -E 18789|9090 # 3. 健康检查 /usr/local/bin/openclaw-healthcheck.sh # 4. 错误计数 curl -s http://127.0.0.1:9090/metrics | grep openclaw_errors_total # 5. 最近错误日志 sudo journalctl -u openclaw-gateway -p err -n 20 --no-pager这五条跑一遍不超过十秒但能覆盖绝大多数“服务悄悄挂了”的情况。Gateway 作为 OpenClaw 的中枢它的可观测性做扎实了后面接渠道、加技能、扩实例才有稳定的地基。需要进一步查接口细节时可以对照接入文档核对参数如果你还在选模型出口也可以先在模型对话里验证调用是否正常再落到 Gateway 配置里。
