2026年MacBook 本地部署 OpenClaw 完全指南

大家好，我是讯享网，很高兴认识大家。这里提供最前沿的Ai技术和互联网信息。

环境：macOS / Intel i7 / 16GB 内存 / 256GB 硬盘目标：本地部署 OpenClaw + NapCat 机器人 + 远端大模型（MiniMax）更新：2026-03-01

OpenClaw 是一个开源 AI Agent 框架，让你在本地运行一个 AI 助手，通过各种聊天软件（、微信、Telegram 等）与它交互。它的核心特点：

本地运行、远端思考：框架跑在你的电脑上，但大脑（LLM）在云端
多通道接入：同一个 Agent 可以同时连接多个聊天平台
技能扩展：通过 Skills 系统无限扩展能力（联网搜索、读网页、操作浏览器等）

图表0

图表1

组件	角色	类比
Gateway	消息中枢，连接所有通道和服务	类似”总机/路由器”
Agent	AI 大脑，负责理解意图、调用工具	类似”秘书”
NapCat	协议适配器，把消息转成标准格式	类似”翻译官”
大模型 API	提供推理能力	类似”外聘顾问的大脑”
Skills	扩展能力包（搜索、摘要、浏览器等）	类似”技能证书”
Tools	内置基础工具（web_fetch/search/browser）	类似”自带的工具箱”

图表2

图表3

