OpenClaw 本地部署教程（Windows/macOS 通用，超详细版）

OpenClaw 本地部署教程（Windows/macOS 通用，超详细版）

前言

OpenClaw 是一款开源 AI 助手框架，支持在 WhatsApp、Telegram、Discord 等多个消息平台部署个人 AI 助手，可对接 OpenAI、Anthropic、Google AI 等多种模型，也支持 Ollama 本地模型运行，兼顾灵活性与实用性。

本教程针对 Windows 10/11 及 macOS 12+ 系统，采用「通用核心步骤+平台专属细节」的结构，全程手把手操作，从环境准备、依赖安装到部署验证、故障排查，覆盖所有关键环节，新手也能轻松跑通，无需专业开发经验。

⚠️ 核心说明：

• 双平台通用部署逻辑一致，仅「环境依赖安装」「终端操作」有细微差异，已单独标注，按需查看即可；
• 部署全程免费，无需付费订阅，仅需准备 AI 模型 API Key（可选，也可使用 Ollama 本地模型）；
• 最低配置要求：内存 2GB+（建议 4GB），存储 10GB+ 可用空间，网络稳定（用于下载依赖和验证部署）。

一、前置准备（双平台通用）

部署前需完成 3 件事，提前准备好，避免后续操作卡顿。

1.1 必备工具/资源

名称	用途	获取方式
终端工具	执行部署命令（Windows：PowerShell；macOS：终端）	系统自带，无需额外安装
浏览器	访问 OpenClaw 官网、模型平台获取 API Key	任意浏览器（Chrome/Edge/Safari 均可）
AI 模型 API Key	对接 AI 模型（可选，推荐 Anthropic/OpenAI/Ollama）	1. Anthropic（Claude）：访问其官网创建 2. OpenAI（GPT）：访问其官网创建 3. Ollama（本地免费）：ollama.com/
网络环境	下载依赖、同步配置	稳定外网（无需科学上网，国内网络可正常部署）

1.2 API Key 获取说明（新手必看）

如果使用在线模型（Anthropic/OpenAI），需获取对应 API Key，步骤如下（以 Anthropic 为例）：

1. 访问 Anthropic 官网，注册/登录账号（需绑定邮箱，支持国内邮箱）；
2. 进入「Settings → API Keys」，点击「Create API Key」，输入名称（如 OpenClaw），生成密钥；
3. 复制密钥，保存到记事本（后续配置会用到，切勿泄露，泄露后立即 revoke）。

✅ 替代方案：若不想使用在线模型，可安装 Ollama 本地模型（免费，无需 API Key），部署步骤见下文「四、可选配置：Ollama 本地模型对接」。

1.3 核心依赖说明

OpenClaw 运行依赖 Node.js（v22+），双平台均需安装，后续步骤会详细讲解安装方法，无需提前下载。

二、环境依赖安装（Windows/macOS 分平台操作）

核心依赖为 Node.js（v22+），双平台安装步骤不同，按需选择对应章节操作，安装完成后验证是否生效。

2.1 Windows 系统（Windows 10/11）

步骤 1：安装 Node.js（v22+）

1. 访问 Node.js 官网：nodejs.org/zh-cn/downl…；
2. 下滑找到「Windows 安装包」，点击下载（64 位系统选择「Windows Installer (.msi) 64-bit」，32 位选择 32-bit，建议 64 位）；
3. 双击安装包，勾选「I accept the terms in the License Agreement」，点击「Next」；
4. 选择安装路径（默认即可，建议记住路径，后续排查问题有用），点击「Next」；
5. 勾选「Add to PATH」（关键！自动配置环境变量，无需手动操作），点击「Next」；
6. 其余步骤默认下一步，点击「Install」，等待安装完成，点击「Finish」。

步骤 2：验证 Node.js 安装成功

1. 按下「Win + R」，输入「powershell」，打开 PowerShell（管理员身份运行，避免权限不足）；

2. 分别输入以下两条命令，按下回车，若输出版本号（Node.js ≥22.0.0，npm ≥10.5.0），则安装成功：

   # 查看 Node.js 版本
   node -v
   # 查看 npm 版本
   npm -v
   

   ⚠️ 避坑点：若提示「node 不是内部或外部命令」，说明环境变量未配置成功，重启电脑后重新验证，仍失败则手动配置环境变量（步骤见下文「六、常见问题排查」）。

步骤 3：安装额外依赖（可选，解决后续安装报错）

部分 Windows 系统缺少构建工具，会导致 OpenClaw 安装失败，提前安装：

# 以管理员身份运行 PowerShell，执行以下命令
npm install -g node-gyp
npm install -g windows-build-tools

等待安装完成，无需验证，直接进入下一步。

2.2 macOS 系统（macOS 12+）

