OpenClaw本地部署保姆级指南：零基础打造专属AI员工

一、项目概述#

1.1 背景与起源#

OpenClaw（曾用名：Clawdbot、Moltbot）是由奥地利开发者 Peter Steinberger 于 2025 年 11 月推出的开源个人 AI 助手项目。该项目在 2026 年初迅速走红，GitHub 星标数突破 169k，成为现象级 AI 工具。

项目诞生源于对传统 AI 助手局限性的思考——大多数 AI 助手仅能提供建议和对话，而无法真正执行任务。OpenClaw 致力于打破这一瓶颈，打造一个”能真正做事的 AI 助手”。

1.2 主要功能#

OpenClaw 是一个自托管的 AI 代理网关，通过用户自己的设备运行，提供以下核心功能：

多渠道统一接入：支持 WhatsApp、Telegram、Slack、Discord、Google Chat、Signal、iMessage、Microsoft Teams、WebChat 等主流通信平台，以及 BlueBubbles、Matrix、Zalo 等扩展渠道
本地化执行能力：可直接访问文件系统、执行 Shell 命令、控制浏览器自动化
语音交互：支持语音唤醒和持续对话模式（适用于 macOS/iOS/Android）
可视化工作区：提供 Live Canvas 功能，AI 可以实时操控可视化界面
技能扩展系统：通过 AgentSkills 平台支持 100+ 技能扩展
自动化任务：支持 Cron 定时任务、Webhook 触发器、Gmail Pub/Sub 等自动化能力

1.3 开发目的#

OpenClaw 的开发目的是为技术背景的用户提供一个：

完全控制权：用户完全拥有数据和 AI 工作流
真正执行：不仅仅是聊天机器人，而是能实际执行任务的数字员工
隐私安全：所有数据默认存储在本地设备（~/.openclaw/ 目录）
高度可扩展：通过技能系统满足个性化需求

1.4 目标用户群体#

OpenClaw 主要面向以下用户群体：

开发者和技术人员：需要自动化日常开发、运维任务的程序员
高级用户：希望通过自然语言控制电脑操作的技术爱好者
个人生产力追求者：希望提升个人效率、自动化重复性任务的用户
隐私敏感用户：不愿将数据上传到云端服务器的用户

二、核心特性#

2.1 技术特点#

本地优先架构#

OpenClaw 采用本地优先的设计理念，所有配置数据、交互历史、会话信息都存储在本地。这种设计确保了数据主权和隐私安全。

Gateway 控制平面#

核心架构采用 Gateway 模式，通过 WebSocket（默认 ws://127.0.0.1:18789）作为统一控制平面，协调所有客户端、工具和事件。这种设计提供了：

统一的会话管理
跨平台的设备配对
中心化的配置管理

Pi Agent 运行时#

集成 Pi Agent 作为默认 AI 运行时，支持：

RPC 模式调用
工具流式传输
块级流式传输
长上下文支持（推荐 Anthropic Opus 4.5）

2.2 创新点#

车道（Lane）抽象机制#

创新采用”车道”抽象管理命令队列：

每个用户会话独占一条串行 Lane
低风险任务可显式分配至并行 Lane
避免传统 async/await 模式的竞态条件问题

长期记忆系统#

通过 Markdown 文件（MEMORY(*).md 或 memory/ 目录）存储用户偏好和关键信息，结合：

SQLite 向量搜索
FTS5 关键词匹配的混合检索机制
实现语义理解和精确查询的平衡

命令白名单机制#

预批准 grep、jq 等安全命令，同时拦截：

命令替换
系统文件重定向
其他危险操作

2.3 与同类工具的差异化优势#

表格

特性	OpenClaw	传统聊天机器人	云端 AI 助手
部署方式	自托管/本地	云端	云端
数据存储	完全本地	云端	云端
执行能力	系统级访问	仅建议	受限执行
多渠道支持	10+ 平台	单一平台	单一平台
扩展性	100+ 技能	有限插件	有限插件
成本	仅 API 调用	订阅制	订阅制
隐私性	完全掌控	第三方控制	第三方控制

三、环境要求#

3.1 硬件环境#

最低配置#

CPU：2 核心处理器
内存：4GB RAM
存储：10GB 可用空间（用于日志、缓存、技能等）

云服务器选项#

如需远程部署，推荐配置：

实例类型：t4g.medium（Graviton ARM）或 t3.medium（x86）
操作系统：Ubuntu 22.04 LTS 或 Debian 12

