2026 年，AI 智能体赛道迎来了一款现象级开源项目——OpenClaw。其 GitHub 星标已突破 28 万，凭借本地运行、零代码配置、自动任务处理三大核心特点，迅速成为开发者群体中的热门工具。OpenClaw 并非传统意义上的对话式 AI 或大语言模型本身，其核心价值在于打破 AI“只说不做”的局限，为大模型赋予完整的系统级执行能力，实现从“意图理解 → 任务拆解 → 执行闭环 → 结果反馈”的全流程自动化。

本文将从零开始，详细讲解 OpenClaw 的全平台安装部署方法，涵盖环境准备、一键脚本安装、模型配置、服务验证及常见问题处理，帮助开发者快速完成部署并投入使用。

一、OpenClaw 项目概述

1.1 项目背景

OpenClaw 由奥地利开发者 Peter Steinberger 于 2025 年 11 月发布，采用 MIT 开源协议，曾用名为 Clawdbot、Moltbot，2026 年初正式更名为 OpenClaw。其品牌 Logo 为红色龙虾造型，“Claw”寓意“用钳子抓取任务”，国内用户习惯将部署、调试该模型的过程称为“养虾”。

1.2 核心架构

从架构层面来看，OpenClaw 本质上不是一个独立的大模型，而是一个自托管的智能体网关与执行框架。它把 WhatsApp、Telegram、Discord 等聊天入口，与模型、会话、路由、记忆和工具系统连接起来，形成一个统一的“网关”（Gateway）。OpenClaw 采用 Hub-and-Spoke 架构，以一个 Gateway 作为中心枢纽，连接用户输入端（iMessage、Slack、WebChat、CLI、微信、飞书等）与 Agent 执行引擎。其核心模块包含：会话管理、记忆存储、工具沙箱、访问控制和任务编排——智能由模型提供，OpenClaw 则提供执行环境。

1.3 核心特性

特性	说明
本地运行	数据全程留存设备本地，隐私性更强，规避敏感信息外泄风险
零代码门槛	无需掌握编程知识，依托一键部署包即可快速上手
跨平台兼容	适配 Windows、macOS、Linux 多系统，可对接微信、飞书、Slack 等平台
开箱即用	整合式部署包内置全部运行依赖环境与基础技能，解压即可启动
全能任务处理	支持文件整理、邮件发送、表格制作、浏览器自动化、批量数据处理等场景

二、系统环境要求

在开始安装之前，请确保系统满足以下最低要求：

2.1 操作系统兼容性

操作系统	版本要求
Windows	Windows 10 / 11（64 位），建议使用专业版或企业版
macOS	macOS 12.0 Monterey 或更高版本
Linux	主流发行版，推荐 Ubuntu 22.04+

2.2 软硬件要求

配置项	最低要求	推荐配置
处理器	双核及以上	四核及以上
内存	≥2GB	≥4GB
Node.js	v22.x 或更高	v24.x LTS
依赖管理	npm 或 pnpm	pnpm（速度更快）
网络	需联网下载安装包和依赖	建议配置国内镜像源加速
其他	Git（源码安装需要）	—

2.3 大模型选择

OpenClaw 原生支持多种大语言模型接入，以下为官方推荐选项：

模型提供商	适用场景	接入方式
Moonshot AI (Kimi K2.5)	国内用户推荐、长上下文强	API Key
OpenAI	海外用户、功能全面	API Key
Anthropic	高安全性场景	API Key
Ollama	本地部署、数据隐私优先	本地推理

权限要求：Windows 需 PowerShell 管理员权限，Linux/macOS 需 sudo 权限。

三、OpenClaw 安装方法（三种方式详解）

OpenClaw 提供三种安装方式，用户可根据自身技术水平和使用场景灵活选择。

3.1 方法一：一键脚本安装（推荐新手）

这是官方最推荐的方式，脚本会自动检测并安装缺失依赖，全程无需手动干预。

第一步：下载安装包

打开 top.wokk.cn，点击「一键安装」，选择Windows或macOS版本下载。

第二步：安装（1分钟）

双击下载好的安装包：

① 同意使用协议 → 下一步
② 选择安装路径（保持默认即可）→ 下一步
③ 点击「安装」→ 等待完成
④ 点击「完成」→ 自动启动

【Windows 系统】 ：

1. 右键点击“开始”菜单，选择“终端（管理员）”或“Windows PowerShell（管理员）”，在 UAC 弹窗中点击“是”

2. 执行官方一键安装命令：

text

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

1. 国内用户若下载缓慢，可使用国内镜像加速脚本：