步骤 1：安装 Node.js（v22+）（两种方式，任选其一）

方式 1：官网安装（简单，适合新手）

1. 访问 Node.js 官网：nodejs.org/zh-cn/downl…；
2. 下滑找到「macOS 安装包」，点击下载（Intel 芯片选择「macOS Installer (.pkg) Intel」，M 芯片选择「macOS Installer (.pkg) ARM64」）；
3. 双击安装包，按照提示下一步，完成安装（默认自动配置环境变量）。

方式 2：Homebrew 安装（推荐，适合有 Homebrew 的用户）

1. 打开「终端」（Launchpad → 其他 → 终端）；

2. 若未安装 Homebrew，先执行以下命令安装（复制粘贴，回车即可）：

   /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
   

3. 安装 Node.js（v22+）：

   brew install node@22
   

步骤 2：验证 Node.js 安装成功

1. 打开终端，分别输入以下两条命令，按下回车，若输出版本号（Node.js ≥22.0.0，npm ≥10.5.0），则安装成功：

   # 查看 Node.js 版本
   node -v
   # 查看 npm 版本
   npm -v
   

步骤 3：安装 Xcode 命令行工具（必装，解决依赖构建问题）

macOS 系统需要 Xcode 命令行工具才能正常构建 OpenClaw 依赖，执行以下命令安装：

xcode-select --install

弹出安装提示，点击「安装」，等待完成（无需安装完整 Xcode，仅安装命令行工具即可）。

⚠️ 避坑点：若提示「xcode-select: error: command line tools are already installed」，说明已安装，无需重复操作。

三、OpenClaw 核心部署步骤（双平台通用）

环境依赖安装完成后，进入核心部署环节，双平台操作完全一致，全程在终端（PowerShell/终端）执行命令，每一步都标注详细说明，切勿跳过。

步骤 1：一键安装 OpenClaw（推荐，新手首选）

1. 打开终端（Windows：PowerShell 管理员模式；macOS：终端）；

2. 复制对应命令，粘贴到终端，按下回车，自动开始安装（会自动下载 OpenClaw 最新版本及依赖）：

   ✅ Windows（PowerShell）：

   iwr -useb https://openclaw.ai/install.ps1 | iex
   

   ✅ macOS（终端）：

   curl -fsSL https://openclaw.ai/install.sh | bash
   

3. 安装过程中，会提示是否进行新手引导（Onboard），输入「y」（默认），按下回车，进入配置向导；若暂时不想配置，输入「n」，后续可通过命令启动向导。

   ⚠️ 避坑点：

   • 安装过程中若提示「权限不足」，Windows 确保以管理员身份运行 PowerShell，macOS 在命令前加「sudo」（如：sudo curl ...）；
   • 若出现「sharp 安装失败」，macOS 执行「SHARP_IGNORE_GLOBAL_LIBVIPS=1 npm install -g openclaw@latest」，Windows 重新运行安装命令即可；
   • 网络不佳导致下载超时，可重试命令，或切换网络（如手机热点）。

步骤 2：新手配置向导（Onboard，核心步骤）

配置向导会引导完成网关设置、AI 模型配置、消息渠道连接，全程交互式操作，按提示一步一步来即可。

1. 若安装时未进入向导，手动启动向导，执行以下命令：

   openclaw onboard --install-daemon
   

2. 向导配置步骤（按提示输入，全程中文引导）：

   （1）网关配置（Gateway）

   • 提示「选择网关类型」，默认「本地网关」（Local Gateway），直接按下回车（新手无需修改）；
   • 提示「设置网关端口」，默认端口 18789（OpenClaw 默认端口），直接回车，若端口被占用，会提示修改，按提示输入新端口（如 18790）即可。

   （2）AI 模型配置（Agent）

   • 提示「选择 AI 模型提供商」，按自身情况选择（如 Anthropic/OpenAI/Ollama），输入对应编号，回车；
   • 若选择 Anthropic/OpenAI，提示「输入 API Key」，粘贴提前准备好的 API Key，回车（粘贴时直接右键粘贴，无需输入，确保密钥无空格）；
   • 若选择 Ollama，提示「是否已安装 Ollama」，若已安装，输入「y」，回车，自动对接本地模型；若未安装，先按下文「四、可选配置」安装 Ollama，再重新配置。

   （3）守护进程安装（Daemon）

   • 提示「是否安装守护进程」，输入「y」，回车（守护进程可让 OpenClaw 后台运行，关闭终端后仍能正常使用）；
   • Windows 会安装为系统服务，macOS 会安装为 launchd 服务，全程自动完成，无需手动操作。

   （4）消息渠道配置（Channels，可选）

   • 提示「是否连接消息渠道」，新手推荐先连接 Telegram（简单易操作），输入对应编号，回车；
   • 按提示获取 Telegram Bot Token（步骤：打开 Telegram → 搜索 @BotFather → 发送 /newbot→ 按提示创建机器人，获取 Token）；
   • 粘贴 Token，回车，完成渠道连接；若暂时不想连接，输入「n」，后续可通过命令连接（见下文「步骤 5」）。

