MacBook 本地部署 OpenClaw 完全指南

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

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

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

图表0

图表1

图表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 ~/.zshrc

npm 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 skills 教程

openclaw onboard

向导选项建议：

配置文件路径：~/.openclaw/openclaw.json

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.5

nano ~/.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-max

DeepSeek

openclaw 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-chat

NapCat 是 的 OneBot 协议适配器，让 OpenClaw 能收发 消息。

1. 下载 Docker Desktop for Mac
2. 安装并启动（确保状态栏出现 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
3. 首次登录需要查看 WebUI Token：

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

1. 添加一个 反向 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 重装

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

编辑 ~/.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/。

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

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

点 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 “你好”

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