text

iwr -useb https://open-claw.org.cn/install-cn.ps1 | iex

1. 等待安装完成，脚本会自动完成 Node.js 检测、核心程序安装、环境变量配置

【macOS / Linux / WSL2 系统】 ：

1. 打开系统终端

2. 执行官方一键安装命令：

text

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

1. 国内用户可使用国内镜像加速：

text

curl -fsSL https://open-claw.org.cn/install-cn.sh | bash

1. 等待脚本执行完成，全程自动完成环境配置

脚本自动完成的操作：

1. 检测操作系统和现有环境

2. 安装或更新 Node.js（如未满足 v22 要求）

3. 全局安装 OpenClaw 最新版

4. 自动启动 onboard 初始化向导

3.2 方法二：npm 全局安装（推荐普通开发者）

适用于已具备 Node.js 22+ 环境的用户，使用 npm 直接安装最为简洁。

首先确认 Node.js 版本：

text

node --version

输出需为 v22.x.x 或更高版本。确认无误后执行全局安装：

text

npm install -g openclaw@latest

也可使用 pnpm（速度更快）：

text

pnpm add -g openclaw@latest

安装完成后，执行以下命令初始化并安装守护进程：

text

openclaw onboard --install-daemon

--install-daemon 参数会安装后台守护进程（macOS 使用 launchd，Linux 使用 systemd），确保 OpenClaw 开机自启并在后台持续运行。

3.3 方法三：源码编译安装（推荐开发者）

适用于需要修改源码或参与项目开发的用户。

方案 A：使用官方脚本的 git 模式

text

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

方案 B：手动克隆仓库

text

git clone https://github.com/openclaw/openclaw.git
cd openclaw
pnpm install && pnpm ui:build && pnpm build
pnpm openclaw onboard --install-daemon

开发模式启动（支持代码变更自动重载）：

text

pnpm gateway:watch

3.4 三种安装方式对比

安装方式	适用人群	优点	缺点
一键脚本	新手/快速体验	自动处理所有依赖、零门槛	可控性较低
npm 安装	普通开发者	简洁快速、精准控制版本	需预装 Node.js 22+
源码安装	高级开发者	可定制化、参与开发	操作较复杂

注意：Windows 用户若选择一键脚本安装，部分安全软件可能拦截 OpenClaw 进程。建议在安装、解压和启动程序之前，暂时关闭 360 安全卫士、腾讯电脑管家、火绒等安全防护软件。OpenClaw 运行时需要获取系统操控权限、文件读写权限以及模拟键鼠操作，易被安全软件误判为风险程序。

四、模型配置与初始化向导（onboard）

安装完成后，OpenClaw 会通过 onboard 向导引导完成核心配置，或可通过以下命令手动启动：

text

openclaw onboard --install-daemon

向导将依次引导完成以下四项配置：

1. Gateway（网关） ：设置本地通信网关端口（默认 18789）

2. Workspace（工作区） ：配置工作目录和权限

3. Channel（通道） ：连接通信平台（WhatsApp / Telegram / Discord / Slack 等）

4. Skill（技能） ：从 ClawHub 安装初始技能包

4.1 大模型接入配置（以 Kimi K2.5 为例）

Kimi K2.5 是 OpenClaw 创始人推荐的接入模型，国内用户体验尤佳。

配置步骤：

1. 安装成功后，系统弹出配置界面，选择 Yes 确认并回车

2. 使用键盘方向键选择 QuickStart（快速安装模式），敲击回车确认

3. 选择 Model，国内用户选择 Moonshot AI (Kimi K2.5)

4. 选择 Moonshot AI .cn 中国区接入点

5. 访问 https://platform.moonshot.cn/console 登录 Kimi 平台

6. 点击左侧 API Key 管理，创建 API Key 并复制密钥

7. 返回 OpenClaw 终端，粘贴 API Key 并敲击回车

8. 选择 Moonshot / Kimi-K2.5 模型并回车确认

9. 选择聊天载体，可先跳过，使用 TUI 进行体验

10. 选择网络搜索提供商，选择 Kimi

11. 返回 Kimi 工作台创建搜索专用 API Key，复制并粘贴

12. 按需选择技能包，一般建议选择 Yes 安装基础技能

4.2 本地大模型接入（Ollama）

对于数据隐私要求较高的场景，可通过 Ollama 部署本地大模型。以 Qwen3.5 9B 为例，INT4 量化版本仅需 4-5GB 显存即可流畅运行。

Ollama 配置要点：

• 确保 Ollama 服务已在本地运行

