Mac 上 2026 版 OpenClaw 安装与配置全流程：TaoToken 统一 Key 接入 settings.json 骨架

1. Mac 上跑 OpenClaw为什么卡在配置这一步OpenClaw 是一个开源本地 AI 执行引擎能在你的 Mac 上直接操作文件、执行终端命令、控制浏览器把「对话」变成「动手干活」。它适合想在本机搭一套自动化助手的开发者、运维和效率玩家尤其是习惯用命令行、又不想把数据全丢到云端的人。2026 版对 Apple Silicon 做了原生适配M 系列芯片跑起来比 Intel 机器更顺但真正让人卡住的往往不是安装而是装完之后那一步模型通道怎么接、Key 往哪写、settings.json 骨架长什么样。我自己在 M2 的 MacBook 上从零走了一遍Homebrew、Node.js、OpenClaw 本体都算顺利反倒是首次启动的 Onboarding 向导里模型供应商和 API Key 那几屏最容易让人反复重来。默认向导会引导你选某个云厂商、粘贴对应 Key但如果你手上已经有 TaoToken 的统一 Key就没必要被单一供应商绑住——把通道统一到 TaoToken之后换模型只改一个字段不用重新走一遍向导。这篇就按「Mac 环境 → 依赖 → 安装 → TaoToken 统一 Key 写入 settings.json → 连通性验证 → 排障」的顺序走一遍重点交付一份可直接复制的 settings.json 骨架以及一条最小请求验证命令。你照着做能在本地把 OpenClaw 接入流程完整跑通。2. 前置准备TaoToken 统一 Key 与 Mac 依赖2.1 先拿到 TaoToken 的 Key 和通道地址TaoToken 在这里扮演的角色是「统一入口」你不需要为每个模型单独申请 Key也不用在 OpenClaw 里配一堆供应商。先去控制台创建一个 API Key再确认两件事——API 基地址和你要用的模型名。官网入口https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentAPI 基地址https://taotoken.net/api创建 Keyhttps://taotoken.net/console/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewriteKey 一般以固定前缀开头创建后只显示一次复制到本地临时文件或密码管理器里。注意 API 基地址不要带 UTM 参数写进配置的就是干净的https://taotoken.net/api。2.2 Mac 侧依赖检查OpenClaw 2026 版要求 Node.js ≥ 22.0.0Homebrew 用来装 Node 和后续工具。先开终端Command 空格搜「终端」逐条确认# 系统版本需 macOS 12.0 sw_vers # 芯片架构arm64 为 Apple Silicon uname -m # Homebrew 是否已装 brew --version # Node 版本需 ≥ 22 node -v npm -v如果brew报 command not found先装 Homebrew/bin/bash -c $(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)Apple Silicon 装完 Homebrew 后按提示把/opt/homebrew/bin加进 PATH否则新终端里还是找不到 brew。这一步别跳过后面 Node 装不上多半是这里没配好。3. 安装 OpenClaw 与 Node.js 依赖3.1 用 Homebrew 装 Node 22brew install node22 # 让 node22 优先于系统里可能存在的旧版本 echo export PATH/opt/homebrew/opt/node22/bin:$PATH ~/.zshrc source ~/.zshrc # 复核 node -v # 期望 v22.x.x npm -v如果你机器上已经有别的 Node 版本node -v还是旧号说明 PATH 顺序不对。用which node看它指向哪确保指向/opt/homebrew/opt/node22/bin/node。3.2 全局安装 OpenClawnpm install -g openclawlatest # 验证 openclaw --version输出类似OpenClaw 2026.x.x就说明本体装好了。如果 npm 全局目录权限报错别急着sudo先修权限更干净sudo chown -R $(whoami) $(npm config get prefix)/{lib/node_modules,bin,share}3.3 首次启动会生成配置目录第一次执行openclaw会进入 Onboarding 向导同时在家目录生成配置目录~/.openclaw。向导里模型供应商那几屏你可以先随便选一个跳过或者直接 CtrlC 退出——因为我们接下来要手动写 settings.json把通道统一到 TaoToken比在向导里逐屏选更可控。# 确认配置目录已生成 ls -la ~/.openclaw4. 可复制配置settings.json 骨架写入 TaoToken4.1 配置文件位置与结构OpenClaw 的主配置在~/.openclaw/settings.json。如果向导已经生成过一份先备份再改cp ~/.openclaw/settings.json ~/.openclaw/settings.json.bak下面这份骨架把模型通道指向 TaoTokenbaseUrl用干净的 API 地址apiKey建议用环境变量引用而不是硬编码明文。你可以直接复制把model换成你在 TaoToken 控制台确认可用的模型名。{ gateway: { port: 18789, host: 127.0.0.1 }, providers: { taotoken: { type: openai-compatible, baseUrl: https://taotoken.net/api, apiKey: ${TAOTOKEN_API_KEY}, models: { default: your-model-name } } }, agent: { defaultProvider: taotoken, defaultModel: your-model-name }, skills: { enabled: [apple-reminders, apple-notes, github] }, hooks: { boot-md: true, session-memory: true } }几个字段说明一下避免你改错字段作用注意providers.taotoken.type声明兼容 OpenAI 协议保持openai-compatiblebaseUrl请求基地址写https://taotoken.net/api不带 UTMapiKey鉴权用${TAOTOKEN_API_KEY}引用环境变量defaultProvider默认走哪个通道填taotokendefaultModel默认模型名换成控制台里确认可用的名字注意apiKey直接写明文也能跑但配置文件容易被同步或备份用环境变量引用更稳妥。下面就把 Key 写进 shell 环境。4.2 把 Key 写进环境变量Zsh 是 Mac 默认 shell编辑~/.zshrcecho export TAOTOKEN_API_KEY你的Key ~/.zshrc source ~/.zshrc # 确认已生效只回显前几位避免整串泄露 echo ${TAOTOKEN_API_KEY:0:6}如果你用的是 Bash改~/.bash_profile并source它。环境变量没生效的话OpenClaw 启动时会因为解析不到${TAOTOKEN_API_KEY}而报鉴权失败这是后面排障里最常见的一类。4.3 校验 JSON 语法手写 JSON 最容易多一个逗号或少一个引号。改完先校验python3 -m json.tool ~/.openclaw/settings.json /dev/null echo JSON OK输出JSON OK再往下走。语法不过关的话OpenClaw 启动会直接报解析错误连网关都起不来。5. 验证请求启动网关并跑一次最小调用5.1 启动 OpenClaw# 前台启动方便看日志 openclaw start前台模式会把网关日志打在终端里你能直接看到它监听127.0.0.1:18789、加载了哪些 skills、有没有报 provider 错误。确认没问题后另开一个终端窗口做验证或者用后台模式openclaw start --detach openclaw status5.2 用 curl 打一次最小请求网关起来后先不急着进 TUI用一条 curl 确认 TaoToken 通道真的通。这一步能把你和「配置写错」快速区分开curl -s https://taotoken.net/api/chat/completions \ -H Authorization: Bearer ${TAOTOKEN_API_KEY} \ -H Content-Type: application/json \ -d { model: your-model-name, messages: [{role: user, content: ping}], max_tokens: 16 }返回里带choices字段、内容非空就说明 Key 和通道都没问题。如果这里就报 401问题在 Key 或环境变量如果报模型不存在问题在model名字回去核对控制台。5.3 在 OpenClaw 里发一条真实指令curl 通了之后回到 OpenClaw 交互界面验证端到端openclaw进入 TUI 后输入一句简单指令比如「列出当前目录下的文件」。如果它能调用终端技能并返回结果说明 settings.json 里的 provider、model、skills 全部串起来了。你也可以打开 Web UI 看可视化日志open http://localhost:18789Web 界面里能看到每次请求走的 provider、耗时和返回排查时比翻终端日志直观。6. 本篇常见错排查6.1 command not found: openclaw装完新终端里找不到命令多半是 npm 全局 bin 目录不在 PATH。先source ~/.zshrc再不行手动加echo export PATH$HOME/.local/bin:$PATH ~/.zshrc source ~/.zshrc还不行就npm config get prefix看全局目录把它的bin加进 PATH。6.2 鉴权失败 / 401按顺序查三件事echo ${TAOTOKEN_API_KEY:0:6}看环境变量是否为空settings.json 里是不是写成了${TAOTOKEN_API_KEY}而不是别的变量名Key 有没有复制时带上多余空格。环境变量改了之后一定要source或重开终端否则 OpenClaw 读到的还是旧值。6.3 JSON 解析报错用python3 -m json.tool ~/.openclaw/settings.json定位。常见是末尾多逗号、字符串用了中文引号、或者注释没删干净标准 JSON 不支持注释。改完再校验一次。6.4 模型名不存在model字段必须和 TaoToken 控制台里确认可用的名字完全一致大小写、连字符都不能差。curl 那条命令报的错和 OpenClaw 里报的错如果一致基本就是模型名的问题。6.5 端口 18789 被占用lsof -i :18789有进程占用就 kill 掉或者改 settings.json 里gateway.port换一个端口重启 OpenClaw 生效。6.6 Node 版本过低openclaw --version报 Node 版本不满足说明 PATH 里还是旧 Node。which node确认指向 node22不对就重配 PATH 并source。排障时如果卡在 Key 或通道配置直接去 API Keys 页面重新核对https://taotoken.net/console/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite 接入细节和字段说明看文档https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 。想先确认某个模型能不能用可以在模型对话里试一句https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentchatutm_campaignrewrite 。如果你打算长期跑编码或 Agent 任务Coding Plan 更省心https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite 。最后留一个我踩过的坑改完 settings.json 一定要重启 OpenClaw热加载不一定生效openclaw stop再openclaw start最稳。