前言

随着 AI 智能体技术与大模型的快速发展，本地部署、可自定义的 AI 协作框架越来越受更多人的青睐。OpenClaw 是一个开源的 AI 智能体框架，能够将 LLM 模型转化为可执行任务的“数字员工”，支持对接主流大模型 API、集成飞书/钉钉等即时通讯渠道、实现多角色智能体协同，适合用于构建个人 AI 助理、企业级智能客服、实验流程自动化等场景。本系列文章将从0到1逐步深入，帮助读者了解并使用 OpenClaw。本文作为系列开篇，聚焦 Windows、MacOS、Linux 三平台的一键安装、初始化配置以及常见问题排错，内容基于官方文档与实战经验。

一、前置准备

1.1 系统要求

操作系统	版本要求
Windows	Windows 10（64位）或 Windows 11
MacOS	11.0 (Big Sur) 或更高版本
Linux	Ubuntu 20.04 / 22.04 或其他主流发行版

1.2 硬件要求

• 内存：至少 4 GB（推荐 8 GB）
• 磁盘空间：至少 10 GB 可用空间
• 网络：安装过程中需联网下载安装包

1.3 核心依赖

OpenClaw 运行需要以下环境支持：

• Node.js：22.x 或更高版本
• Git：用于版本管理和依赖下载

💡 提示：使用下方的一键安装脚本会自动检测并安装这些依赖，无需手动操作

二、Windows 10/11 安装步骤

2.1 一键安装

1. 打开Windows PowerShell (管理员)：右键点击开始按钮
2. 执行一键安装命令：

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

3. 若提示在此系统上禁止运行脚本，先执行以下命令解锁，再执行一键安装命令：

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

4. 等待安装完成。系统会自动完成 OpenClaw 的全局安装，安装时间可能因安装方式、系统环境和配置需求的不同而有较大差异‌

5. 验证安装

# 检查版本号，如正常显示版本号，说明 CLI 已注册成功
openclaw --version 

# 检查 gateway 是否正在运行       
openclaw gateway status   

2.2 运行初始化向导

安装完成后，执行以下命令启动交互式配置向导：

openclaw onboard --install-daemon

向导会引导您完成以下配置：

• 安全提示确认：阅读风险提示后选择确认
• 模式选择：推荐选择 QuickStart（快速启动）
• 模型配置：选择大模型提供商（如DeepSeek、通义千问等），按提示完成 API Key 配置，或选择 Skip for now 跳过，后续随时添加
• 工作区：默认 ~/.openclaw/workspace
• Gateway 网关：端口、绑定地址、认证模式等
• 渠道：Telegram、WhatsApp等，可先选择 Skip for now 跳过
• 健康检查：启动 Gateway 网关，并验证其正在运行
• Skills：可先选择 Skip for now 跳过

2.3 打开管理控制台

# 执行以下指令，会在默认浏览器中打开
openclaw dashboard

2.4 启动服务并验证

# 启动网关服务（如果没启动时）
openclaw gateway start

# 快速启动并访问管理控制台，用于无浏览器弹窗的场景
openclaw dashboard --no-open

复制终端上面 Dashboard URL 后面的地址，可能如下

Dashboard URL: http://127.0.0.1:18789/#token=您的Token

在浏览器上打开复制的地址，如果看到 OpenClaw 管理界面即表示安装成功

2.5 允许设备访问

# 查询访问设备，获取 requestId
openclaw devices list

# 允许请求的设备通过访问
openclaw devices approve <requestId>

三、MacOS 安装步骤

3.1 一键安装

打开 终端（Terminal），执行以下命令：

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

3.2 运行初始化向导

openclaw onboard --install-daemon

按提示完成配置（同 Windows 部分）

3.3 启动服务并验证

# 后台启动网关服务
nohup openclaw gateway start &

# 用默认浏览器打开管理控制台
openclaw dashboard

如果看到 OpenClaw 管理界面即表示安装成功

四、Linux（Ubuntu）安装步骤

4.1 安装依赖

打开终端，执行以下命令安装必要工具：

# 更新本地软件包列表
sudo apt update

# 安装依赖包
sudo apt install -y curl git

4.2 一键安装 OpenClaw

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

4.3 运行初始化向导

openclaw onboard --install-daemon

按提示完成配置（同 Windows 部分）

4.4 启动服务并验证

# 设置开机自启（可选）
sudo systemctl enable openclaw

# 启动网关服务
openclaw gateway start

# 用默认浏览器打开管理控制台
openclaw dashboard

如果看到 OpenClaw 管理界面即表示安装成功

五、常见问题与解决方法

问题	可能原因	解决方法
Node.js 版本过低	系统版本低于22	使用 nvm 安装 Node.js 22+ => nvm install 22
安装脚本执行失败	网络连接问题	检查网络，或配置代理后重试
国内下载速度慢	GitHub 访问受限	已使用国内镜像源，但是仍有问题可尝试科学上网
端口 18789 被占用	其他程序占用端口	更换端口 => openclaw gateway --port 18790
Token 生成失败	网关未启动	先重启网关再生成 Token => openclaw gateway start
模型 API 调用失败	API Key 配置错误	重新配置模型 => openclaw onboard

六、常用运维命令

# 启动网关服务
openclaw gateway start

# 重启网关服务
openclaw gateway restart

# 查看网关服务状态
openclaw gateway status

# 查看运行日志
openclaw logs --follow

# 查看整体状态，包括版本、内存、会话等
openclaw status

# 检查系统健康状态
openclaw doctor

# 极简健康状态，ok/error
openclaw health         

# 更新到最新版本
openclaw update

# 检查模型认证状态
openclaw models status

# 渠道专属日志
openclaw channels logs --channel feishu

七、安装 Skills 技能

OpenClaw 的核心能力来源于技能插件。安装完成后，建议按以下顺序安装相关技能：

基础设施：建议安装

# 安全审查工具
npx clawhub@latest install skill-vetter

# 智能搜索接口
npm install @tavily/core

效能提升：视具体情况而定

# 智能推荐技能
npx clawhub@latest install find-skills

# 持续从经验中学习、自我优化
npx clawhub@latest install self-improving-agent

八、获取帮助

若在安装或使用过程中遇到问题，可通过以下方式获取支持：

• 官方文档：openclaw.ai
• 中文社区版文档：clawcn.net
• GitHub 仓库：github.com/openclaw/openclaw
• 交流社区：虾聊社区 xialiao.ai

---

📌 说明

本文为原创技术实操记录，部分内容由 AI 辅助生成，已由作者深度校验与优化。文中操作仅用于技术学习交流，使用前请做好数据备份，谨慎部署，相关风险由使用者自行承担。

⚠️ 风险提示：OpenClaw 具有完整的系统访问权限，能够读写文件、执行命令。建议安装来源可信的 Skills，并定期审查已安装的技能