1. OpenClaw 是什么为什么 Windows/MacOS 用户都在折腾 GatewayOpenClaw 是一个本地 AI 智能代理圈内人叫它小龙虾。它和普通问答式 AI 最大的区别在于它能读懂你的自然语言指令自主规划执行步骤直接操控你的电脑完成实际工作——整理文件、提取文档内容、生成表格、自动浏览网页、发送消息这些都不需要你写一行代码。适合谁三类人最值得试一是每天要处理大量重复文件操作的办公族二是想把 AI 能力接入本地工作流但不想碰复杂源码的开发者三是需要数据完全留在本机、不想上传到外部服务器的隐私敏感用户。但问题来了。很多人下载完整合包双击启动界面卡在「正在等待 Gateway 就绪...」转圈或者直接弹窗报错说配置文件缺失。Windows 上被安全软件拦截、MacOS 上权限不足导致 Gateway 启动失败这两个场景占了新手报错的八成以上。这篇就围绕 OpenClaw 在 Windows 和 MacOS 下的完整安装链路重点解决 Gateway 启动失败、配置文件缺失这两个高频问题。我会给出可复制的 config.toml 和 settings.json 骨架接入 TaoToken 统一 Key 的步骤以及逐条验证命令。目标很简单让你一次跑通本地 AI 自动操作电脑的环境。适配版本Windows OpenClaw v2.9.3、MacOS OpenClaw v2.7.9。下面所有路径和配置都基于这两个版本实测其他版本可能有差异遇到问题先确认版本号。2. 安装前必做TaoToken 前置准备与安全软件处理2.1 为什么需要 TaoTokenOpenClaw 本身是一个代理框架它需要调用大模型来理解你的指令、规划任务步骤。如果你直接对接各家模型的原生 API会面临几个麻烦每个模型的 Key 格式不同、计费方式不同、切换模型要改配置。TaoToken 的作用是提供一个统一的 API 入口你只需要一个 Key就能在 OpenClaw 里调用多种模型。具体操作访问 https://taotoken.net/api-keys 注册并创建一个 API Key。这个 Key 就是你后面填进 config.toml 的凭证。创建时建议给 Key 起个名字比如「openclaw-local」方便后续管理。拿到 Key 之后你需要确认两件事一是 Base URL 用 https://taotoken.net/api注意不要加多余的路径后缀二是 Model ID 填你实际要用的模型名称比如 claude-sonnet-4-20250514 或 gpt-4o具体以 TaoToken 文档里列出的为准。2.2 安全软件必须完全退出这是 Windows 用户部署失败的第一大原因。OpenClaw 具备文件读写、模拟键鼠、调用程序权限安全软件会把它误识别为风险程序直接隔离核心文件。你需要做的完全退出 360 安全卫士、腾讯电脑管家、火绒等防护软件不是最小化到托盘而是右键退出。同时关闭 Windows Defender 实时防护设置 → 隐私和安全性 → Windows 安全中心 → 病毒和威胁防护 → 管理设置 → 关闭实时保护。MacOS 用户相对好一些但也要注意系统设置 → 隐私与安全性 → 辅助功能确保 OpenClaw 有权限。如果之前被拦截过去「安全性与隐私」里点「仍要打开」。2.3 安装路径的硬性要求无论 Windows 还是 MacOS安装路径必须是纯英文不能有中文、空格、特殊符号。Windows 推荐 D:\OpenClawMacOS 推荐 /Users/你的用户名/OpenClaw。路径不对会直接报错终止部署这个坑我见过太多次了。另外尽量不要装到 C 盘或系统盘避免占用系统空间影响 Gateway 运行时的文件读写性能。3. 可复制配置config.toml 与 settings.json 骨架3.1 Windows 下的 config.tomlOpenClaw 安装完成后配置文件默认在安装目录的 config 文件夹下。Windows 路径示例D:\OpenClaw\config\config.toml。如果这个文件不存在说明安装过程中配置文件生成失败你需要手动创建。下面是一个可复制的最小可用骨架重点是把 TaoToken 的 Base URL 和 Key 填对[gateway] host 127.0.0.1 port 8765 auto_start true log_level info [model] provider taotoken base_url https://taotoken.net/api api_key sk-你的TaoTokenKey model_id claude-sonnet-4-20250514 timeout 120 [workspace] allowed_dirs [D:\\Downloads, D:\\Documents, C:\\Users\\你的用户名\\Desktop] max_file_size_mb 50 [security] confirm_before_execute true sandbox_mode false几个关键点base_url 必须写 https://taotoken.net/api不要加 /v1 或其他后缀api_key 替换成你在 TaoToken 控制台创建的那个model_id 填你实际要用的模型不确定就先填 claude-sonnet-4-20250514。3.2 MacOS 下的 settings.jsonMacOS 版本的配置文件格式略有不同默认路径在 ~/OpenClaw/config/settings.json。如果你找不到这个文件可以在终端执行ls -la ~/OpenClaw/config/如果目录不存在手动创建mkdir -p ~/OpenClaw/config然后创建 settings.json内容如下{ gateway: { host: 127.0.0.1, port: 8765, autoStart: true, logLevel: info }, model: { provider: taotoken, baseUrl: https://taotoken.net/api, apiKey: sk-你的TaoTokenKey, modelId: claude-sonnet-4-20250514, timeout: 120 }, workspace: { allowedDirs: [ /Users/你的用户名/Downloads, /Users/你的用户名/Documents, /Users/你的用户名/Desktop ], maxFileSizeMb: 50 }, security: { confirmBeforeExecute: true, sandboxMode: false } }注意 JSON 格式对引号和逗号很敏感多一个逗号都会导致解析失败。建议用 VS Code 编辑它会自动提示格式错误。3.3 三件套对照表不管你用哪种配置文件格式核心就三样东西缺一不可配置项Windows config.tomlMacOS settings.json值Base URLbase_urlbaseUrlhttps://taotoken.net/apiAPI Keyapi_keyapiKeysk-你的TaoTokenKeyModel IDmodel_idmodelIdclaude-sonnet-4-20250514这三项填错任何一项Gateway 都会启动失败或者请求报 401。填完之后保存文件继续下一步验证。4. 验证请求逐条命令确认 Gateway 与模型连通4.1 启动 Gateway 并检查状态Windows 下双击安装目录里的「Openclaw Windows 一键启动.exe」等待主界面出现。右上角会显示 Gateway 状态。如果显示「Gateway 在线」说明服务已启动。如果显示离线先别急打开命令行验证端口是否在监听netstat -ano | findstr 8765MacOS 下用lsof -i :8765如果没有任何输出说明 Gateway 根本没起来。这时候去看日志文件Windows 在 D:\OpenClaw\logs\gateway.logMacOS 在 ~/OpenClaw/logs/gateway.log。日志里通常会直接告诉你缺什么。4.2 用 curl 验证 TaoToken 连通性在确认 Gateway 端口监听正常后下一步验证 TaoToken 的 API 是否可达。打开终端或 PowerShell执行curl -X POST https://taotoken.net/api/v1/chat/completions \ -H Content-Type: application/json \ -H Authorization: Bearer sk-你的TaoTokenKey \ -d { model: claude-sonnet-4-20250514, messages: [{role: user, content: 回复OK}], max_tokens: 10 }如果返回 JSON 里包含 OK 或正常的 choices 字段说明 Key 和 Base URL 都没问题。如果返回 401说明 Key 填错了或者没生效如果返回 404说明 Base URL 路径不对检查是不是多加了 /v1。4.3 在 OpenClaw 界面下发测试任务Gateway 在线且 API 连通后在底部输入框输入一个简单任务测试在桌面创建一个名为 test_openclaw.txt 的文件内容写入 hello按 Enter 发送。如果 OpenClaw 能自动执行并反馈结果说明整条链路跑通了。如果卡住不动去看 Tokens 统计有没有变化没变化说明请求根本没发出去回到 4.2 检查 API 连通性。4.4 验证文件操作权限再测试一个文件整理任务将 D 盘 Downloads 文件夹里的图片按扩展名分类到不同子文件夹这个任务会触发文件读写和目录创建。如果报权限错误Windows 下检查 config.toml 里的 allowed_dirs 是否包含了 D:\DownloadsMacOS 下检查系统设置里 OpenClaw 是否有「文件和文件夹」访问权限。5. 常见报错逐条排查401、local proxy failed、reading choices、OAuth5.1 报错 401 Unauthorized这是最常见的错误意思是 TaoToken 拒绝了你的请求。原因通常有三个Key 填错、Key 被删除、Key 没有对应模型的权限。排查步骤先确认 config.toml 或 settings.json 里的 api_key 字段值是否以 sk- 开头有没有多余空格。然后去 TaoToken 控制台确认这个 Key 还在没有被禁用。最后确认 model_id 填的模型你的账号有权限调用。如果确认都没问题还是 401用 4.2 的 curl 命令单独测试排除是 OpenClaw 配置问题还是 Key 本身问题。5.2 local proxy failed这个报错通常出现在 Gateway 启动阶段意思是本地代理服务启动失败。原因一般是端口被占用。Windows 下执行netstat -ano | findstr 8765如果看到有进程占用了 8765记下 PID然后taskkill /PID 那个PID /FMacOS 下lsof -i :8765 kill -9 那个PID杀掉占用进程后重启 OpenClaw。如果不想杀进程也可以改 config.toml 里的 port 为 8766 或其他空闲端口同时确保没有其他程序用这个端口。5.3 reading choices 报错这个报错说明 OpenClaw 收到了 API 响应但解析 choices 字段时失败了。通常是因为返回的不是标准 OpenAI 格式或者模型返回了错误信息但被当成了正常响应。排查先用 curl 确认 TaoToken 返回的 JSON 结构里有没有 choices 数组。如果 curl 返回正常但 OpenClaw 报这个错检查 config.toml 里的 provider 是不是写成了 taotoken有些版本对 provider 名称敏感。另外确认 model_id 没有拼写错误。如果模型名不对TaoToken 可能返回一个错误对象而不是标准响应OpenClaw 解析时就会报 reading choices。5.4 OAuth 相关报错如果你在配置过程中看到 OAuth 字样说明你可能误触了某些需要 OAuth 授权的功能。OpenClaw 本身用 API Key 认证不需要 OAuth。检查 config.toml 里有没有多余的 auth_type 或 oauth 字段有的话删掉。如果你用的是 Claude Code 或 Codex 这类工具它们有自己的 auth.json 配置。OpenClaw 不读那个文件不要混淆。OpenClaw 只认 config.toml 或 settings.json 里的 api_key。5.5 Gateway 一直显示「正在等待 Gateway 就绪...」首次启动初始化需要 1-3 分钟这是正常的。但如果超过 5 分钟还在转说明有问题。先看日志文件。Windows 在 D:\OpenClaw\logs\gateway.logMacOS 在 ~/OpenClaw/logs/gateway.log。日志里通常会写「config file not found」或「invalid api_key」之类的具体原因。如果日志显示配置文件缺失回到第 3 节手动创建 config.toml 或 settings.json。如果日志显示端口被占用参考 5.2 处理。如果日志没有任何输出说明 Gateway 进程根本没启动检查安全软件是否拦截了。6. 跑通之后用 TaoToken 统一管理你的 OpenClaw 模型调用Gateway 在线、测试任务能执行之后你可能会想换模型试试。比如有些任务用 claude-sonnet-4-20250514 效果好有些用 gpt-4o 更合适。这时候 TaoToken 的统一 Key 优势就体现出来了你不需要为每个模型单独申请 Key、单独改配置只需要在 config.toml 里改 model_id 字段Base URL 和 API Key 保持不变。具体操作打开 config.toml把 model_id 从 claude-sonnet-4-20250514 改成 gpt-4o保存重启 Gateway。然后在界面里下发同样的任务对比执行效果。整个过程不需要动 api_key 和 base_url。如果你需要更细粒度的控制比如给不同任务分配不同模型可以在 TaoToken 控制台创建多个 Key每个 Key 绑定不同的模型权限然后在 OpenClaw 里通过切换配置文件来实现。不过对于大多数个人用户来说一个 Key 加动态改 model_id 已经够用了。另外提醒一点OpenClaw 的 Tokens 统计面板会显示每次任务的 token 消耗。如果你发现某个任务消耗异常高可能是任务描述太模糊导致模型反复规划。把任务写具体一点比如「将 D:\Downloads 里的 jpg 和 png 文件移动到 D:\Images 对应子文件夹」比「整理下载文件夹」更省 token。遇到 Gateway 启动失败或配置报错先去 https://taotoken.net/api-keys 确认 Key 状态再对照第 5 节的报错排查逐条检查。大部分问题都是 Key 填错、路径含中文、端口被占用这三类。把这三样确认一遍基本都能跑通。