1. 先搞清楚 OpenClaw 是什么，以及 macOS 上为什么会卡在安装这一步

OpenClaw 是一个跑在本地的自动化 Agent 网关，社区里习惯叫它「小龙虾」。它能做什么？简单说，你把大模型的 Key 配给它，它就能在本地起一个 Dashboard，通过浏览器对话、挂工具、跑自动化任务，所有会话和配置都落在你自己的机器上。适合谁？适合想在 macOS 上折腾本地 Agent、又不想把 Key 和对话内容散落在各种第三方面板里的开发者。

但 macOS 上装 OpenClaw，卡人的地方往往不是 OpenClaw 本身，而是它脚下那三层地基：Homebrew、Node.js、Git。我见过太多人在这三步里反复横跳——Homebrew 装到一半 curl 超时，Node.js 版本停在 18 结果npm install直接编译失败，Git 没装导致git clone报xcrun: error。这些报错单独看都不难，但叠在一起就很容易让人放弃。

这篇教程的目标很明确：从零开始，把 macOS 上的环境准备、OpenClaw 克隆、依赖安装、网关启动、模型接入一条线走完，每一步都给可复制的终端命令和验证动作。同时，模型这一层我会用 TaoToken 的统一 Key 来接，这样你不需要在 MiniMax、Claude、GPT 之间来回注册，一个 Base URL 加一个 Key 就能把 OpenClaw 的模型通道打通。官网入口在 https://taotoken.net/?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= ，API 地址是 https://taotoken.net/api ，后面配置里会反复用到。

先对齐一下机器条件：磁盘预留 5GB 以上，Node.js 必须 22 或更高（低于 22 会在编译阶段崩），终端用系统自带的 Terminal 就行。网络方面，GitHub 和 npm 官方源在国内偶尔会慢，遇到超时优先换源或重试，不要一上来就怀疑命令写错。

2. 装 OpenClaw 之前，先把 TaoToken 的 Key 和模型 ID 拿到手

很多人习惯先把 OpenClaw 装完再想模型的事，结果装到openclaw agents add main那一步才发现手里没有可用的 Key，又回头折腾。我的建议是反着来：先把 TaoToken 的 Key 和要用的 Model ID 准备好，装完直接填，一次跑通。

TaoToken 在这里扮演的角色是「统一模型入口」。你不需要为每个模型厂商单独维护一套 Key，OpenClaw 里填同一个 Base URL 和同一个 Key，通过 Model ID 切换具体模型。对 OpenClaw 这种需要频繁改模型配置的工具来说，这一点很省事。

操作路径是这样的：打开 https://taotoken.net/api ，进入控制台后找到 API Keys 页面，新建一个 Key 并复制保存。这个 Key 只显示一次，丢了只能重建，所以复制完先贴到你的密码管理器或临时文本里。接着在文档页确认你要用的 Model ID，比如你想用 Claude 系列就记下对应的模型标识，想用别的系列同理。Model ID 是区分大小写的，抄错一个字符就会在请求阶段报模型不存在。

这里有个细节值得提前说：OpenClaw 的模型配置最终会落到~/.openclaw/openclaw.json这个文件里，里面记录的是 provider、baseUrl、apiKey、model 这几项。你在终端向导里填的内容，本质上就是在写这个 JSON。所以如果你后面想批量改或者备份配置，直接看这个文件就行，不用重新跑一遍向导。

把这三样东西准备好：Base URL（https://taotoken.net/api）、API Key、Model ID。接下来进入安装流程，装完就能直接填。

3. 可复制配置：Homebrew、Node.js、Git 到 OpenClaw 的完整命令链

这一节是全文的操作核心，命令按顺序贴，你从终端第一条开始执行即可。每一步后面都跟了验证命令，验证不过就别往下走，否则错误会累积。

3.1 Homebrew 安装与 PATH 配置