3. 配置完成后，终端会提示「配置成功」，并显示网关地址（默认：http://127.0.0.1:18789）。

步骤 3：启动 OpenClaw 网关（核心服务）

网关是 OpenClaw 的核心，负责处理所有消息和模型请求，配置完成后，启动网关：

# 启动网关（默认端口，若修改过端口，会自动使用修改后的端口）
openclaw gateway start

# 查看网关状态（确认是否启动成功）
openclaw gateway status

✅ 启动成功判断：终端输出「Gateway is running」，且无红色报错；若提示「Gateway failed to start」，查看下文「六、常见问题排查」。

步骤 4：验证部署成功（关键步骤）

部署是否成功，通过 3 种方式验证，确保每一步都通过，后续才能正常使用。

方式 1：健康状态检查

执行以下命令，检查 OpenClaw 所有服务状态：

# 基础健康检查
openclaw health

# 详细健康检查（推荐）
openclaw status --deep

✅ 成功标志：所有服务显示「绿色对勾」，网关地址（http://127.0.0.1:18789）可访问，日志无错误信息。

方式 2：访问 Web 仪表板

1. 打开浏览器，输入网关地址（默认：http://127.0.0.1:18789），按下回车；
2. 若能正常打开 OpenClaw 仪表板，显示「Dashboard」「Settings」等菜单，说明网关启动成功，部署完成。

方式 3：发送测试消息（已连接消息渠道的情况）

1. 若已连接 Telegram，打开 Telegram，找到创建的机器人，发送消息（如「Hello OpenClaw」）；
2. 若机器人能正常回复，说明 AI 模型、消息渠道均配置成功，部署完全可用。

⚠️ 注意：Telegram 机器人默认启用隐私模式，首次发送消息可能需要通过「openclaw pairing approve」命令批准配对，具体步骤见下文「步骤 5」。

步骤 5：消息渠道补充配置（可选，新手推荐）

若配置向导中未连接消息渠道，可手动连接，这里以 Telegram 为例，其他渠道（WhatsApp/Discord）步骤类似。

（1）连接 Telegram 渠道

# 登录 Telegram 渠道，输入 Bot Token
openclaw channels login telegram

粘贴之前获取的 Telegram Bot Token，回车，完成连接。

（2）批准 Telegram 配对（解决机器人不回复问题）

Telegram 机器人默认需要批准配对才能回复消息，步骤如下：

# 查看待批准的配对请求
openclaw pairing list telegram

# 批准配对（将 `<code>` 替换为实际配对码）
openclaw pairing approve telegram <code>

批准后，再次发送测试消息，机器人即可正常回复。

（3）连接 WhatsApp 渠道（可选）

# 登录 WhatsApp 渠道，生成二维码
openclaw channels login whatsapp

终端会显示二维码，打开手机 WhatsApp → 设置 → 已连接设备 → 扫描二维码，完成登录即可。

⚠️ 避坑点：WhatsApp 扫码失败，确保手机和电脑在同一网络，刷新二维码（二维码有效期较短），关闭 VPN，更新手机 WhatsApp 到最新版本。

四、可选配置：Ollama 本地模型对接（免费，无需 API Key）

若不想使用在线模型（Anthropic/OpenAI），可安装 Ollama 本地模型，完全免费，无需 API Key，适合无外网或不想付费的用户。

4.1 安装 Ollama（双平台通用）

1. 访问 Ollama 官网：ollama.com/；
2. 下载对应系统的安装包（Windows/macOS 均有对应版本）；
3. 双击安装包，按提示完成安装（默认自动配置环境变量）；
4. 验证安装：打开终端，输入「ollama -v」，输出版本号即安装成功。

4.2 下载本地模型（如 Llama 3）

执行以下命令，下载 Llama 3 模型（轻量版，适合本地部署）：

ollama pull llama3:8b

等待下载完成（模型大小约 4GB，视网络速度而定），下载完成后，自动保存到本地。

4.3 对接 OpenClaw 与 Ollama

# 重新启动 OpenClaw 配置向导
openclaw onboard --install-daemon

# 选择 AI 模型提供商时，输入对应编号（选择 Ollama）
# 按提示确认已安装 Ollama，自动对接本地模型，无需输入 API Key

对接完成后，重复「三、步骤 4」，验证模型是否正常工作（发送测试消息，机器人能正常回复即可）。

五、日常操作命令（双平台通用，必备）