# 先装 Homebrew（如果没有）
/bin/bash -c “\((curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)" # 装 Node.js brew install node # 验证 node -v # 应输出 v22.x.x 或更高 npm -v# 1. 确认你的 CPU 架构 uname -m # x86_64 → Intel Mac # arm64 → Apple Silicon (M1/M2/M3/M4) # 2. 下载对应版本（以 v22.14.0 为例） # Intel Mac: curl -o ~/node.tar.gz https://nodejs.org/dist/v22.14.0/node-v22.14.0-darwin-x64.tar.gz # Apple Silicon: curl -o ~/node.tar.gz https://nodejs.org/dist/v22.14.0/node-v22.14.0-darwin-arm64.tar.gz # 3. 解压到本地目录 mkdir -p ~/local/node tar -xzf ~/node.tar.gz --strip-components=1 -C ~/local/node # 4. 添加到 PATH（写入 .zshrc 永久生效） echo 'export PATH="\)HOME/local/node/bin:$PATH"' >> ~/.zshrc source ~/.zshrc # 5. 验证 node -v && npm -v🔴 坑点 1：CPU 架构要匹配！ - 用 uname -m 确认架构，下载对应版本 - 如果终端运行在 Rosetta 模式（arch 输出 i386），即使是 M 系列芯片也要下载 x86_64 版 - Homebrew 在某些机器上会装错架构的 Ruby，导致 brew 命令报 Bad CPU type in executable🔴 坑点 2：npm 全局安装路径 手动安装 Node 时，npm 全局包默认装到 Node 目录下，建议配置独立目录避免权限问题：mkdir -p ~/.npm-global npm config set prefix ~/.npm-global echo 'export PATH="$HOME/.npm-global/bin:$PATH"' >> ~/.zshrc source ~/.zshrcnpm install -g openclaw@latest openclaw --version # 应输出版本号，如 2026.2.26🔴 坑点 3：openclaw 命令找不到 npm 全局安装后，可执行文件在 npm prefix 的 bin/ 下。如果 openclaw 找不到：# 查看 npm 全局 bin 目录 npm config get prefix # 确保该路径/bin 在 PATH 中 export PATH="$(npm config get prefix)/bin:\(PATH"openclaw onboard向导选项建议：<table data-draft-node="block" data-draft-type="table" data-size="normal" data-row-style="normal"><tbody><tr><th>步骤</th><th>推荐选择</th><th>说明</th></tr><tr><td>免责声明</td><td>Yes</td><td>必须同意</td></tr><tr><td>配置模式</td><td>QuickStart</td><td>快速入门</td></tr><tr><td>模型配置</td><td>跳过</td><td>后面手动配置更灵活</td></tr><tr><td>聊天通道</td><td>跳过</td><td>后面配置 </td></tr><tr><td>技能包</td><td>No</td><td>后面按需安装</td></tr><tr><td>Hooks</td><td>Memory</td><td>启用记忆功能</td></tr></tbody></table>配置文件路径：~/.openclaw/openclaw.json<table data-draft-node="block" data-draft-type="table" data-size="normal" data-row-style="normal"><tbody><tr><th>提供商</th><th>推荐模型</th><th>免费额度</th><th>API 兼容性</th><th>特点</th></tr><tr><td>MiniMax</td><td>MiniMax-M2.5</td><td>Coding Plan ¥49/月</td><td>OpenAI 兼容</td><td>便宜够用</td></tr><tr><td>智谱 AI</td><td>GLM-4.7</td><td>有</td><td>OpenAI 兼容</td><td>中文能力强</td></tr><tr><td>阿里百炼</td><td>qwen3-max</td><td>有</td><td>OpenAI 兼容</td><td>性价比高</td></tr><tr><td>DeepSeek</td><td>deepseek-chat</td><td>有</td><td>OpenAI 兼容</td><td>推理能力强</td></tr><tr><td>OpenAI</td><td>gpt-4o</td><td>无</td><td>原生</td><td>英文最强，需翻墙</td></tr></tbody></table>openclaw config set 'models.providers.minimax' --json '{ "baseUrl": "https://api.minimaxi.com/v1", "apiKey": "你的API-Key", "api": "openai-completions", "models": [ { "id": "MiniMax-M2.5", "name": "MiniMax M2.5" }, { "id": "MiniMax-M2.1", "name": "MiniMax M2.1" } ] }' # 设置默认模型 openclaw models set minimax/MiniMax-M2.5nano ~/.openclaw/openclaw.json在 models 部分填入（其他提供商只需替换 baseUrl 和 apiKey）：{ "models": { "providers": { "minimax": { "baseUrl": "https://api.minimaxi.com/v1", "apiKey": "你的sk-开头的Key", "api": "openai-completions", "models": [ { "id": "MiniMax-M2.5", "name": "MiniMax M2.5" } ] } } }, "agents": { "defaults": { "model": { "primary": "minimax/MiniMax-M2.5" } } } }🔴 坑点 4：MiniMax Coding Plan 的 API Key 格式 MiniMax 有两种 Key： - sk-sp- 开头 → Standard Plan Key - sk-cp- 开头 → Coding Plan Key（¥49/月套餐专属）两者不通用，Coding Plan 必须用 sk-cp- 开头的 Key，否则会报错。智谱 AI（GLM）openclaw config set 'models.providers.zhipu' --json '{ "baseUrl": "https://open.bigmodel.cn/api/paas/v4", "apiKey": "你的API-Key", "api": "openai-completions", "models": [ { "id": "glm-4-plus", "name": "GLM-4 Plus" }, { "id": "glm-4.7", "name": "GLM-4.7" } ] }' openclaw models set zhipu/glm-4.7阿里百炼（Qwen）openclaw config set 'models.providers.qwen' --json '{ "baseUrl": "https://dashscope.aliyuncs.com/compatible-mode/v1", "apiKey": "你的API-Key", "api": "openai-completions", "models": [ { "id": "qwen3-max", "name": "Qwen3 Max" }, { "id": "qwen3-plus", "name": "Qwen3 Plus" } ] }' openclaw models set qwen/qwen3-maxDeepSeekopenclaw config set 'models.providers.deepseek' --json '{ "baseUrl": "https://api.deepseek.com/v1", "apiKey": "你的API-Key", "api": "openai-completions", "models": [ { "id": "deepseek-chat", "name": "DeepSeek Chat" }, { "id": "deepseek-reasoner", "name": "DeepSeek Reasoner" } ] }' openclaw models set deepseek/deepseek-chatNapCat 是的 OneBot 协议适配器，让 OpenClaw 能收发消息。<ol><li data-pid="N91FA580">下载 Docker Desktop for Mac</li><li data-pid="h4bIlABr">安装并启动（确保状态栏出现 Docker 图标） 🔴 坑点 5：Docker Desktop 架构 同样注意下载与你 CPU 匹配的版本（Intel / Apple Silicon）。 启动 NapCat 容器 docker run -d \ --name napcat \ --restart always \ -e ACCOUNT=你的号 \ -e WS_ENABLE=true \ -e NAPCAT_GID=\)(id -g) -e NAPCAT_UID=$(id -u) -p 3001:3001 -p 6099:6099 mlikiowa/napcat-docker:latest
扫码登录
# 查看容器日志，等待二维码出现
docker logs -f napcat
日志中会出现 QR Code，用手机扫码登录。登录成功后会看到：
[] Logged in as: 你的昵称 (你的号)
配置 NapCat WebSocket
打开 NapCat 管理界面：http://localhost:6099

首次登录需要查看 WebUI Token：

docker logs napcat 2>&1 | grep ”WebUi Token“
# 输出类似：[NapCat] [WebUi] WebUi Token: xxxxxxxx

添加一个 反向 WebSocket 连接：

URL: ws://host.docker.internal:18789/api/（Docker 内访问宿主机）
Token: 填你在 openclaw.json 中设置的 accessToken

编辑 ~/.openclaw/openclaw.json，添加：

{
”channels“: {
”“: {
”enabled“: true,
”wsUrl“: ”ws://127.0.0.1:3001“,
”accessToken“: ”你设置的密码“
}
}
}

🔴 坑点 6：NapCat 连接方向 OpenClaw 和 NapCat 之间有两种连接方式： - 正向 WS：OpenClaw 主动连 NapCat（在 channels..wsUrl 配置） - 反向 WS：NapCat 主动连 OpenClaw（在 NapCat WebUI 配置）

推荐正向 WS（更简单），即 OpenClaw 连接 ws://127.0.0.1:3001。

编辑 ~/.openclaw/openclaw.json，确保有 gateway 认证配置：

{
”gateway“: {
”mode“: ”local“,
”auth“: {
”mode“: ”token“,
”token“: ”一个随机生成的长字符串“
}
}
}

生成随机 token 的方法：

openssl rand -hex 24

# 安装为 LaunchAgent（开机自启）
openclaw gateway install

# 或手动前台运行（调试用）
openclaw gateway

检查启动状态：

# 查看日志
tail -20 ~/.openclaw/logs/gateway.log

正常启动日志应该包含：

[gateway] listening on ws://127.0.0.1:18789
[] Connected to OneBot server
[] Logged in as: 你的昵称 (你的号)

🔴 坑点 7：Gateway 启动失败常见原因 1. 端口被占用：lsof -i :18789，kill 掉占用进程 2. JSON 格式错误：用 python3 -m json.tool ~/.openclaw/openclaw.json 验证 3. Node 版本检测：如果手动安装 Node，Gateway 可能找不到，日志会提示 System Node unknown…is below the required Node 22+，但只要它能用你安装的 Node 就没问题 4. LaunchAgent 启动失败：用 openclaw gateway stop && openclaw gateway install 重装

这三个是内置工具，不需要额外安装，在配置文件中启用即可。

工具	功能	类比	依赖
web_search	关键词搜索，返回结果列表	“打开百度搜一下”	无
web_fetch	读取指定 URL 的正文内容	“把这篇文章内容读出来”	无
browser	控制真实 Chrome 浏览器	“坐在电脑前手动操作浏览器”	Chrome + 扩展

编辑 ~/.openclaw/openclaw.json，在顶层添加 tools 字段：

{
”tools“: {
”web“: {
”fetch“: {
”enabled“: true,
”maxChars“: 10000,
”timeoutSeconds“: 30
},
”search“: {
”enabled“: true
}
}
}
}

🔴 坑点 8：browser 不是放在 tools 下的！ browser 是独立的顶级服务，不需要在 tools 中声明。如果写了 ”tools“: { ”browser“: {…} } 会导致配置校验失败，Gateway 无法启动！

错误示例（不要这样写）：

”tools“: {
”browser“: { ”enabled“: true } ← ❌ 会报错
}

browser 服务会在 Gateway 启动时自动开启，日志中出现 Browser control listening on http://127.0.0.1:18791/ 即表示就绪。

🔴 坑点 9：JSON trailing comma JSON 不允许最后一个元素后面有逗号。以下写法会导致 Gateway 启动失败：

{
”search“: { ”enabled“: true }
}, ← ❌ 这个逗号不能有（如果后面没有其他字段）

改完配置后务必用 python3 -m json.tool ~/.openclaw/openclaw.json 验证。

Browser 工具需要一个 Chrome 扩展来桥接 OpenClaw 和浏览器。

openclaw browser extension install

这会把扩展文件下载到 /.openclaw/browser/chrome-extension/。

打开 Chrome，地址栏输入 chrome://extensions
右上角开启开发者模式
点击加载已解压的扩展程序
选择路径：/.openclaw/browser/chrome-extension
固定扩展到工具栏

加载后会弹出设置页面（chrome-extension://xxx/options.html），填写：

字段	值
Port	18792（默认，不用改）
Gateway token	填 openclaw.json 中 gateway.auth.token 的值

点 Save，扩展图标变为已连接状态即可。

🔴 坑点 10：访达看不到 .openclaw 目录 macOS 默认隐藏以 . 开头的文件和目录。 - 快捷键：在访达中按 Cmd + Shift + . 切换显示隐藏文件 - 终端打开：open ~/.openclaw

🟡 提示：web_fetch 的局限性 部分网站（如知乎）有反爬保护，web_fetch 直接请求会被拦截，返回空内容或要求登录。此时需要用 browser 工具让 Agent 通过真实浏览器访问。可以告诉机器人”用浏览器打开这个链接”来触发 browser 工具。

以下是一份完整可用的配置文件模板：

{
”models“: {
”providers“: {
”minimax“: {
”baseUrl“: ”https://api.minimaxi.com/v1“,
”apiKey“: ”你的API-Key“,
”api“: ”openai-completions“,
”models“: [
{ ”id“: ”MiniMax-M2.5“, ”name“: ”MiniMax M2.5“ }
]
}
}
},
”agents“: {
”defaults“: {
”model“: {
”primary“: ”minimax/MiniMax-M2.5“
},
”models“: {
”minimax/MiniMax-M2.5“: {}
}
}
},
”commands“: {
”native“: ”auto“,
”nativeSkills“: ”auto“,
”restart“: true,
”ownerDisplay“: ”raw“
},
”gateway“: {
”mode“: ”local“,
”auth“: {
”mode“: ”token“,
”token“: ”你的gateway-token（openssl rand -hex 24 生成）“
}
},
”plugins“: {
”entries“: {
”“: { ”enabled“: true }
}
},
”tools“: {
”web“: {
”fetch“: {
”enabled“: true,
”maxChars“: 10000,
”timeoutSeconds“: 30
},
”search“: {
”enabled“: true
}
}
},
”channels“: {
”“: {
”enabled“: true,
”wsUrl“: ”ws://127.0.0.1:3001“,
”accessToken“: ”你设置的NapCat连接密码“
}
}
}

# 版本 & 健康检查
openclaw –version
openclaw doctor # 全面健康检查
openclaw doctor –fix # 自动修复检测到的问题

# Gateway 管理
openclaw gateway install # 安装为 LaunchAgent（开机自启）
openclaw gateway stop # 停止
openclaw gateway # 前台运行（调试用）

# 配置
openclaw config get # 查看当前配置
openclaw configure # 交互式配置向导

# 模型
openclaw models list # 查看可用模型
openclaw models set <provider>/<model-id> # 切换模型

# Skills
openclaw skills list # 查看所有技能及状态
openclaw skills check # 检查哪些技能就绪/缺依赖
openclaw skills info <name> # 查看某个技能详情

# 日志
tail -f ~/.openclaw/logs/gateway.log # 实时查看日志

# 直接对话（绕过聊天通道）
openclaw agent –message ”你好“

#	坑点	现象	解决方案
1	CPU 架构不匹配	Bad CPU type in executable	uname -m 确认架构，下载对应版本
2	npm 全局路径缺失	openclaw: command not found	配置 npm prefix 并加入 PATH
3	MiniMax Key 类型混用	API 鉴权失败	Coding Plan 用 sk-cp- 开头的 Key
4	JSON trailing comma	Gateway 启动失败	python3 -m json.tool 校验 JSON
5	browser 写在 tools 下	Unrecognized key: ”browser“	browser 是独立服务，不放 tools 里
6	NapCat 扫码超时	容器反复重启	docker logs -f napcat 及时扫码
7	.openclaw 目录不可见	访达找不到配置目录	Cmd+Shift+. 或 open ~/.openclaw
8	Gateway LaunchAgent 故障	无法 start/stop	先 stop 再 install 重装
9	知乎等反爬网站	web_fetch 返回空	改用 browser 工具访问
10	macOS 下载文件被隔离	下载的二进制无法执行	xattr -cr 文件路径移除隔离属性

[[2026-02-28-AI笔记工作流搭建指南]]

2026年MacBook 本地部署 OpenClaw 完全指南

相关推荐