1. 为什么 macOS 上装 OpenClaw 值得单独写一篇OpenClaw前身 ClawdBot / Moltbot是一款开源的本地自托管 AI 个人智能助手平台能接入 Claude、GPT、Qwen、DeepSeek 以及 Ollama 本地模型实现文件操作、终端执行、浏览器控制、定时任务等全场景自动化。如果你在 macOS 上第一次部署它会发现体验比 Windows 顺太多一条 curl 命令直接梭Homebrew、Node 都给你检测好基本不用手动处理什么。但顺不等于零坑。我在 MacBook Pro M1 Pro macOS Sequoia 15.3.2 上完整跑了一遍从 Node.js 环境准备到 Ollama 本地模型接入中间踩了几个典型坑Xcode 版本过旧导致 Skills 批量安装失败、旧配置文件残留触发 SECURITY ERROR、LaunchAgent 和手动 gateway 端口冲突。这篇就是边装边记的实战文档包含真实日志和所有踩坑点。本文适合三类人一是刚拿到 Mac 想跑本地 AI 助手的开发者二是已经在用 Ollama 但想把 OpenClaw 接进来的玩家三是想统一 Key/API 通道、把本地模型和云端模型放在一个配置里管理的用户。读完你能拿到一份可复制的openclaw.json配置片段、逐步验证动作以及常见报错的定位方法。先说清楚整体链路macOS 环境 → 安装 Node.js ≥ 22 → 一键脚本装 OpenClaw → 初始化向导选 Custom Provider 接入 Ollama → 下载本地模型 → LaunchAgent 自动启动 Gateway → Dashboard 验证。每一步我都会给出真实命令和预期输出你照着敲就行。2. TaoToken 前置统一 Key/API 通道怎么接在讲具体配置之前先解决一个很多人会卡住的问题OpenClaw 的模型接入层怎么统一管理。本地 Ollama 走http://127.0.0.1:11434/v1没问题但当你同时想用云端模型比如 Qwen、DeepSeek 的 API时每个 provider 一套 Key、一套 Base URL配置文件会变得很难维护。我的做法是用 TaoToken 作为统一通道。它的 API 地址是https://taotoken.net/api兼容 OpenAI 的chat/completions协议所以 OpenClaw 里只要按 OpenAI-compatible 的方式配就行。这样本地模型和云端模型可以共用一套配置结构切换时只改 Model ID。具体操作分三步。第一步去控制台创建 API Key访问https://taotoken.net/api-keys带 utm 参数?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentapikeys登录后点创建密钥复制生成的sk-开头的字符串。这个 Key 后面要填进 OpenClaw 的配置里。第二步确认你要用的模型 ID。TaoToken 的模型列表可以在模型对话页查看https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentmodels。常见的比如qwen3.5-9b、deepseek-r1等记下你要用的那个 ID。第三步在 OpenClaw 的初始化向导里Model/auth provider 选 Custom ProviderAPI Base URL 填https://taotoken.net/api/v1API Key 填刚才复制的sk-字符串Endpoint compatibility 选 OpenAI-compatibleModel ID 填你记下的模型 ID。这样云端通道就通了。如果你更习惯用 Coding Plan 做长期编码任务可以看https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentcodingplan它适合 Agent 类持续调用场景。接入文档在https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentdoc里面有完整的参数说明。这里要强调一点TaoToken 是合规的 API 聚合通道不是灰色中转。它的作用是让你用一个 Key 管理多个模型的调用省去每个 provider 单独配置的麻烦。本地 Ollama 和 TaoToken 云端通道可以共存配置文件里写两个 provider 就行。3. 可复制配置openclaw.json 完整片段这一节给你一份经过实战验证的openclaw.json路径是~/.openclaw/openclaw.json。这份配置同时包含本地 Ollama provider 和 TaoToken 云端 provider你可以按需删减。先看本地 Ollama 部分的配置。关键字段是baseUrl、apiKey、api和models数组{ models: { mode: merge, providers: { custom-127-0-0-1-11434: { baseUrl: http://127.0.0.1:11434/v1, apiKey: ollama, api: openai-completions, models: [ { id: qwen3.5:9b, name: Qwen3.5 9B (Local), reasoning: false, input: [text], cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 }, contextWindow: 32768, maxTokens: 8192 } ] } } } }注意apiKey填ollama是占位符本地 Ollama 不校验这个值。api字段必须是openai-completions这是 OpenClaw 识别 OpenAI 兼容协议的关键。再看 TaoToken 云端 provider 部分加在同一个providers对象里{ models: { mode: merge, providers: { taotoken-cloud: { baseUrl: https://taotoken.net/api/v1, apiKey: sk-你的实际Key, api: openai-completions, models: [ { id: qwen3.5-9b, name: Qwen3.5 9B (Cloud), reasoning: false, input: [text], cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 }, contextWindow: 32768, maxTokens: 8192 } ] } } } }然后是 agents 默认模型和 workspace 配置{ agents: { defaults: { model: { primary: custom-127-0-0-1-11434/qwen3.5:9b }, workspace: /Users/你的用户名/.openclaw/workspace, compaction: { mode: safeguard }, maxConcurrent: 4, subagents: { maxConcurrent: 8 } } } }primary字段的格式是provider-id/model-id这里指向本地 Ollama。想切云端就把custom-127-0-0-1-11434/qwen3.5:9b改成taotoken-cloud/qwen3.5-9b。最后是 gateway、hooks、channels 和 skills 部分{ session: { dmScope: per-channel-peer }, hooks: { internal: { enabled: true, entries: { bootstrap-extra-files: { enabled: true }, command-logger: { enabled: true } } } }, channels: { telegram: { enabled: false } }, gateway: { port: 18789, mode: local, bind: loopback, auth: { mode: token } }, skills: { install: { nodeManager: npm } } }把以上片段合并成一个完整的 JSON 文件保存到~/.openclaw/openclaw.json。如果你已经跑过 onboarding 向导这个文件会自动生成你只需要对照修改对应字段。改完后重启 Gateway 让配置生效launchctl unload ~/Library/LaunchAgents/ai.openclaw.gateway.plist launchctl load ~/Library/LaunchAgents/ai.openclaw.gateway.plist这里有个细节gateway.auth.mode默认是token意味着访问 Dashboard 需要带 token。本机自用可以改成none但如果你在局域网环境建议保留 token 认证因为 OpenClaw 有文件读写和终端执行权限裸奔风险不小。4. 验证请求从 Ollama 连通性到 Dashboard 成功配置写完不算完得一步步验证。我按顺序给你四个验证动作每个都有预期输出。第一个验证Ollama 服务是否在跑。执行curl http://localhost:11434预期输出是Ollama is running。如果报Connection refused说明 Ollama 没启动执行ollama serve或brew services start ollama。第二个验证本地模型是否下载成功。执行ollama list预期能看到你 pull 的模型比如NAME ID SIZE MODIFIED qwen3.5:9b abc123def456 5.8 GB 2 hours ago如果列表为空执行ollama pull qwen3.5:9b下载。16GB 内存的 Mac 建议选 9B 以下的模型32GB 以上可以上 14B 或 32B。第三个验证OpenClaw Gateway 是否正常运行。执行launchctl list | grep openclaw预期输出类似- 0 ai.openclaw.gateway第一列是 PID-表示由 launchd 管理第二列是退出码0 表示正常。然后看日志tail -f ~/.openclaw/logs/gateway.log正常运行的日志特征[gateway] agent model: custom-127-0-0-1-11434/qwen3.5:9b [gateway] listening on ws://127.0.0.1:18789 [browser/server] Browser control listening on http://127.0.0.1:18791/ [hooks] loaded 4 internal hook handlers看到listening on ws://127.0.0.1:18789就说明 Gateway 起来了。第四个验证Dashboard 能否打开。执行openclaw dashboard这个命令会自动带上 token 打开浏览器。如果你手动访问http://127.0.0.1:18789报token_missing说明 token 认证开着用命令打开就行。想查看当前 tokenopenclaw config get gateway.auth.token然后手动拼 URLopen http://127.0.0.1:18789/#token$(openclaw config get gateway.auth.token)四个验证都通过后在 Dashboard 里发一条测试消息比如你好帮我列一下当前目录文件。如果模型正常返回说明整条链路通了Dashboard → Gateway → Ollama → qwen3.5:9b。如果你配了 TaoToken 云端通道把 agents.defaults.model.primary 改成taotoken-cloud/qwen3.5-9b重启 Gateway 后再发一条消息能返回就说明云端通道也通了。这一步验证的是统一 Key/API 通道是否生效。5. 常见报错排查401、local proxy failed、reading choices这一节对照真实报错给你定位方法。我按出现频率排序。报错一401 Unauthorized如果你在日志里看到Error: 401 Unauthorized {error:{message:Invalid API key,type:invalid_request_error}}这是 Key 配置问题。分两种情况本地 Ollama 报 401检查apiKey字段是否填了ollama占位符不能空TaoToken 云端报 401检查apiKey是否是sk-开头的完整字符串有没有多余空格。用 curl 单独测一下curl https://taotoken.net/api/v1/models \ -H Authorization: Bearer sk-你的Key返回模型列表说明 Key 有效返回 401 说明 Key 本身有问题去控制台重新生成。报错二local proxy failed日志里出现Error: local proxy failed: dial tcp 127.0.0.1:11434: connect: connection refused这是 Ollama 没启动或端口不对。先确认 Ollama 在跑curl http://localhost:11434如果没返回Ollama is running执行ollama serve。如果 Ollama 跑在别的端口检查baseUrl是否写对。默认是http://127.0.0.1:11434/v1注意结尾的/v1不能少。报错三reading choices日志里出现Error: reading choices: unexpected end of JSON input这是模型返回了空响应或非 JSON 格式。常见原因有三个一是模型 ID 写错Ollama 里没有这个模型执行ollama list核对二是api字段没写openai-completionsOpenClaw 用了错误的协议解析三是模型上下文超限把contextWindow调小试试。用 curl 直接测 Ollamacurl http://localhost:11434/v1/chat/completions \ -H Content-Type: application/json \ -d {model:qwen3.5:9b,messages:[{role:user,content:hi}]}能返回正常 JSON 说明 Ollama 侧没问题问题在 OpenClaw 配置。报错四OAuth 相关如果你在 onboarding 时选了内置的 OAuth provider比如某些需要浏览器授权的日志里可能出现Error: OAuth callback failed: timeout本地模型场景不需要 OAuth选 Custom Provider 就行。如果已经配了 OAuth provider 想删掉编辑openclaw.json把对应 provider 块删掉或者重新跑openclaw onboard选 Use existing values 让它自动修复。报错五Xcode too outdatedSkills 安装时报Install failed: apple-notes (exit 1) — Error: Your Xcode (14.3.1) is too outdated. Please update to Xcode 16.4这是 macOS 特有问题。Xcode 14.x 无法编译新版 Homebrew 公式。解决方案去 App Store 更新 Xcode 到 16.4或者忽略不影响主程序聊天功能。实测以下 Skills 在 Xcode 14.3.1 下无需更新即可安装1password、bear-notes、blogwatcher、blucli、clawhub、eightctl、github、himalaya、mcporter、model-usage、nano-banana-pro、nano-pdf、openai-whisper、oracle、sonoscli、things-mac、xurl。报错六SECURITY ERROR: Gateway URL uses plaintext ws://Error: SECURITY ERROR: Gateway URL ws://openclaw.local:18789 uses plaintext ws:// to a non-loopback address.旧配置文件残留了gateway.mode: remote加非本地地址。执行openclaw config set gateway.mode local openclaw config set gateway.bind loopback或者重新跑openclaw onboard选 Use existing values 自动修复。报错七端口冲突Error: listen tcp 127.0.0.1:18789: bind: address already in useLaunchAgent 已经启动了 Gateway你又手动跑了openclaw gateway。macOS 上不需要手动启动LaunchAgent 管好了。检查状态launchctl list | grep openclaw如果确实需要手动重启先 unload 再 load。6. 把本地模型和统一通道用起来配置跑通之后你手里其实有了两套模型通道本地 Ollama 走http://127.0.0.1:11434/v1完全离线、零成本TaoToken 云端走https://taotoken.net/api/v1一个 Key 管多个模型。切换方式就是改agents.defaults.model.primary字段重启 Gateway 生效。我自己的用法是日常文件整理、终端命令执行这类隐私敏感任务走本地 qwen3.5:9b需要更强推理或长上下文时切到云端通道。两套配置在同一个openclaw.json里不用来回改环境变量。如果你想把云端通道的 Key 管理得更规范建议去控制台按用途创建多个 Key比如一个给 OpenClaw 专用一个给其他工具用。接入文档里有完整的参数说明和示例遇到协议兼容问题可以先查文档再排查。最后留一个实用技巧openclaw doctor是排查配置问题的第一入口它会检查 Node 版本、依赖完整性、配置文件合法性、Gateway 状态等。遇到任何异常先跑一遍openclaw doctor --verbose输出里会直接告诉你哪一项不通过、怎么修。我踩的坑里有一半是靠这个命令定位的。