Homebrew 是 macOS 的包管理器，后面装 Node.js 和 Git 都靠它。执行官方安装脚本：

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

中途会提示Press RETURN/ENTER to continue，直接回车。如果卡在curl: (56) Recv failure: Operation timed out，说明到 GitHub 的链路不稳，换时间段重试通常能过，不必改命令。

装完后 Apple Silicon 机器需要把 brew 写进 PATH，两条命令依次执行：

echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zprofile eval "$(/opt/homebrew/bin/brew shellenv)"

验证：

brew --version

看到Homebrew 4.x.x或更高版本号即通过。如果提示command not found: brew，说明 PATH 没生效，关掉终端重开一个窗口再试。

3.2 Node.js 22+ 安装与版本校验

先看现状：

node -v

输出v22.x.x或更高就跳过安装；低于 22 或提示 command not found，执行：

brew install node

装完如果node -v还是旧版本，是旧路径优先级更高，强制刷新软链：

brew link --overwrite node

再验证 Node 和 npm：

node -v npm -v

两个都出版本号才算过。注意 brew 安装不需要加sudo，加了反而容易把权限搞乱。

3.3 Git 安装与克隆 OpenClaw

brew install git git --version

看到git version 2.4x.x即就绪。接着克隆项目并进入目录：

git clone https://github.com/openclaw/openclaw.git cd openclaw

cd openclaw这步不能省，不进去直接npm install会找不到 package.json。然后装依赖并全局注册命令：

npm install npm install -g .

3.4 初始化、启动网关与模型配置片段

openclaw setup openclaw gateway

setup会写出~/.openclaw/openclaw.json并确认 workspace 和 sessions 目录。gateway首次启动要构建 UI，等几分钟，期间浏览器报ERR_CONNECTION_REFUSED是正常的，别急着杀进程。

模型配置用终端向导：

openclaw agents add main

按提示选 Yes 更新、确认工作目录、选择配置模型。到 provider 列表时选你准备好的那项，粘贴 API Key。如果你想让配置直接落到 JSON 里，可以手动编辑~/.openclaw/openclaw.json，结构大致如下（字段名以你本地实际生成的为准）：

{ "agents": { "main": { "provider": "taotoken", "baseUrl": "https://taotoken.net/api", "apiKey": "sk-你的Key", "model": "你的ModelID" } } }

三件套对齐：Base URL 填https://taotoken.net/api，Key 填控制台复制的那个，Model ID 填文档里确认过的标识。改完 JSON 后重启openclaw gateway让配置生效。

4. 验证请求：从 Dashboard 到模型回包，确认整条链路真的通了

装完不等于通了，必须做验证。验证分三层，一层层往上确认，哪层断了就停在哪层排查。

第一层，网关进程是否活着。openclaw gateway跑起来后，另开一个终端窗口执行：

openclaw dashboard

浏览器会自动打开http://127.0.0.1:18789。如果页面能加载出对话界面，说明网关和 UI 都正常。页面打不开先看 gateway 窗口有没有报错退出，再看端口是否被占用。

第二层，模型配置是否被识别。在 Dashboard 对话框里直接问一句「你现在用的是哪个模型」。正常情况它会回你配置的 Model ID 对应的模型名。如果它回「未配置模型」或者报错，说明openclaw.json里的 provider、baseUrl、apiKey、model 有一项没对上，回到第 3.4 节逐项核对。

第三层，请求是否真的打到了 TaoToken。这一步用 curl 单独验证，绕开 OpenClaw，直接测 Key 和 Base URL 是否可用：

curl https://taotoken.net/api/v1/chat/completions \ -H "Authorization: Bearer sk-你的Key" \ -H "Content-Type: application/json" \ -d '{ "model": "你的ModelID", "messages": [{"role": "user", "content": "ping"}] }'