3.2 软件环境#

核心依赖#

Node.js：≥ 22.0.0（强烈推荐使用最新 LTS 版本）
包管理器：npm、pnpm 或 bun（推荐 pnpm）
操作系统：
- macOS（支持原生应用）
- Linux（推荐 Ubuntu/Debian）
- Windows（仅支持 WSL2，强烈推荐）

可选依赖#

Docker：用于沙箱隔离和容器化部署
Tailscale：用于远程访问和安全隧道
Python 3.8+：某些高级技能可能需要
Chrome/Chromium：浏览器自动化功能

3.3 API 服务配置#

OpenClaw 支持多种 AI 模型提供商，推荐配置：

Anthropic（推荐）#

模型选择：Claude Opus 4.5 或 Claude Sonnet 4.5
订阅要求：Pro 或 Max 订阅（100K 或 200K 上下文）
优势：长上下文支持、更好的注入攻击抵抗能力

OpenAI#

模型选择：GPT-4o、GPT-4o-mini
订阅要求：ChatGPT Plus 或 API 密钥
优势：成本效益好、速度快

其他选项#

Google Gemini
DeepSeek（开源推理模型）
本地模型（通过 Ollama 等）

3.4 网络要求#

出站网络：访问 LLM API 和某些技能的外部服务
端口占用：
- 18789：Gateway WebSocket 接口
- 可根据配置自定义
远程访问：需配置 Tailscale 或 SSH 隧道

四、部署步骤#

4.1 方法一：NPM 全局安装（推荐）#

步骤 1：安装 Node.js#

确保已安装 Node.js ≥ 22：

1
# 检查版本
2
node --version  # 应显示 v22.0.0 或更高
3

4
# 如果未安装，可使用 nvm 安装
5
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
6
nvm install 22
7
nvm use 22

步骤 2：全局安装 OpenClaw#

1
# 使用 npm
2
npm install -g openclaw@latest
3

4
# 或使用 pnpm（推荐）
5
pnpm add -g openclaw@latest
6

7
# 或使用 bun
8
bun install -g openclaw@latest

步骤 3：运行入职向导#

1
openclaw onboard --install-daemon

入职向导将引导你完成以下配置：

安全确认：了解运行 AI 代理的安全最佳实践
模型提供商设置：选择 AI 模型提供商并输入 API 密钥或进行 OAuth 认证
渠道配置：选择并配置消息平台（Slack、Discord、Telegram、WhatsApp 等）
渠道白名单：配置哪些渠道或用户可以与机器人交互
技能设置：启用可选技能（如网页搜索、图像生成等）
Gateway 启动：构建镜像、生成 Gateway 令牌并启动服务

步骤 4：验证安装#

1
# 检查 Gateway 是否运行
2
openclaw gateway status
3

4
# 或直接访问 Web 界面
5
# 默认地址：http://localhost:18789

4.2 方法二：Docker 部署#

步骤 1：拉取镜像#

1
# 拉取官方镜像
2
docker pull openclaw/openclaw:latest
3

4
# 或使用国内镜像（中国用户推荐）
5
docker pull 1186258278/openclaw-zh:latest

步骤 2：创建数据卷#

1
docker volume create openclaw-data

步骤 3：初始化配置#

1
docker run --rm -v openclaw-data:/root/.openclaw \
2
  openclaw/openclaw:latest openclaw setup
3

4
# 配置远程访问（如果需要）
5
docker run --rm -v openclaw-data:/root/.openclaw \
6
  openclaw/openclaw:latest openclaw config set gateway.mode local
7

8
# 设置访问令牌（推荐）
9
docker run --rm -v openclaw-data:/root/.openclaw \
10
  openclaw/openclaw:latest openclaw config set gateway.auth.token your-secure-token

步骤 4：启动容器#

1
docker run -d \
2
  --name openclaw \
3
  -p 18789:18789 \
4
  -v openclaw-data:/root/.openclaw \
5
  --restart unless-stopped \
6
  openclaw/openclaw:latest \
7
  openclaw gateway run

步骤 5：使用 Docker Compose（可选）#

创建 docker-compose.yml 文件：

1
version: '3.8'
2
services:
3
  openclaw:
4
    image: openclaw/openclaw:latest
5
    container_name: openclaw
6
    ports:
7
      - "18789:18789"
8
    volumes:
