★ FEATURED ARTICLE 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_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_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 在这里扮演的角色是「统一模型入口」。你不需要为每个模型厂商单独维护一套 KeyOpenClaw 里填同一个 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 URLhttps://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 和 npmnode -v npm -v两个都出版本号才算过。注意 brew 安装不需要加sudo加了反而容易把权限搞乱。3.3 Git 安装与克隆 OpenClawbrew install git git --version看到git version 2.4x.x即就绪。接着克隆项目并进入目录git clone https://github.com/openclaw/openclaw.git cd openclawcd openclaw这步不能省不进去直接npm install会找不到 package.json。然后装依赖并全局注册命令npm install npm install -g .3.4 初始化、启动网关与模型配置片段openclaw setup openclaw gatewaysetup会写出~/.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/apiKey 填控制台复制的那个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_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 需要新建或管理 Key 就去 API Keys 页面 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 接入细节和参数说明看文档 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。想先在网页里试模型效果模型对话入口在 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 里能找到。最后留一个实操建议把第 3 节的命令按顺序存成一个install-openclaw.sh把第 4 节的 curl 存成check-model.sh。下次换机器或者帮同事装两条脚本跑完就知道通没通比对着教程一步步敲稳得多。
阅读完成 · 觉得有帮助？
