1. 安装前必读 & 前置准备
1.1 适用范围 & 核心说明
本手册适用于零编程基础用户,提供完整的 OpenClaw 本地部署步骤。严格按照操作指引执行,通常可在 10 分钟内完成部署。
1.2 系统 & 硬件要求
- 系统版本:macOS 12.0 (Monterey) 及以上,建议升级至最新版本以避免兼容性问题。
- 硬件适配:Intel 芯片、Apple Silicon M1/M2/M3/M4 全系列均支持。
- 磁盘空间:至少预留 2GB 可用空间用于存放依赖环境和配置文件。
本文档提供 OpenClaw 在 macOS 系统上的本地化部署完整流程。涵盖前置环境准备(Homebrew、Node.js、Git)、核心程序安装、配置文件修改(API 密钥)、服务启动及常见报错解决方案。支持接入阿里云通义千问或 OpenAI 模型,亦可对接 Ollama 本地模型实现断网使用。包含终端命令速查表及进阶配置说明。
本手册适用于零编程基础用户,提供完整的 OpenClaw 本地部署步骤。严格按照操作指引执行,通常可在 10 分钟内完成部署。
Homebrew 是 macOS 专属包管理器,为后续依赖安装的基础。
/bin/zsh -c "$(curl -fsSL https://gitee.com/cunkai/HomebrewCN/raw/master/Homebrew.sh)"
Installation successful! 字样即成功。echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zprofile
eval "$(/opt/homebrew/bin/brew shellenv)"
brew -v,出现版本号即成功。OpenClaw 基于 Node.js 开发,需安装对应运行环境。
brew install node@20
echo 'export PATH="/opt/homebrew/opt/node@20/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc
node -v 和 npm -v,均正常输出版本号即成功。Git 用于拉取 GitHub 上的依赖仓库。
brew install git
git --version,出现版本号即成功。git config --global url."https://github.com/".insteadOf "ssh://[email protected]/"
git config --global url."https://github.com/".insteadOf "[email protected]:"
git config --global user.name "你的 GitHub 用户名"
git config --global user.email "你的 GitHub 注册邮箱"
终端一次性执行以下 4 个命令,全部正常输出版本号且无报错,说明前置环境就绪。
brew -v
node -v
npm -v
git --version
npm config set registry http://registry.npmmirror.com
git config --global url."https://github.com/".insteadOf ssh://[email protected]/
npm install -g openclaw@latest
added xxx packages in xxxs 字样,无红色报错即成功。openclaw -v,出现版本号即成功。openclaw init
Configuration initialized successfully! 字样即成功。OpenClaw 基于大模型运行,必须配置 API 密钥。
open ~/.openclaw/config.yaml
llm 配置段,以下提供两种方案:方案 1:阿里云通义千问(国内首选)
llm:
provider: dashscope
api_key: "你的通义千问 API 密钥"
model: "qwen-max"
base_url: "https://dashscope.aliyuncs.com/compatible-mode/v1"
方案 2:OpenAI GPT 方案
llm:
provider: openai
api_key: "你的 OpenAI API 密钥"
model: "gpt-4o"
base_url: "https://api.openai.com/v1"
openclaw start
OpenClaw server is running on http://localhost:9000 字样即成功。新开一个终端窗口,执行:
openclaw status
显示 running 状态说明服务正常运行。
http://localhost:9000(若修改过端口请替换)。在后台对话界面输入测试指令(如'帮我写一份 Mac 终端常用命令清单'),大模型正常返回内容说明全流程运行正常。
npm cache clean --force;重新执行安装命令。source ~/.zshrc;重启终端。openclaw stop;修改配置文件中的 port 参数;重启服务;检查防火墙设置。provider 和 base_url 匹配情况;确认密钥有效性;国内用户使用 OpenAI 需确保网络通畅。sudo chown -R $(whoami) ~/.npm;清理缓存;重新安装且不加 sudo。在后台「集成」模块中选择飞书或钉钉,创建企业应用获取 App ID 和 Secret 填入配置即可。
ollama pull qwen。llm 段:llm:
provider: ollama
model: "qwen"
base_url: "http://localhost:11434/v1"
openclaw service install
openclaw service uninstall
| 命令 | 功能说明 |
|---|---|
npm install -g openclaw@latest | 全局安装 / 升级 OpenClaw |
openclaw -v | 查看版本号 |
openclaw init | 初始化配置文件 |
openclaw start | 启动服务 |
openclaw stop | 停止服务 |
openclaw restart | 重启服务 |
openclaw status | 查看运行状态 |
openclaw logs | 查看运行日志 |
open ~/.openclaw/config.yaml | 打开核心配置文件 |

微信公众号「极客日志」,在微信中扫描左侧二维码关注。展示文案:极客日志 zeeklog
生成新的随机RSA私钥和公钥pem证书。 在线工具,RSA密钥对生成器在线工具,online
基于 Mermaid.js 实时预览流程图、时序图等图表,支持源码编辑与即时渲染。 在线工具,Mermaid 预览与可视化编辑在线工具,online
查找任何按下的键的javascript键代码、代码、位置和修饰符。 在线工具,Keycode 信息在线工具,online
JavaScript 字符串转义/反转义;Java 风格 \uXXXX(Native2Ascii)编码与解码。 在线工具,Escape 与 Native 编解码在线工具,online
使用 Prettier 在浏览器内格式化 JavaScript 或 HTML 片段。 在线工具,JavaScript / HTML 格式化在线工具,online
Terser 压缩、变量名混淆,或 javascript-obfuscator 高强度混淆(体积会增大)。 在线工具,JavaScript 压缩与混淆在线工具,online