部署完成后，常用命令整理，方便日常管理 OpenClaw，复制即可使用：

# 启动 OpenClaw 网关
openclaw gateway start

# 停止 OpenClaw 网关
openclaw gateway stop

# 重启 OpenClaw 网关
openclaw gateway restart

# 查看网关状态
openclaw gateway status

# 查看 OpenClaw 详细状态（排查问题必备）
openclaw status --all

# 查看 OpenClaw 日志（报错时排查）
openclaw logs --follow

# 重新配置 OpenClaw（修改模型、渠道等）
openclaw configure

# 打开 Web 仪表板
openclaw dashboard

# 检查配置文件是否有效
openclaw config validate

# 查看配置文件路径
openclaw config path

# 安全审计（检查安全隐患）
openclaw security audit --deep

六、常见问题排查（新手必看，解决 99% 问题）

部署过程中遇到报错，不要慌，按以下问题逐一排查，均为高频问题，对应解决方案已整理好。

问题 1：Node.js 安装后，终端提示「node 不是内部或外部命令」

✅ 解决方案：

• Windows：重启电脑，重新验证；若仍失败，手动配置环境变量：

  1. 右键「此电脑」→「属性」→「高级系统设置」→「环境变量」；
  2. 在「系统变量」中找到「Path」，点击「编辑」；
  3. 点击「新建」，粘贴 Node.js 安装路径（默认：C:\Program Files\nodejs）；
  4. 点击「确定」，重启 PowerShell，重新验证。

• macOS：执行「source ~/.bash_profile」或「source ~/.zshrc」，刷新环境变量，重新验证。

问题 2：安装 OpenClaw 时，提示「权限不足」

✅ 解决方案：

• Windows：以「管理员身份」运行 PowerShell，重新执行安装命令；
• macOS：在安装命令前加「sudo」，如「sudo curl -fsSL https:///install.sh| bash」，输入电脑密码（输入时无显示，正常输入即可）。

问题 3：网关启动失败，提示「端口 18789 被占用」

✅ 解决方案（两种方式，任选其一）：

方式 1：停止占用端口的进程（推荐）：

• Windows（PowerShell）：

  # 查找占用 18789 端口的进程 PID
  netstat -ano | findstr :18789
  # 终止进程（将 <PID> 替换为实际进程 ID）
  taskkill /F /PID <PID>
  

• macOS（终端）：

  # 查找占用 18789 端口的进程 PID
  lsof -i :18789
  # 终止进程（将 <PID> 替换为实际进程 ID）
  kill -9 <PID>
  

方式 2：修改 OpenClaw 网关端口：

# 启动网关时指定新端口（如 18790）
openclaw gateway --port 18790

# 或重新配置向导，指定新端口
openclaw onboard --gateway-port 18790

问题 4：发送测试消息，机器人不回复

✅ 解决方案：

1. 检查网关是否正常运行：「openclaw gateway status」，确保显示「running」；
2. 检查 AI 模型配置：「openclaw models status」，确认模型连接正常；
3. Telegram 机器人：执行「openclaw pairing list telegram」，查看是否有未批准的配对，批准后重试；
4. WhatsApp 机器人：检查手机是否在线，是否在其他设备登录 WhatsApp Web，重启网关后重试；
5. 查看日志：「openclaw logs --follow」，排查是否有报错（如 API Key 无效、模型不支持）。

问题 5：配置文件修改后，不生效

✅ 解决方案：

1. 确认配置文件路径：执行「openclaw config path」，找到配置文件（默认：~/.openclaw/openclaw.json）；
2. 修改配置文件后，重启网关：「openclaw gateway restart」；
3. 验证配置是否生效：「openclaw status」，查看生效的配置信息。

问题 6：OpenClaw 启动后，重启电脑失效

✅ 解决方案：

安装守护进程时未成功，重新执行以下命令，安装守护进程：

openclaw onboard --install-daemon

安装完成后，重启电脑，OpenClaw 会自动启动。

七、总结

本教程覆盖 OpenClaw 本地部署全流程，Windows/macOS 双平台通用，核心步骤为：「环境准备 → 依赖安装 → 一键部署 → 配置向导 → 验证测试」，全程纯技术分享，无多余内容。

新手重点关注「环境依赖安装」和「配置向导」两个环节，按步骤操作，基本不会出错；若遇到问题，优先查看「常见问题排查」，99% 的高频问题都能解决。

部署完成后，可根据需求对接不同的 AI 模型和消息渠道，自定义 AI 助手的功能（如网络搜索、代码执行等），具体可参考 OpenClaw 官方文档：docs.openclaw.ai/。

如果部署过程中遇到其他未提及的问题，可在评论区留言，或参考 OpenClaw 官方 FAQ：open-claw.me/zh/faq，获取更详细的解决方案。

---