OpenClaw 完整安装指南

OpenClaw 完整安装指南

一、什么是 OpenClaw？

OpenClaw 是一个开源的主动式个人 AI 助手，它能够将 AI 模型与本地消息应用（如 WhatsApp、Discord 等）连接，实现 24 小时自动化的任务处理。这个项目前身名为 Moltbot/Clawdbot，是一个基于 TypeScript 的大型项目，代码量超过 50 万行。

主要特性

• 🤖 主动式 AI 助手，能主动识别并执行任务
• 🔗 支持多种消息平台接入
• 🛠️ 提供 25+ 种工具和 53+ 官方技能
• 🐳 支持 Docker 容器化部署
• 🔒 支持沙箱隔离，保证安全性

二、系统要求

2.1 最低配置

• CPU: ≥ 2 核
• 内存: ≥ 4GB
• 磁盘空间: ≥ 10GB

2.2 必备工具

• Node.js: ≥ 22（建议使用 v24）
• Git: 最新版本
• Docker: 可选，但推荐用于沙箱隔离（Docker Engine 24+ 或 Docker Desktop 4.25+）

2.3 可选组件

• FFmpeg（语音处理）
• Chromium（浏览器自动化）

三、安装前准备

3.1 检查 Node.js 版本

在终端执行：

node-v

如果版本不足 v22，可以通过以下方式升级：

• 使用 nvm:nvm install 24
• 使用 fnm:fnm install 24
• 使用 brew(Mac):brew install node@24

3.2 安装 Git

• Windows: 访问 https://git-scm.com/ 下载安装
• Linux:sudo apt install git或sudo yum install git
• Mac:brew install git

3.3 安装 Docker（可选但推荐）

• Windows: 下载 Docker Desktop
• Linux: 安装 Docker Engine 24+
• Mac: 安装 Docker Desktop 4.25+

验证 Docker 安装：

docker--versiondockerps

四、安装方法

OpenClaw 提供三种官方支持的部署方式，根据你的需求选择：

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

Windows 安装

使用管理员权限打开 PowerShell：

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

macOS/Linux 安装

curl-fsSLhttps://openclaw.ai/install.sh|bash

安装步骤

1. 执行安装命令后，会启动安装向导
2. 选择QuickStart快速安装模式
3. 按照提示完成配置：
   • 设置 OpenClaw 工作目录
   • 配置 AI 模型 API Key（支持多种模型提供商）
   • 选择需要启用的技能和工具
4. 等待安装完成，系统会自动启动服务

优点: 安装简单，适合快速体验
缺点: 定制化程度较低

方案二：Docker Compose 部署（推荐生产环境）

4.1 创建专用用户（Linux）

为避免权限混乱并实现数据隔离：

# 创建用户及其主目录sudouseradd-mnode# 将用户加入 docker 组（管理容器）和 sudo 组（系统管理）sudousermod-aGdockernodesudousermod-aGsudonode# 切换到 node 用户su-node

4.2 下载配置文件

# 克隆项目gitclone https://github.com/openclaw/openclaw.gitcdopenclaw# 复制示例配置文件cpsettings.yaml.example settings.yaml

4.3 配置 settings.yaml

编辑settings.yaml文件，配置以下关键参数：

# AI 模型配置llm:provider:"openai"# 可选: openai, anthropic, azure, localapiKey:"your-api-key-here"model:"gpt-4"# 消息平台配置platforms:discord:enabled:truetoken:"your-discord-bot-token"whatsapp:enabled:false# 工具和技能配置tools:web_search:enabled:truefile_management:enabled:trueskills:auto_load:true

4.4 启动服务

# 构建并启动容器docker-composeup-d# 查看日志docker-composelogs-f

优点:

• 全容器化，环境一致
• 隔离性好，安全性高
• 适合生产环境部署

方案三：NPM 安装（推荐本地开发）

4.1 全局安装

npminstall-gopenclaw

4.2 初始化配置

# 创建配置目录mkdir-p~/.openclawcd~/.openclaw# 初始化配置openclaw init

4.3 配置环境变量

在项目根目录创建.env文件：

OPENCLAW_API_KEY=your-api-key OPENCLAW_MODEL=gpt-4 OPENCLAW_DISCORD_TOKEN=your-discord-token OPENCLAW_PORT=18789

4.4 启动服务

# 开发模式（支持热重载）openclaw dev# 生产模式openclaw start

优点:

• 热重载友好，调试方便
• 可以直接查看调试信息
• 适合开发者本地调试

五、配置 AI 模型

OpenClaw 支持多种 AI 模型提供商：

5.1 OpenAI

llm:provider:"openai"apiKey:"sk-..."model:"gpt-4"temperature:0.7

5.2 Anthropic (Claude)

llm:provider:"anthropic"apiKey:"sk-ant-..."model:"claude-3-opus-20240229"

5.3 阿里云百炼（国内推荐）

llm:provider:"aliyun"apiKey:"your-aliyun-api-key"model:"qwen-max"

