1. 为什么要在 Mac 上折腾 openclaw 小龙虾openclaw 小龙虾是一个跑在本地的 AI 助手框架你可以把它理解成一个「自己家的智能中枢」它负责接收你的指令、调用大模型、再把结果整理成对话或任务输出。和直接用网页版对话不同本地部署的好处是配置、密钥、日志都在你自己机器上想接哪个模型通道就接哪个适合喜欢折腾、又想把 AI 能力沉淀到本地的开发者。这篇手册聚焦 Mac 电脑版的完整部署路径从环境准备一路走到启动验证重点解决一个高频痛点模型通道怎么统一接。很多人卡在「每个模型都要单独配 Key、单独改 base_url」这一步配置一多就乱。我的做法是用 TaoToken 统一 Key 接入把模型通道收敛到一处再在 openclaw 的 config.toml 里写一份可复制的配置骨架。这样你换模型时只改一个字段不用满仓库找密钥。适合谁看刚拿到 Mac、想跑通第一个本地 AI 服务的同学已经装过 Node 但被 config 文件劝退的同学以及想把 openclaw 接进自己工作流、需要稳定 API 通道的同学。全程命令可直接复制配置片段可直接粘贴遇到报错对照第 5 节排查即可。2. 前置准备TaoToken 统一 Key 与 Mac 环境2.1 先拿到统一 Key别急着装 openclawopenclaw 本身只是「壳」真正干活的是背后的大模型通道。如果你打算接多个模型最省事的做法是先用一个统一入口把 Key 管起来。TaoToken 提供的就是这种统一 Key / API 通道能力你申请一个 Key就能在配置里切换不同模型而不用为每个厂商单独维护一套密钥。申请入口在官网注册后进控制台创建 API Key 即可官网地址https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content控制台创建 Keyhttps://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewriteAPI Keys 管理页https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite拿到 Key 之后先别关页面后面 config.toml 里要填。API 的基础地址是https://taotoken.net/api注意这个地址不带任何查询参数配置时原样写进去就行。提示Key 只显示一次的情况很常见创建后立刻复制到本地密码管理器或临时文本里别等配置到一半再回去找。2.2 Mac 侧环境三件套openclaw 依赖 Node.js 运行Git 用来拉依赖Homebrew 负责装前两者。按顺序来第一步装 Homebrew。终端执行官方脚本中途会让你输入开机密码/bin/bash -c $(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)Apple SiliconM 系列装完后要把 brew 加进 PATHecho eval $(/opt/homebrew/bin/brew shellenv) ~/.zprofile eval $(/opt/homebrew/bin/brew shellenv)Intel 芯片则用/usr/local/bin/brew路径。验证brew -v第二步装 Node.js 的 LTS 版本。别装最新尝鲜版兼容性坑多brew install node20 echo export PATH/opt/homebrew/opt/node20/bin:$PATH ~/.zshrc source ~/.zshrc node -v npm -v第三步装 Git 并做一条关键配置。openclaw 拉依赖时如果走 SSH 容易报 code 128提前把 GitHub 访问改成 HTTPSbrew install git git config --global url.https://github.com/.insteadOf gitgithub.com: git --version到这里环境就绪。四个命令brew -v、node -v、npm -v、git --version都能出版本号再往下走。3. 可复制配置openclaw 安装与 config.toml 骨架3.1 安装 openclaw 本体先把 npm 源切到国内镜像装依赖会快很多npm config set registry https://registry.npmmirror.com npm install -g openclawlatest openclaw -v这里有一条红线不要加 sudo。加了 sudo 之后 npm 全局目录权限会变成 root后续启动服务会报 EACCES修复起来很烦。如果之前不小心用过 sudo先执行sudo chown -R $(whoami) ~/.npm sudo chown -R $(whoami) /usr/local/lib/node_modules3.2 初始化并找到 config.toml执行初始化向导一路回车用默认值即可端口默认 9000openclaw init初始化完成后配置文件默认落在~/.openclaw/config.toml。用编辑器打开open ~/.openclaw/config.toml3.3 config.toml 配置骨架接 TaoToken 统一 Key下面这份骨架可以直接复制把api_key换成你自己的即可。核心思路是把模型通道统一指向 TaoToken 的 API 地址模型名按需切换# ~/.openclaw/config.toml # openclaw 小龙虾 Mac 本地部署配置骨架 [server] host 127.0.0.1 port 9000 log_level info [auth] username admin password 改成你自己的密码 [llm] # 统一走 TaoToken 通道换模型只改 model 字段 provider openai-compatible api_key 你的TaoToken统一Key base_url https://taotoken.net/api model claude-sonnet-4-20250514 timeout 60 max_tokens 4096 [llm.params] temperature 0.7 top_p 0.9几个字段说明一下方便你对照排查字段作用常见取值provider通道协议类型openai-compatibleapi_key统一 Key控制台创建的那串base_urlAPI 基础地址https://taotoken.net/apimodel具体模型名按需切换timeout请求超时秒数60 起步注意base_url结尾不要多加斜杠也不要带任何查询参数原样写https://taotoken.net/api最稳。api_key前后不要留空格否则会报鉴权失败。3.4 启动服务配置保存后启动openclaw start终端出现server is running on http://localhost:9000就说明起来了。这个终端窗口别关关了服务就停。想后台常驻可以后面用openclaw service install。4. 验证请求确认通道真的通了4.1 命令行看状态新开一个终端窗口查运行状态openclaw status显示 running 即正常。再看日志确认没有鉴权报错openclaw logs4.2 网页后台发一条测试指令浏览器打开http://localhost:9000用 config.toml 里设的账号密码登录。进入对话界面输入一条能验证模型是否真的在回话的指令比如用一句话说明你现在使用的是哪个模型通道。如果模型正常返回内容说明 TaoToken 统一 Key 已经生效整条链路openclaw → TaoToken → 模型是通的。返回报错的话直接跳到第 5 节。4.3 用 curl 直接验证 API 通道想更精确地定位问题可以绕过 openclaw 直接打一次 API确认 Key 本身没问题curl -X POST https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer 你的TaoToken统一Key \ -H Content-Type: application/json \ -d { model: claude-sonnet-4-20250514, messages: [{role: user, content: ping}] }返回里有choices字段就说明 Key 和通道都正常问题在 openclaw 配置侧如果这里就报 401那就是 Key 或地址写错了。5. 本篇常见错排查5.1 报错npm error code 128这是 Git 走 SSH 拉 GitHub 失败。回到 2.2 节那条insteadOf配置确认执行过git config --global url.https://github.com/.insteadOf gitgithub.com: npm cache clean --force npm install -g openclawlatest5.2 报错command not found: openclawnpm 全局 bin 目录没进 PATH。先确认npm config get prefix把输出的路径加进~/.zshrcecho export PATH$(npm config get prefix)/bin:$PATH ~/.zshrc source ~/.zshrc5.3 报错端口 9000 被占用改 config.toml 里的port换成 9001 或 9002保存后重启openclaw stop openclaw start浏览器记得用新端口访问。5.4 报错API 密钥无效 / 调用失败按这个顺序查先看api_key有没有多余空格再看base_url是不是https://taotoken.net/api然后用 4.3 节的 curl 单独验证 Key。如果 curl 通、openclaw 不通多半是 config.toml 里provider或model字段写错了对照 3.3 的骨架改回来。5.5 报错EACCES permission denied之前用 sudo 装过包导致权限错乱。执行sudo chown -R $(whoami) ~/.npm sudo chown -R $(whoami) /usr/local/lib/node_modules npm cache clean --force npm install -g openclawlatest之后所有 npm 命令都不加 sudo。6. 后续怎么用按场景选入口部署跑通只是起点接下来看你主要拿 openclaw 干什么。如果你是想长期做编码、跑 Agent 任务建议把通道能力用起来走 Coding Plan 更划算配置方式在控制台里能看到Coding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite如果你只是想先验证某个模型在 openclaw 里表现如何直接用模型对话页试不用改本地配置模型对话https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_contentmodel-chatutm_campaignrewrite如果你在排查接入问题、想确认参数写法接入文档是最快的参考接入文档https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite如果你还没创建 Key或者想再建一个专门给 openclaw 用的 Key去 API Keys 页API Keyshttps://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite最后补一句实操经验config.toml 改完一定要openclaw restart光保存不重启配置不生效这个坑我踩过不止一次。
