1. OpenClaw 本地 Agent 为什么总卡在 Gateway 离线OpenClaw 是一个能在本机跑起来的开源 AI Agent接收自然语言指令后自动拆解任务完成文件整理、网页检索、文档汇总这类操作。它和普通聊天机器人的区别在于聊天机器人只输出文字OpenClaw 会真的去动你的文件系统、开浏览器、调本地服务。适合谁适合想把重复办公流程交给本地程序、又不想把内部资料传到云端的 Windows / macOS 开发者。但真正上手时两个故障几乎人人都会撞上一是界面右上角一直显示 Gateway 离线任务发不出去二是安装或运行时报「路径包含中文」程序直接拒绝启动。这两个问题看着吓人其实根因都很具体——Gateway 离线多半是本地服务没起来或端口被占中文路径报错则是 OpenClaw 内部调用子进程时对非 ASCII 路径处理不完善。这篇按「先接通道、再修路径、最后验连通」的顺序走一遍交付可复制的 config.toml 与 settings.json 骨架、TaoToken 统一 Key 接入步骤以及 Gateway 连通性验证和中文路径修复的逐条命令。全程命令可直接粘贴Windows 用 PowerShellmacOS 用终端。2. 接入前的准备TaoToken 统一 Key 与 API 通道OpenClaw 本身是 Agent 框架它需要一个大模型通道来驱动推理。与其在本地分别配多家模型的 Key不如用一个统一入口把模型对话、编码、Agent 调用都收敛到同一套凭证上配置量能少一大半。TaoToken 在这里扮演的就是这个统一通道一个 Key 覆盖多种模型调用OpenClaw 的 config.toml 里只填一个 base_url 和一个 api_key 即可。对本地 Agent 场景来说好处是切换模型不用改代码排障时也只需检查一个通道是否通。先拿 Key。打开控制台页面登录后在 API Keys 里新建一个密钥复制出来只显示一次务必存好https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite如果你后面要跑长期编码任务或 Agent 常驻建议直接看 Coding Plan额度模型更适合高频调用https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite接入文档在这里config.toml 的字段含义、可用模型名都以文档为准https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewriteAPI 基地址统一用https://taotoken.net/api注意这个地址不带任何查询参数直接写进配置即可。Key 拿到后先别急着填进 OpenClaw下一步我们先确认通道本身是通的避免把「通道问题」误判成「Gateway 问题」。3. 可复制的 config.toml 与 settings.json 骨架OpenClaw 的配置分两层config.toml管模型通道和 Gateway 参数settings.json管界面与运行行为。下面两份骨架可以直接复制把api_key换成你自己的即可。先看config.toml。放在 OpenClaw 安装目录下的config文件夹里Windows 示例D:\OpenClaw\config\config.tomlmacOS 示例~/OpenClaw/config/config.toml# OpenClaw 主配置 —— TaoToken 统一通道版 [gateway] host 127.0.0.1 port 8765 # 关键Gateway 必须绑定回环地址不要写 0.0.0.0 auto_start true startup_timeout 180 # 首次初始化给足 3 分钟 [model] provider openai-compatible base_url https://taotoken.net/api api_key sk-你的TaoToken密钥 model_name claude-sonnet-4-5 timeout 120 max_retries 3 [agent] workspace D:/OpenClaw/workspace # 必须纯英文正斜杠更稳 language zh-CN log_level info [security] allow_file_write true allow_browser_control true再看settings.json放在安装目录根下{ gateway: { autoReconnect: true, reconnectIntervalMs: 3000, healthCheckPath: /health }, ui: { showGatewayStatus: true, defaultMode: auto }, paths: { workspace: D:/OpenClaw/workspace, temp: D:/OpenClaw/temp, logs: D:/OpenClaw/logs }, model: { stream: true, temperature: 0.3 } }两个文件里所有路径字段都写成纯英文、用正斜杠/。这是后面修中文路径报错的第一道防线——配置层先杜绝中文运行层再兜底。注意workspace、temp、logs三个目录要提前手动建好OpenClaw 不会自动创建父级目录缺目录会表现为 Gateway 启动后立刻退出。4. Gateway 连通性验证与中文路径修复逐条命令配置填完先别开界面用命令行把 Gateway 拉起来看日志问题会暴露得更清楚。4.1 手动启动 Gateway 并观察日志Windows PowerShellcd D:\OpenClaw .\openclaw-gateway.exe --config .\config\config.toml --log-level debugmacOS 终端cd ~/OpenClaw ./openclaw-gateway --config ./config/config.toml --log-level debug正常启动会看到类似输出[gateway] listening on 127.0.0.1:8765 [gateway] model channel ready: https://taotoken.net/api [gateway] health endpoint: http://127.0.0.1:8765/health如果卡在initializing...超过 3 分钟或者直接exit code 1往下看排障。4.2 验证 Gateway 是否真的在线另开一个终端请求健康检查接口curl -s http://127.0.0.1:8765/health返回{status:ok,model:connected}说明 Gateway 和模型通道都通了。如果返回connection refused说明 Gateway 没起来如果返回{status:ok,model:disconnected}说明 Gateway 起来了但 TaoToken 通道没通重点查 api_key 和 base_url。4.3 中文路径报错的定位与修复中文路径报错的典型日志长这样[error] failed to spawn subprocess: path contains non-ASCII characters [error] workspace resolve failed: D:\工具\OpenClaw\workspace修复分三步。第一步确认当前工作目录没有中文# Windows Get-Location # 如果输出含中文立刻切走 cd D:\OpenClaw# macOS pwd cd ~/OpenClaw第二步检查配置里所有路径字段。用命令扫一遍 config.toml 和 settings.json 里有没有非 ASCII 字符grep -nP [^\x00-\x7F] config/config.toml settings.json有输出就说明还有中文残留逐行改掉。第三步如果安装目录本身就在中文路径下比如D:\工具\OpenClaw最彻底的办法是整体迁移到纯英文路径# Windows先停掉所有 OpenClaw 进程再迁移 Stop-Process -Name openclaw* -Force -ErrorAction SilentlyContinue Move-Item D:\工具\OpenClaw D:\OpenClaw# macOS pkill -f openclaw mv ~/工具/OpenClaw ~/OpenClaw迁移后记得同步改 config.toml 和 settings.json 里的绝对路径再重新启动 Gateway。4.4 端口被占导致 Gateway 离线的处理如果日志报bind: address already in use说明 8765 被别的程序占了。查占用进程# Windows netstat -ano | findstr :8765# macOS lsof -i :8765拿到 PID 后结束它或者把 config.toml 里的port改成 8766 之类的空闲端口同时 settings.json 不用改它走的是相对健康检查路径。5. 本篇常见错排查Q1Gateway 显示在线但发指令没反应。先看日志有没有model channel timeout。多半是 TaoToken 通道超时把 config.toml 里timeout从 120 调到 180max_retries调到 3。再确认base_url写的是https://taotoken.net/api没有多余斜杠或参数。Q2改了 config.toml 但行为没变。OpenClaw 只在启动时读配置改完必须重启 Gateway。界面上点重启按钮或者命令行CtrlC后重新拉起。Q3中文路径改完了还报错。检查环境变量。Windows 下TEMP、TMP如果指向含中文的目录子进程照样会挂。临时改法$env:TEMP D:\OpenClaw\temp $env:TMP D:\OpenClaw\temp然后从同一个终端启动 Gateway。Q4macOS 上 Gateway 启动即退出日志为空。大概率是权限问题。给可执行文件加执行权限chmod x ~/OpenClaw/openclaw-gateway再检查~/OpenClaw/logs目录是否可写。Q5想确认模型通道到底通不通不想开 OpenClaw。直接用 curl 打一次模型对话接口比在界面里试快得多curl -s https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer sk-你的TaoToken密钥 \ -H Content-Type: application/json \ -d {model:claude-sonnet-4-5,messages:[{role:user,content:ping}]}返回带choices字段就说明通道没问题问题一定在 OpenClaw 本地配置或 Gateway 上。想直接在网页里验证模型是否可用用模型对话页面最快https://taotoken.net/model-chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel-chatutm_campaignrewrite6. 把通道和路径一次配到位整套流程走下来核心就两件事通道收敛到一个 base_url 加一个 Key路径全部锁死在纯英文目录。Gateway 离线九成是端口或启动超时中文路径报错九成是配置或环境变量里还有非 ASCII 字符。把这两类根因分开查比反复重装快得多。如果你在跑长期编码或常驻 Agent建议把 Key 换成 Coding Plan 的额度模型避免高频调用时额度不够中断任务https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite需要新建或轮换 Key 时回到控制台https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite配置字段拿不准就翻接入文档config.toml 每个字段都有说明https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite最后留一个我踩过的坑迁移安装目录后桌面快捷方式还指向旧路径双击启动的是旧目录里的程序配置改了也不生效。迁移完记得重建快捷方式或者直接从新目录的命令行启动省得排查半天发现是快捷方式在捣乱。