9
      - openclaw-data:/root/.openclaw
10
    environment:
11
      - OPENCLAW_GATEWAY_TOKEN=your-secure-token
12
      - ANTHROPIC_API_KEY=your-anthropic-api-key
13
    restart: unless-stopped
14

15
volumes:
16
  openclaw-data:

启动服务：

1
docker-compose up -d

4.3 方法三：从源代码构建#

步骤 1：克隆仓库#

1
git clone https://github.com/openclaw/openclaw.git
2
cd openclaw

步骤 2：安装依赖#

1
# 推荐使用 pnpm
2
pnpm install
3

4
# 或使用 bun
5
bun install

步骤 3：构建项目#

1
# 构建 UI（首次运行会自动安装 UI 依赖）
2
pnpm ui:build
3

4
# 构建项目
5
pnpm build

步骤 4：运行入职向导#

1
pnpm openclaw onboard --install-daemon

步骤 5：开发模式（可选）#

1
# 启动开发服务器（自动重载）
2
pnpm gateway:watch

4.4 渠道配置示例#

配置 Telegram#

创建 Telegram 机器人：
- 在 Telegram 中向 @BotFather 发送 /newbot
- 按照提示创建机器人并保存 Bot Token
配置 OpenClaw：

1
# 方法 1：通过环境变量
2
export TELEGRAM_BOT_TOKEN="123456:ABCdefGHIjklMNOpqrsTUVwxyz"
3

4
# 方法 2：通过配置文件
5
nano ~/.openclaw/openclaw.json

在配置文件中添加：

1
{
2
  "channels": {
3
    "telegram": {
4
      "enabled": true,
5
      "botToken": "123456:ABCdefGHIjklMNOpqrsTUVwxyz",
6
      "allowFrom": ["+1234567890"]
7
    }
8
  }
9
}

配置 WhatsApp#

1
# 通过入职向导配置
2
openclaw channels login whatsapp
3

4
# 或手动配置
5
openclaw config set channels.whatsapp.enabled true
6
openclaw config set channels.whatsapp.allowFrom '["+1234567890"]'

配置 Slack#

需要创建 Slack App 并获取 Bot Token 和 App Token：

1
export SLACK_BOT_TOKEN="xoxb-your-bot-token"
2
export SLACK_APP_TOKEN="xapp-your-app-token"

4.5 远程访问配置#

SSH 隧道访问#

1
# 在本地机器上创建 SSH 隧道
2
ssh -N -L 18789:127.0.0.1:18789 user@your-server-ip
3

4
# 然后在浏览器中访问
5
# http://localhost:18789/?token=your-gateway-token

Tailscale 访问#

在服务器上安装 Tailscale
配置 OpenClaw 使用 Tailscale：

1
openclaw config set gateway.tailscale.mode serve
2
openclaw config set gateway.bind loopback

重启 Gateway：

1
docker restart openclaw

Nginx 反向代理（生产环境）#

创建 Nginx 配置文件 /etc/nginx/sites-available/openclaw：

1
server {
2
    listen 443 ssl http2;
3
    server_name openclaw.example.com;
4

5
    ssl_certificate /path/to/cert.pem;
6
    ssl_certificate_key /path/to/key.pem;
7
    ssl_protocols TLSv1.2 TLSv1.3;
8
    ssl_ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256;
9
    ssl_prefer_server_ciphers off;
10

11
    location / {
12
        proxy_pass http://127.0.0.1:18789;
13
        proxy_http_version 1.1;
14

15
        # WebSocket 支持（必须）
16
        proxy_set_header Upgrade $http_upgrade;
17
        proxy_set_header Connection "upgrade";
18

19
        # 转发真实客户端信息
20
        proxy_set_header Host $host;
21
        proxy_set_header X-Real-IP $remote_addr;
22
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
23
        proxy_set_header X-Forwarded-Proto $scheme;
24

25
        # 超时配置
26
        proxy_read_timeout 86400;
27
        proxy_send_timeout 86400;
28
    }
29
}
30

31
# HTTP 重定向到 HTTPS
32
server {
33
    listen 80;
34
    server_name openclaw.example.com;
35
    return 301 https://$server_name$request_uri;
36
}

启用配置：

1
sudo ln -s /etc/nginx/sites-available/openclaw /etc/nginx/sites-enabled/
2
sudo nginx -t
3
sudo systemctl reload nginx

4.6 常见问题解决#

端口被占用#