• OpenClaw 配置文件指向 http://localhost:11434

• 选择对应的本地模型名称

五、服务验证与常用命令

5.1 验证服务状态

安装完成并配置模型后，执行以下命令检查服务运行状态：

命令	作用
openclaw status	显示整体服务运行状态及组件依赖关系
openclaw gateway status	查看 Gateway 网关状态
openclaw gateway status --detail	包含 RPC 连接数、请求队列深度等关键指标
lsof -i :18789	验证端口监听（替换为实际服务端口）

5.2 启动交互式控制台

text

openclaw tui

TUI（文本用户界面）提供与 OpenClaw 交互的终端聊天控制台。退出 TUI 按两次 Ctrl + C。

5.3 常用管理命令

命令	说明
openclaw logs --follow --level=error	实时输出错误日志
openclaw doctor --fix	自动诊断并修复常见问题（端口冲突、配置语法错误等）
openclaw config validate --schema	执行配置文件 JSON Schema 验证并生成修复建议
openclaw update --channel stable	升级到稳定版
openclaw update --channel beta	升级到测试版
openclaw update --channel dev	升级到开发版

5.4 Gateway 启动

text

openclaw gateway --port 18789 --verbose

六、常见问题与解决方案

问题 1：终端无法识别 openclaw 指令

• 现象：安装成功后，运行 openclaw 命令提示“未找到命令”

• 原因：全局安装路径未加入系统环境变量 PATH

• 解决方案：

text

# 查看全局包位置
npm prefix -g

# 检查 PATH 是否包含该路径
echo $PATH

# 如未包含，添加到 shell 配置文件（~/.zshrc 或 ~/.bashrc）
export PATH="$(npm prefix -g)/bin:$PATH"
source ~/.zshrc   # 或 source ~/.bashrc

问题 2：Node.js 版本不匹配

• 现象：安装时显示 Node.js 版本低于 22.x

• 解决方案：

  • Linux/macOS：使用 nvm 管理 Node.js 版本

    text

    nvm install 22
    nvm use 22

  • Windows：下载官方 LTS 版本（v22.x 或 v24.x）重新安装

问题 3：Gateway 服务启动失败——端口冲突

• 现象：openclaw gateway 启动失败，提示端口被占用

• 原因：默认端口 18789 被其他进程占用

• 解决方案：

bash

# Windows
netstat -ano | findstr :18789
taskkill /PID <进程号> /F

# Linux/macOS
lsof -ti:18789 | xargs kill -9

# 或修改默认端口
openclaw config set gateway.port 新端口

问题 4：模型 API Key 配置错误

• 现象：与机器人对话时，机器人不回复

• 原因：AI 模型的 API Key 配置错误或已过期

• 解决方案：检查并正确配置 API Key

问题 5：依赖下载缓慢或超时（国内网络环境）

• 现象：npm 安装或技能下载时网络超时

• 原因：默认 npm 仓库位于海外，网络连接不稳定

• 解决方案：配置国内 npm 镜像源

bash

npm config set registry https://registry.npmmirror.com
npm config set disturl https://npmmirror.com/mirrors/node/

问题 6：Apple Silicon（M 系列芯片）架构检测错误

• 现象：macOS M 系列芯片上安装 OpenClaw 时，node-llama-cpp 错误地检测为 x64 架构

• 解决方案：

text

# 确认使用原生 arm64 终端
node -e "console.log(process.arch)"   # 应输出 arm64

# 强制指定 arm64 架构重新安装
arch -arm64 npm install -g openclaw

问题 7：访问控制台提示“缺失访问凭证”

• 现象：浏览器访问 Web UI 时提示无访问权限

• 原因：请求未携带有效的 Token

• 解决方案：

text

# 生成新 Token
openclaw token generate

# 浏览器 URL 追加 Token 参数
http://localhost:18789?token=<your-token>

七、总结与扩展建议

本文详细介绍了 OpenClaw 的开源 AI 智能体架构、系统环境要求、三种安装方法、模型配置流程以及常见问题的排查思路。完成上述步骤后，开发者即可获得一个稳定运行的本地 AI 智能体环境，支持文件处理、邮件收发、浏览器自动化等多种任务场景。

为进一步提升 OpenClaw 的使用效率，可关注以下扩展方向：

• 多模型对接：参考故障排查手册，实现多模型负载均衡和故障转移

• 渠道接入：对接微信、飞书、Slack 等平台，实现多渠道统一管理

• Ollama 本地部署：使用 Qwen3.5 等小模型本地推理，实现零 API 成本运行