5.4 本地模型 (Ollama)

llm:provider:"local"baseUrl:"http://localhost:11434"model:"llama2"

六、端口配置和防火墙

OpenClaw 默认使用18789端口。

6.1 Linux 防火墙配置

# UFW (Ubuntu)sudoufw allow18789/tcpsudoufw reload# firewalld (CentOS)sudofirewall-cmd--permanent--add-port=18789/tcpsudofirewall-cmd--reload

6.2 云服务器安全组

如果使用阿里云、腾讯云等云服务器，需要在安全组中放通 18789 端口。

七、连接消息平台

7.1 Discord 接入

1. 访问 Discord Developer Portal
2. 创建新应用，获取 Bot Token
3. 在配置文件中添加：

platforms:discord:enabled:truetoken:"your-bot-token"clientId:"your-client-id"

7.2 WhatsApp 接入

需要接入 WhatsApp Business API：

platforms:whatsapp:enabled:truephoneNumberId:"your-phone-number-id"accessToken:"your-access-token"

7.3 企业微信接入（国内推荐）

platforms:wechat:enabled:truecorpId:"your-corp-id"agentSecret:"your-agent-secret"token:"your-token"encodingAesKey:"your-aes-key"

八、常用命令

8.1 服务管理

# 启动服务openclaw start# 停止服务openclaw stop# 重启服务openclaw restart# 查看状态openclaw status

8.2 日志查看

# 实时日志openclaw logs# 最近 100 行日志openclaw logs-n100# 持续监控日志openclaw logs-f

8.3 配置管理

# 重新加载配置openclaw reload# 验证配置openclaw config validate

九、常见问题排查

问题 1：端口被占用

# 检查端口占用netstat-tuln|grep18789# Linux/Macnetstat-ano|findstr18789# Windows# 修改端口# 编辑 settings.yaml，修改 port 配置port:18888

问题 2：Docker 权限错误

# 将用户添加到 docker 组sudousermod-aGdocker$USER# 重新登录或执行newgrpdocker

问题 3：Node.js 版本不兼容

# 使用 nvm 切换版本nvm use24# 或指定 Node 版本nvmaliasdefault24

问题 4：API Key 无效

• 检查 API Key 是否正确复制
• 确认 API Key 有效且未过期
• 检查账户余额是否充足

十、性能优化建议

10.1 内存优化

如果服务器内存较小，可以：

1. 减少启用的技能数量
2. 使用轻量级模型（如 GPT-3.5-turbo）
3. 调整并发处理数量

10.2 网络优化

• 国内用户建议使用阿里云百炼或本地模型
• 配置代理加速访问 OpenAI API
• 使用 CDN 加速静态资源

10.3 Docker 资源限制

# docker-compose.yml 中添加services:openclaw:deploy:resources:limits:cpus:'2'memory:4G

十一、安全建议

11.1 保护 API Key

• 将 API Key 存储在环境变量中
• 不要将.env文件提交到 Git
• 定期轮换 API Key

11.2 网络安全

• 使用反向代理（Nginx）配置 HTTPS
• 限制访问 IP 白名单
• 配置防火墙规则

11.3 数据隔离

• 使用专用用户运行 OpenClaw
• Docker 部署时使用网络隔离
• 定期备份数据目录

十二、进阶配置

12.1 自定义技能

在~/.openclaw/skills目录创建自定义技能：

// my-custom-skill.tsexportdefault{name:'My Custom Skill',description:'A custom skill for my needs',execute:async(context)=>{// 你的逻辑return'Hello from custom skill!';}};

12.2 配置定时任务

schedules:-name:daily_backupcron:"0 2 * * *"action:backup_data-name:hourly_synccron:"0 * * * *"action:sync_data

12.3 集成第三方服务

OpenClaw 可以通过工具集成各种第三方服务：

• 数据库（PostgreSQL、MongoDB）
• 对象存储（阿里云 OSS、腾讯云 COS）
• 消息队列（Redis、RabbitMQ）

十三、总结

OpenClaw 是一个功能强大的开源 AI 助手，通过本教程，你应该能够：

✅ 了解 OpenClaw 的基本概念和特性
✅ 根据需求选择合适的安装方式
✅ 完成基础配置和部署
✅ 接入消息平台并开始使用
✅ 解决常见问题
✅ 进行性能优化和安全加固

部署方案选择建议

下一步

• 探索 OpenClaw 的 25+ 工具和 53+ 官方技能
• 根据需求配置自定义技能
• 加入 OpenClaw 社区交流经验

参考资源

• 🌐 官方网站: https://clawd.bot/
• 📚 GitHub 仓库: https://github.com/openclaw/openclaw
• 📖 官方文档: https://docs.openclaw.ai/
• 💬 社区论坛: https://community.openclaw.ai/

教程版本: v1.0
更新日期: 2026 年 3 月 10 日
OpenClaw 版本: 最新稳定版

如有问题或建议，欢迎在评论区留言讨论！