1
# 检查端口占用
2
netstat -tlnp | grep 18789
3

4
# 修改配置使用其他端口
5
openclaw config set gateway.port 18790

Docker 容器启动失败#

1
# 查看容器日志
2
docker logs -f openclaw
3

4
# 验证 Docker 服务
5
docker run --rm hello-world
6

7
# 检查数据卷权限
8
docker volume inspect openclaw-data

API 密钥认证失败#

1
# 重新运行入职向导
2
openclaw onboard
3

4
# 或手动配置 API 密钥
5
openclaw config set models.providers.anthropic.apiKey "your-api-key"
6

7
# 运行诊断工具
8
openclaw doctor

渠道连接问题#

1
# 检查渠道状态
2
openclaw channels status
3

4
# 重新连接渠道
5
openclaw channels reconnect telegram
6

7
# 查看详细日志
8
openclaw gateway logs --verbose

五、使用示例#

5.1 命令行使用#

发送消息#

1
# 发送消息到指定渠道
2
openclaw message send --to +1234567890 --message "Hello from OpenClaw"
3

4
# 直接与助手对话
5
openclaw agent --message "分析当前系统磁盘使用情况" --thinking high

管理会话#

1
# 列出活动会话
2
openclaw sessions list
3

4
# 重置会话
5
openclaw sessions reset
6

7
# 压缩会话上下文
8
openclaw sessions compact

5.2 WebChat 界面使用#

在浏览器中访问： http://localhost:18789
输入 Gateway Token（如果已配置）
开始与助手对话

5.3 聊天平台使用#

Telegram 示例#

在 Telegram 中找到你的机器人
发送消息：“帮我分析这个 GitHub 仓库的代码结构”
OpenClaw 将自动执行相关操作并返回结果

WhatsApp 示例#

在 WhatsApp 中向你的号码发送消息
输入：“整理我的收件箱，标记重要邮件”
OpenClaw 将执行邮件整理任务

5.4 自动化任务示例#

Cron 定时任务#

1
# 每天早上 8 点发送天气报告
2
openclaw cron create "0 8 * * *" "今天的天气如何？"
3

4
# 每周一生成周报
5
openclaw cron create "0 9 * * 1" "生成本周工作总结"

Webhook 触发器#

1
# 创建 webhook
2
openclaw webhook create my-webhook "处理收到的数据"
3

4
# 查看 webhook URL
5
openclaw webhook list

5.5 技能使用示例#

安装技能#

1
# 从 ClawHub 安装技能
2
openclaw skills install weather
3

4
# 列出已安装技能
5
openclaw skills list

使用技能#

在聊天中直接调用：

“天气怎么样？“（天气技能）

“搜索最新的 AI 新闻”（网页搜索技能）

“生成项目文档”（文档生成技能）

5.6 高级使用示例#

浏览器自动化#

1
# 在聊天中输入
2
"打开 example.com 网站，截图并告诉我首页有什么内容"
3

4
# OpenClaw 将自动：
5
# 1. 启动浏览器
6
# 2. 导航到指定网站
7
# 3. 截图
8
# 4. 分析页面内容

文件操作#

1
# 在聊天中输入
2
"查找 /home/user/documents 目录下所有 PDF 文件，并创建摘要"
3

4
# OpenClaw 将执行文件搜索和内容分析

代码执行#

1
# 在聊天中输入
2
"运行 tests 目录下的所有测试，并生成报告"
3

4
# OpenClaw 将执行测试并返回结果

六、注意事项#

6.1 安全考量#

权限管理#

OpenClaw 需要广泛的系统权限才能执行任务，必须谨慎配置：

默认安全策略：
- 主会话：工具在主机上运行，代理拥有完全访问权限
- 群组/频道会话：启用沙箱模式，在 Docker 容器中运行
配置沙箱模式：

1
{
2
  "agents": {
3
    "defaults": {
4
      "sandbox": {
5
        "mode": "non-main"
6
      }
7
    }
8
  }
9
}

白名单配置：

1
{
2
  "channels": {
3
    "whatsapp": {
4
      "allowFrom": ["+1234567890"]
5
    },
6
    "telegram": {
7
      "allowFrom": ["@username"]
8
    }
9
  }
10
}

网络安全#

切勿将 Gateway 端口（18789）直接暴露到公网
使用 SSH 隧道、Tailscale 或 VPN 进行远程访问
配置防火墙规则：

