本文档提供 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