返回体里出现choices数组和一段回复内容，说明 Key、Base URL、Model ID 三者都对。如果这里就报 401，问题在 Key；报模型不存在，问题在 Model ID；报连接失败，问题在 Base URL 或网络。curl 通了但 Dashboard 不通，问题就锁定在 OpenClaw 的配置读取上，而不是账号侧。

三层都过，才算真正「一次跑通」。我建议把第三层的 curl 命令存成一个脚本，以后换 Key 或换模型时先跑它，能快速区分是账号问题还是本地配置问题。

5. 本篇常见错排查：401、local proxy failed、reading choices、OAuth 逐个对照

装 OpenClaw 过程中会撞上的报错其实就那么几类，下面按真实报错原文对照给处理方式。

401 Unauthorized或返回体里带invalid api key。这是 Key 的问题，不是网络问题。检查三处：Key 是否复制完整（首尾有没有漏字符）、请求头是否是Authorization: Bearer sk-xxx格式、这个 Key 是否在控制台被禁用或删除。用第 4 节的 curl 单独测，能最快定位。

local proxy failed或ECONNREFUSED 127.0.0.1:xxxx。这类报错说明 OpenClaw 在尝试连一个本地端口但没连上，常见于 gateway 没启动就去开 dashboard，或者 gateway 启动到一半崩了。处理顺序：先看 gateway 窗口的最后几行输出，确认进程还在；再确认 dashboard 用的端口和 gateway 监听端口一致；最后检查是否有别的程序占了 18789。

Cannot read properties of undefined (reading 'choices')。这个报错的意思是代码在解析响应时找不到choices字段，通常有两种原因：一是 Base URL 填错，请求打到了一个返回 HTML 或错误 JSON 的地址；二是 Model ID 不被识别，服务端返回了错误结构。核对baseUrl是否精确到https://taotoken.net/api，以及 model 字段是否和文档一致。用 curl 看原始返回体，比在 UI 里猜快得多。

OAuth 相关报错，比如OAuth token expired或引导流程反复要求登录。OpenClaw 某些 provider 走 OAuth 流程，如果你在向导里选了需要 OAuth 的选项又没走完授权，配置会处于半成品状态。处理方式是重新跑openclaw agents add main，在 provider 选择时明确选 API Key 方式而不是 OAuth 方式，然后重新粘贴 Key。已经写坏的配置可以直接编辑~/.openclaw/openclaw.json修正，改完重启 gateway。

zsh: command not found: openclaw。全局注册没成功，回到项目目录执行npm install -g .，确认没有报权限错误。如果报EACCES，不要用 sudo 硬上，检查 npm 全局目录权限，或者用npm config get prefix看前缀是否在用户目录下。

npm install阶段编译失败，报node-gyp或Python相关错误。九成是 Node.js 版本低于 22，回到 3.2 节升级。少数是 Xcode Command Line Tools 损坏，执行xcode-select --install重装开发工具后再试。

6. 装完之后：把 Key 管好，把配置备份好

OpenClaw 装好只是起点，日常用起来还有两个习惯值得养成。一是 Key 不要写死在会提交到 Git 的文件里，~/.openclaw/openclaw.json在用户目录下相对安全，但如果你把配置同步到云盘或仓库，记得先脱敏。二是每次改完模型配置，先跑一遍第 4 节的 curl，再开 Dashboard，这样能把账号问题和本地问题分开，排障时间至少省一半。

如果你后面要长期跑编码类或 Agent 类任务，可以了解下 TaoToken 的 Coding Plan，入口在 https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= ；需要新建或管理 Key 就去 API Keys 页面 https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= ；接入细节和参数说明看文档 https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= 。想先在网页里试模型效果，模型对话入口在 https://taotoken.net/?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= 里能找到。

最后留一个实操建议：把第 3 节的命令按顺序存成一个install-openclaw.sh，把第 4 节的 curl 存成check-model.sh。下次换机器或者帮同事装，两条脚本跑完就知道通没通，比对着教程一步步敲稳得多。