1
# Ubuntu/Debian
2
sudo ufw allow ssh
3
sudo ufw deny 18789
4
sudo ufw enable

API 密钥安全#

不要在公共代码仓库中提交 API 密钥
定期轮换 API 密钥
使用环境变量存储敏感信息：

1
export ANTHROPIC_API_KEY="your-api-key"
2
export OPENAI_API_KEY="your-openai-key"

技能安全#

仅安装来自可信来源的技能
审查技能代码后再安装
启用技能安装门控：

1
{
2
  "tools": {
3
    "skills": {
4
      "installGating": true
5
    }
6
  }
7
}

6.2 隐私保护#

数据本地化#

所有数据默认存储在 ~/.openclaw/ 目录
确保该目录权限正确：

1
chmod 700 ~/.openclaw

日志管理#

定期清理日志文件：

1
# 查看日志大小
2
du -sh ~/.openclaw/logs
3

4
# 清理旧日志
5
openclaw logs clean --days 7

会话管理#

定期重置敏感会话
使用会话压缩减少上下文大小
配置会话修剪策略：

1
{
2
  "agents": {
3
    "defaults": {
4
      "sessionPruning": {
5
        "enabled": true,
6
        "maxTokens": 100000,
7
        "keepSummary": true
8
      }
9
    }
10
  }
11
}

6.3 性能优化#

模型选择#

成本优化：使用 GPT-4o-mini 进行日常任务
质量优化：使用 Claude Opus 4.5 处理复杂任务
配置模型故障转移：

1
{
2
  "models": {
3
    "failover": {
4
      "providers": ["anthropic", "openai"],
5
      "strategy": "cost"
6
    }
7
  }
8
}

资源限制#

配置 Docker 资源限制（如使用容器部署）：

1
version: '3.8'
2
services:
3
  openclaw:
4
    # ... 其他配置
5
    deploy:
6
      resources:
7
        limits:
8
          cpus: '2'
9
          memory: 4G
10
        reservations:
11
          cpus: '1'
12
          memory: 2G

缓存优化#

启用响应缓存
配置媒体文件大小限制：

1
{
2
  "channels": {
3
    "discord": {
4
      "mediaMaxMb": 10
5
    }
6
  }
7
}

6.4 监控与维护#

健康检查#

1
# 运行诊断工具
2
openclaw doctor
3

4
# 检查 Gateway 状态
5
openclaw gateway status
6

7
# 查看资源使用
8
openclaw gateway stats

日志监控#

1
# 实时查看日志
2
openclaw gateway logs --follow
3

4
# 查看错误日志
5
openclaw gateway logs --level error

更新维护#

1
# 检查更新
2
openclaw update --check
3

4
# 执行更新
5
openclaw update
6

7
# 切换到不同频道
8
openclaw update --channel stable|beta|dev

6.5 最佳实践建议#

部署建议#

生产环境：使用 Docker 容器化部署
开发环境：使用 npm 全局安装便于调试
远程部署：使用 Tailscale 或 VPN，避免直接暴露端口
高可用性：考虑使用进程管理器（systemd、supervisor）守护进程

使用建议#

渐进式配置：从基本功能开始，逐步启用高级功能
测试优先：在主环境使用前，先在测试环境验证
备份重要配置：定期备份 ~/.openclaw/ 目录
文档记录：记录自定义配置和技能

团队协作#

权限分离：为不同用户配置不同权限
会话隔离：使用不同的会话处理不同任务
审计日志：启用详细日志记录以供审计
技能共享：通过 ClawHub 共享自定义技能

6.6 故障排除清单#

遇到问题时，按以下步骤排查：

检查服务状态：

1
openclaw gateway status

验证配置：

1
openclaw doctor

查看日志：

1
openclaw gateway logs --verbose

测试网络连接：

1
curl https://api.anthropic.com

验证 API 密钥：

1
openclaw config get models.providers.anthropic.apiKey

检查渠道连接：

1
openclaw channels status

重启服务：

openclaw gateway restart

结语#

OpenClaw 代表了个人 AI 助手的新范式——从被动的建议者转变为主动的执行者。通过本指南，你应该能够成功部署和使用这个强大的工具。记住，能力越大，责任越大。在享受 AI 带来的便利的同时，务必重视安全和隐私保护。

随着项目的持续发展，建议定期关注官方文档和社区动态，以获取最新的功能和最佳实践。祝你使用愉快！🦞

音乐