🦞 OpenClaw — 个人 AI 助手

剥壳小龙虾!

📚 目录

📖 项目简介
✨ 核心特性
🏗️ 工作原理
🔧 架构详解
📦 安装部署
⚙️ 配置说明
🚀 快速开始
🔒 安全性
🤝 贡献指南
📄 许可证

📖 项目简介

OpenClaw 是一个运行在您自己设备上的个人 AI 助手网关系统。它可以让您通过日常使用的聊天应用(WhatsApp、Telegram、Slack、Discord、Google Chat、Signal、iMessage、BlueBubbles、IRC、Microsoft Teams、Matrix 等)与 AI 助手进行交互。

🎯 适用对象

🧑‍💻 希望拥有私人 AI 助手的开发者
🔐 重视数据隐私和本地控制的用户
🌟 需要多渠道统一 AI 接入的团队

🌈 核心优势

🏠 本地部署: 完全运行在您的硬件上,您拥有完全控制权
🔗 多渠道支持: 单一网关同时服务于多个消息平台
🤖 智能体原生: 专为 AI 编码智能体设计,支持工具使用、会话管理和多智能体路由
🔓 开源免费: MIT 许可证,社区驱动

📋 系统要求

Node.js: 版本 ≥ 22
模型提供商 API 密钥: 支持 OpenAI、Anthropic、Gemini、OpenRouter 等
⏱️ 安装时间: 约 5 分钟

💡 推荐: 为获得最佳体验和更低的提示注入风险,请使用您可用的最强大的最新一代模型。

✨ 核心特性

🌐 多渠道消息接入

OpenClaw 支持以下消息平台:

平台	状态	说明
📱 WhatsApp	✅ 支持	通过 Baileys
✈️ Telegram	✅ 支持	通过 grammY
💬 Slack	✅ 支持	通过 Bolt
🎮 Discord	✅ 支持	通过 discord.js
💼 Google Chat	✅ 支持	Chat API
🔔 Signal	✅ 支持	signal-cli
💙 iMessage	✅ 支持	BlueBubbles (推荐) / 传统 imsg
🖥️ IRC	✅ 支持	-
👥 Microsoft Teams	✅ 支持	-
🔷 Matrix	✅ 支持	-
🐦 其他平台	✅ 支持	Feishu, LINE, Mattermost, Nextcloud Talk, Nostr, Synology Chat, Tlon, Twitch, Zalo 等

🛠️ 强大的工具生态

🌍 浏览器控制: 专用的 OpenClaw Chrome/Chromium,支持快照、操作、上传和配置文件
🎨 实时画布: 智能体驱动的可视化工作区,支持 A2UI
📱 节点功能: 相机拍照/录像、屏幕录制、位置获取、通知
⏰ 定时任务与唤醒: 支持 Cron 作业、Webhook 和 Gmail Pub/Sub
🔌 技能平台: 内置、托管和工作区技能,支持安装门控和 UI

🎤 语音与多模态

🗣️ 语音唤醒: macOS/iOS 上的唤醒词检测
💬 对话模式: Android 上的持续语音交互
🎙️ TTS 支持: ElevenLabs、OpenAI 和系统 TTS 回退

📱 配套应用

🍎 macOS 应用: 菜单栏控制面板,语音唤醒/推送通话,WebChat,调试工具
📲 iOS 节点: 画布、语音唤醒、对话模式、相机、屏幕录制
🤖 Android 节点: 连接选项卡、聊天会话、语音选项卡、画布、相机/屏幕录制

🏗️ 工作原理

系统架构图

graph TB
    subgraph 消息平台
        A1[WhatsApp]
        A2[Telegram]
        A3[Slack]
        A4[Discord]
        A5[其他平台...]
    end
    
    subgraph Gateway 网关
        B[WebSocket 控制平面<br/>ws://127.0.0.1:18789]
        B1[会话管理]
        B2[路由引擎]
        B3[工具注册表]
    end
    
    subgraph AI 智能体
        C[Pi Agent RPC]
        C1[工具执行]
        C2[上下文管理]
        C3[流式响应]
    end
    
    subgraph 客户端
        D1[CLI 命令行]
        D2[Web 控制 UI]
        D3[macOS 应用]
        D4[移动节点]
    end
    
    A1 --> B
    A2 --> B
    A3 --> B
    A4 --> B
    A5 --> B
    
    B --> B1
    B --> B2
    B --> B3
    
    B --> C
    C --> C1
    C --> C2
    C --> C3
    
    B --> D1
    B --> D2
    B --> D3
    B --> D4
    
    style B fill:#4a9eff,stroke:#333,stroke-width:3px,color:#fff
    style C fill:#ff6b6b,stroke:#333,stroke-width:2px,color:#fff

数据流程

sequenceDiagram
    participant U as 用户
    participant C as 消息平台
    participant G as Gateway
    participant A as Pi Agent
    participant T as 工具系统
    
    U->>C: 发送消息
    C->>G: 转发到 WebSocket
    G->>G: 会话路由
    G->>A: 调用智能体
    A->>A: 理解意图
    A->>T: 执行工具调用
    T-->>A: 返回结果
    A->>A: 生成响应
    A-->>G: 流式返回
    G-->>C: 格式化消息
    C-->>U: 显示回复

🔧 架构详解

核心组件

1. 🌐 Gateway (网关)

Gateway 是 OpenClaw 的核心控制平面,负责:

🔌 连接管理: 维护所有消息平台的长连接
🛣️ 消息路由: 根据规则将消息路由到相应的智能体
🔐 认证授权: 处理用户身份验证和权限控制
📊 会话管理: 跟踪和管理所有活动会话
🎯 事件分发: 向订阅的客户端分发事件

技术实现:

// Gateway 启动示例
const gateway = await startGatewayServer(port, {
  bind: 'loopback',        // 绑定模式: loopback/lan/tailnet
  auth: {
    mode: 'token',         // 认证模式: token/password/none
    token: process.env.OPENCLAW_GATEWAY_TOKEN
  },
  tailscale: {
    mode: 'off'            // Tailscale 模式: off/serve/funnel
  }
});

2. 🤖 Pi Agent 集成

OpenClaw 使用 Pi SDK 嵌入 AI 编码智能体:

核心包依赖:

{
  "@mariozechner/pi-agent-core": "0.49.3",
  "@mariozechner/pi-ai": "0.49.3",
  "@mariozechner/pi-coding-agent": "0.49.3",
  "@mariozechner/pi-tui": "0.49.3"
}

功能特性:

✅ 完全控制会话生命周期和事件处理
✅ 自定义工具注入(消息、沙箱、特定渠道操作)
✅ 按渠道/上下文自定义系统提示
✅ 支持分支和压缩的会话持久化
✅ 多账户认证配置文件轮换与故障转移
✅ 与提供商无关的模型切换

3. 📁 工作区系统

工作区是智能体的”家”,是所有文件工具和工作区上下文的工作目录。

默认位置: ~/.openclaw/workspace

核心文件:

文件	用途	加载时机
`AGENTS.md`	智能体操作指南和内存使用方式	每次会话启动
`SOUL.md`	角色、语气和边界设定	每次会话启动
`USER.md`	用户信息和沟通方式	每次会话启动
`IDENTITY.md`	智能体名称、风格和表情符号	引导仪��时创建/更新
`TOOLS.md`	本地工具和约定说明	仅作指导,不控制工具可用性
`HEARTBEAT.md`	可选的心跳运行检查清单	心跳任务
`BOOT.md`	可选的启动检查清单	网关重启时(启用内部钩子)
`BOOTSTRAP.md`	一次性首次运行仪式	仅全新工作区创建

目录结构示例:

~/.openclaw/workspace/
├── AGENTS.md           # 智能体指令
├── SOUL.md            # 个性设定
├── USER.md            # 用户信息
├── IDENTITY.md        # 身份标识
├── TOOLS.md           # 工具说明
├── skills/            # 技能目录
│   └── <skill>/
│       └── SKILL.md
└── .git/              # 推荐使用 Git 备份

4. 🛡️ 沙箱系统

OpenClaw 提供可选的 Docker 沙箱隔离,用于在隔离环境中执行不受信任的代码:

隔离模式:

off: 无沙箱,所有工具在主机上运行
always: 始终使用沙箱
non-main: 仅对非主会话(群组/频道)使用沙箱

配置示例:

{
  agents: {
    defaults: {
      sandbox: {
        mode: "non-main",           // 隔离模式
        scope: "session",           // 沙箱范围: session/global
        workspaceAccess: "none",    // 工作区访问: none/ro/rw
        docker: {
          image: "openclaw-sandbox",
          network: "none",          // 网络隔离
          readOnlyRoot: true,       // 只读根文件系统
          memory: "512m",           // 内存限制
          cpus: "1.0"              // CPU 限制
        }
      }
    }
  }
}

5. 🔐 认证与授权

支持的认证模式:

模式	说明	适用场景
`token`	共享令牌认证	默认模式,适合本地/远程访问
`password`	密码认证	Tailscale Funnel 或公网访问
`trusted-proxy`	可信代理认证	反向代理后端
`none`	无认证(仅 loopback)	开发环境

配置示例:

{
  gateway: {
    auth: {
      mode: "token",
      token: "${OPENCLAW_GATEWAY_TOKEN}",
      rateLimit: {
        maxAttempts: 10,           // 最大失败尝试次数
        windowMs: 60000,           // 滑动窗口(1分钟)
        lockoutMs: 300000,         // 锁定时长(5分钟)
        exemptLoopback: true       // 本地回环免除限制
      }
    }
  }
}

工作流程详解

消息处理流程

flowchart TD
    A[用户发送消息] --> B{平台类型}
    B -->|WhatsApp| C1[Baileys 客户端]
    B -->|Telegram| C2[grammY Bot]
    B -->|Discord| C3[discord.js]
    B -->|其他| C4[相应客户端]
    
    C1 --> D[Gateway 消息队列]
    C2 --> D
    C3 --> D
    C4 --> D
    
    D --> E{会话路由}
    E -->|DM| F1[主会话]
    E -->|群组提及| F2[群组会话]
    E -->|多智能体| F3[特定智能体]
    
    F1 --> G[Pi Agent 处理]
    F2 --> G
    F3 --> G
    
    G --> H{需要工具?}
    H -->|是| I[工具执行]
    H -->|否| J[直接响应]
    
    I --> K{沙箱模式?}
    K -->|是| L[Docker 容器执行]
    K -->|否| M[主机执行]
    
    L --> N[合并结果]
    M --> N
    J --> N
    
    N --> O[格式化响应]
    O --> P[发送回原平台]
    P --> Q[用户收到回复]

工具执行流程

sequenceDiagram
    participant A as Agent
    participant G as Gateway
    participant T as Tool Registry
    participant S as Sandbox
    participant H as Host
    
    A->>G: 请求工具调用
    G->>T: 查找工具定义
    T-->>G: 返回工具配置
    
    alt 沙箱模式启用
        G->>S: 创建隔离环境
        S->>S: 执行工具代码
        S-->>G: 返回结果
    else 主机模式
        G->>H: 直接执行
        H-->>G: 返回结果
    end
    
    G-->>A: 返回工具结果

📦 安装部署

💻 本地命令行安装

系统要求

操作系统: macOS、Linux 或 Windows (通过 WSL2,强烈推荐)
Node.js: 版本 ≥ 22
包管理器: npm、pnpm 或 bun

快速安装

1️⃣ 使用 npm 全局安装

1
2
3

npm install -g openclaw@latest
# 或使用 pnpm
pnpm add -g openclaw@latest

2️⃣ 运行入门向导

1	openclaw onboard --install-daemon

向导会引导您完成:

✅ Gateway 配置
✅ 工作区设置
✅ 消息渠道配置
✅ 技能安装
✅ 系统守护进程安装(launchd/systemd)

3️⃣ 启动 Gateway

# 前台运行(带详细日志)
openclaw gateway --port 18789 --verbose

# 或使用守护进程
openclaw gateway start

4️⃣ 验证安装

# 检查健康状态
openclaw health

# 查看系统状态
openclaw status

# 运行诊断
openclaw doctor

从源码构建(开发模式)

# 克隆仓库
git clone https://github.com/openclaw/openclaw.git
cd openclaw

# 安装依赖(推荐使用 pnpm)
pnpm install

# 构建 UI
pnpm ui:build

# 构建项目
pnpm build

# 运行入门向导
pnpm openclaw onboard --install-daemon

# 开发模式(自动重载)
pnpm gateway:watch

💡 提示: pnpm openclaw ... 通过 tsx 直接运行 TypeScript。pnpm build 生成 dist/ 目录,用于通过 Node 或打包的 openclaw 二进制文件运行。

🐳 Docker 容器部署

OpenClaw 提供了完整的 Docker 部署方案,包括自动化安装脚本和手动配置两种方式。

方式一: 一键自动部署(推荐)

OpenClaw 提供了功能完整的自动化部署脚本 docker-setup.sh,会自动完成所有配置和启动流程。

1️⃣ 克隆仓库

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

2️⃣ 运行部署脚本

# 基础部署(不启用沙箱)
bash docker-setup.sh

# 启用沙箱隔离(推荐用于生产环境)
OPENCLAW_SANDBOX=1 bash docker-setup.sh

3️⃣ 脚本会自动完成以下操作

✅ 环境检查: 验证 Docker 和 Docker Compose 安装
✅ 目录创建: 自动创建配置和工作区目录
✅ 令牌生成: 自动生成安全的 Gateway 认证令牌
✅ 镜像构建: 构建或拉取 OpenClaw Docker 镜像
✅ 权限设置: 自动修复容器内文件权限
✅ 交互式配置: 运行 onboard 向导设置智能体
✅ Gateway 启动: 自动启动 Gateway 服务
✅ 沙箱配置: (可选) 配置 Docker 沙箱隔离

4️⃣ 查看部署结果

脚本完成后会输出关键信息:

Gateway running with host port mapping.
Access from tailnet devices via the host's tailnet IP.
Config: /home/user/.openclaw
Workspace: /home/user/.openclaw/workspace
Token: <your-generated-token>

Commands:
  docker compose -f docker-compose.yml logs -f openclaw-gateway
  docker compose -f docker-compose.yml exec openclaw-gateway node dist/index.js health --token "<your-token>"

高级配置选项

docker-setup.sh 支持多个环境变量进行自定义配置:

环境变量	默认值	说明
`OPENCLAW_CONFIG_DIR`	`~/.openclaw`	配置文件目录
`OPENCLAW_WORKSPACE_DIR`	`~/.openclaw/workspace`	工作区目录
`OPENCLAW_GATEWAY_PORT`	`18789`	Gateway WebSocket 端口
`OPENCLAW_BRIDGE_PORT`	`18790`	浏览器控制端口
`OPENCLAW_GATEWAY_BIND`	`lan`	绑定模式 (loopback/lan/tailnet)
`OPENCLAW_GATEWAY_TOKEN`	自动生成	Gateway 认证令牌
`OPENCLAW_IMAGE`	`openclaw:local`	Docker 镜像名称
`OPENCLAW_SANDBOX`	空(禁用)	设为 `1` 启用沙箱
`OPENCLAW_DOCKER_SOCKET`	`/var/run/docker.sock`	Docker 套接字路径
`OPENCLAW_HOME_VOLUME`	空	使用命名卷代替绑定挂载
`OPENCLAW_EXTRA_MOUNTS`	空	额外的挂载点(逗号分隔)
`OPENCLAW_DOCKER_APT_PACKAGES`	空	构建时安装的额外 APT 包

自定义配置示例:

# 使用自定义配置目录和端口
OPENCLAW_CONFIG_DIR=/opt/openclaw \
OPENCLAW_WORKSPACE_DIR=/opt/openclaw/workspace \
OPENCLAW_GATEWAY_PORT=8789 \
OPENCLAW_GATEWAY_BIND=loopback \
OPENCLAW_SANDBOX=1 \
bash docker-setup.sh

# 使用 Docker 命名卷(适合跨主机迁移)
OPENCLAW_HOME_VOLUME=openclaw-home \
OPENCLAW_SANDBOX=1 \
bash docker-setup.sh

# 添加额外的挂载点
OPENCLAW_EXTRA_MOUNTS="/data/projects:/home/node/projects:ro,/data/shared:/home/node/shared" \
bash docker-setup.sh

# 使用预构建的镜像(跳过本地构建)
OPENCLAW_IMAGE=ghcr.io/openclaw/openclaw:latest \
bash docker-setup.sh

方式二: 手动 Docker Compose 部署

如果您希望完全手动控制部署流程,可以参考以下步骤。

1️⃣ 准备目录结构

1
2
3

# 创建必要的目录
mkdir -p ~/.openclaw/{identity,agents/main/{agent,sessions}}
mkdir -p ~/.openclaw/workspace

2️⃣ 生成 Gateway 令牌

# 使用 OpenSSL 生成随机令牌
export OPENCLAW_GATEWAY_TOKEN=$(openssl rand -hex 32)

# 或使用 Python
export OPENCLAW_GATEWAY_TOKEN=$(python3 -c "import secrets; print(secrets.token_hex(32))")

echo "Your Gateway Token: $OPENCLAW_GATEWAY_TOKEN"

3️⃣ 创建环境变量文件

cat > .env << EOF
# 基础配置
OPENCLAW_CONFIG_DIR=$HOME/.openclaw
OPENCLAW_WORKSPACE_DIR=$HOME/.openclaw/workspace
OPENCLAW_GATEWAY_PORT=18789
OPENCLAW_BRIDGE_PORT=18790
OPENCLAW_GATEWAY_BIND=lan
OPENCLAW_GATEWAY_TOKEN=$OPENCLAW_GATEWAY_TOKEN

# 镜像配置
OPENCLAW_IMAGE=openclaw:local
OPENCLAW_DOCKER_APT_PACKAGES=
OPENCLAW_INSTALL_DOCKER_CLI=

# 沙箱配置(可选)
OPENCLAW_SANDBOX=
OPENCLAW_DOCKER_SOCKET=/var/run/docker.sock
DOCKER_GID=

# 额外配置
OPENCLAW_EXTRA_MOUNTS=
OPENCLAW_HOME_VOLUME=
OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=

# AI 提供商 API 密钥
OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...
GEMINI_API_KEY=
OPENROUTER_API_KEY=

# 消息平台配置(可选)
TELEGRAM_BOT_TOKEN=
DISCORD_BOT_TOKEN=
SLACK_BOT_TOKEN=
SLACK_APP_TOKEN=
EOF

4️⃣ 使用项目的 docker-compose.yml

OpenClaw 项目已包含完整的 docker-compose.yml,直接使用:

# 构建镜像
docker build -t openclaw:local .

# 启动服务
docker compose up -d

# 查看日志
docker compose logs -f openclaw-gateway

5️⃣ 运行初始化配置

# 运行 onboarding 向导
docker compose run --rm openclaw-cli onboard --mode local --no-install-daemon

# 设置 Gateway 模式
docker compose run --rm openclaw-cli config set gateway.mode local
docker compose run --rm openclaw-cli config set gateway.bind lan

# 验证配置
docker compose run --rm openclaw-cli config get

启用沙箱隔离

沙箱隔离为非主会话(群组/频道)提供 Docker 容器级别的安全隔离。

启用步骤:

# 1. 设置环境变量
export OPENCLAW_SANDBOX=1
export OPENCLAW_INSTALL_DOCKER_CLI=1

# 2. 检测 Docker 套接字 GID
export DOCKER_GID=$(stat -c '%g' /var/run/docker.sock 2>/dev/null || stat -f '%g' /var/run/docker.sock 2>/dev/null)

# 3. 重新运行部署脚本
bash docker-setup.sh

# 或手动构建并配置
docker build --build-arg OPENCLAW_INSTALL_DOCKER_CLI=1 -t openclaw:local .

# 4. 构建沙箱镜像
docker build -t openclaw-sandbox:bookworm-slim -f Dockerfile.sandbox .

# 5. 配置沙箱设置
docker compose run --rm openclaw-cli config set agents.defaults.sandbox.mode "non-main"
docker compose run --rm openclaw-cli config set agents.defaults.sandbox.scope "agent"
docker compose run --rm openclaw-cli config set agents.defaults.sandbox.workspaceAccess "none"

# 6. 重启 Gateway
docker compose up -d openclaw-gateway

验证沙箱状态:

# 检查沙箱配置
docker compose run --rm openclaw-cli config get agents.defaults.sandbox

# 检查 Docker CLI 可用性
docker compose exec openclaw-gateway docker --version

# 查看沙箱镜像
docker images | grep openclaw-sandbox

Docker 命名卷部署

使用 Docker 命名卷代替绑定挂载,便于数据迁移和备份。

# 使用命名卷部署
OPENCLAW_HOME_VOLUME=openclaw-home bash docker-setup.sh

# 或在 .env 文件中设置
echo "OPENCLAW_HOME_VOLUME=openclaw-home" >> .env
bash docker-setup.sh

备份和恢复:

# 备份命名卷
docker run --rm \
  -v openclaw-home:/data \
  -v $(pwd):/backup \
  alpine tar czf /backup/openclaw-backup.tar.gz -C /data .

# 恢复命名卷
docker volume create openclaw-home
docker run --rm \
  -v openclaw-home:/data \
  -v $(pwd):/backup \
  alpine tar xzf /backup/openclaw-backup.tar.gz -C /data

常用 Docker Compose 命令

# 启动服务
docker compose up -d

# 停止服务
docker compose down

# 重启 Gateway
docker compose restart openclaw-gateway

# 查看日志
docker compose logs -f openclaw-gateway

# 进入 CLI 容器
docker compose exec openclaw-cli bash

# 运行一次性命令
docker compose run --rm openclaw-cli openclaw status

# 查看服务状态
docker compose ps

# 更新镜像
docker compose pull
docker compose up -d

# 完全清理(包括数据卷)
docker compose down -v

配置消息平台

WhatsApp (扫码登录):

1 2	docker compose run --rm openclaw-cli channels login # 扫描显示的二维码完成登录

Telegram (Bot Token):

# 方式一: 通过命令添加
docker compose run --rm openclaw-cli channels add --channel telegram --token "123456:ABCDEF..."

# 方式二: 通过环境变量
echo "TELEGRAM_BOT_TOKEN=123456:ABCDEF..." >> .env
docker compose restart openclaw-gateway

Discord (Bot Token):

1	docker compose run --rm openclaw-cli channels add --channel discord --token "your-discord-bot-token"

Slack (Bot + App Token):

# 在 .env 文件中添加
echo "SLACK_BOT_TOKEN=xoxb-..." >> .env
echo "SLACK_APP_TOKEN=xapp-..." >> .env
docker compose restart openclaw-gateway

健康检查和监控

# 检查 Gateway 健康状态
docker compose exec openclaw-gateway \
  node dist/index.js health --token "$OPENCLAW_GATEWAY_TOKEN"

# 查看系统状态
docker compose exec openclaw-cli openclaw status

# 运行诊断
docker compose exec openclaw-cli openclaw doctor

# 查看会话列表
docker compose exec openclaw-cli openclaw sessions list

# 查看资源使用
docker stats openclaw-gateway

故障排查

权限问题:

# 修复配置目录权限
docker compose run --rm --user root --entrypoint sh openclaw-cli -c \
  'find /home/node/.openclaw -xdev -exec chown node:node {} + && \
   [ -d /home/node/.openclaw/workspace/.openclaw ] && \
   chown -R node:node /home/node/.openclaw/workspace/.openclaw || true'

重置配置:

# 备份当前配置
cp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.backup

# 重新运行 onboarding
docker compose run --rm openclaw-cli onboard --mode local --no-install-daemon

沙箱问题:

# 检查 Docker socket 访问
docker compose exec openclaw-gateway ls -la /var/run/docker.sock

# 检查 Docker CLI
docker compose exec openclaw-gateway docker --version

# 禁用沙箱
docker compose run --rm openclaw-cli config set agents.defaults.sandbox.mode "off"
docker compose restart openclaw-gateway

网络问题:

# 检查端口监听
docker compose exec openclaw-gateway netstat -tlnp

# 测试 WebSocket 连接
curl -i -N \
  -H "Connection: Upgrade" \
  -H "Upgrade: websocket" \
  -H "Sec-WebSocket-Key: SGVsbG8sIHdvcmxkIQ==" \
  -H "Sec-WebSocket-Version: 13" \
  http://localhost:18789/

# 检查防火墙
sudo iptables -L -n | grep 18789

更新和维护

更新到最新版本:

# 1. 拉取最新代码
cd openclaw
git pull origin main

# 2. 备份配置
cp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.backup

# 3. 重新构建镜像
docker build -t openclaw:local .

# 4. 重启服务
docker compose up -d

# 5. 查看日志确认正常
docker compose logs -f openclaw-gateway

使用预构建镜像:

# 切换到官方镜像
export OPENCLAW_IMAGE=ghcr.io/openclaw/openclaw:latest
docker compose pull
docker compose up -d

定期备份:

#!/bin/bash
# backup-openclaw.sh
BACKUP_DIR="$HOME/openclaw-backups"
TIMESTAMP=$(date +%Y%m%d_%H%M%S)

mkdir -p "$BACKUP_DIR"

# 备份配置
tar czf "$BACKUP_DIR/openclaw-config-$TIMESTAMP.tar.gz" \
  -C "$HOME" .openclaw

# 备份工作区
tar czf "$BACKUP_DIR/openclaw-workspace-$TIMESTAMP.tar.gz" \
  -C "$HOME/.openclaw" workspace

# 保留最近 7 天的备份
find "$BACKUP_DIR" -name "openclaw-*.tar.gz" -mtime +7 -delete

echo "Backup completed: $BACKUP_DIR"

设置定时备份:

# 添加到 crontab
crontab -e

# 每天凌晨 3 点备份
0 3 * * * /path/to/backup-openclaw.sh

生产环境优化

1. 使用反向代理:

# Nginx 配置示例
upstream openclaw_gateway {
    server 127.0.0.1:18789;
}

server {
    listen 443 ssl http2;
    server_name openclaw.example.com;

    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;

    location / {
        proxy_pass http://openclaw_gateway;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        
        # WebSocket 超时设置
        proxy_read_timeout 86400;
        proxy_send_timeout 86400;
    }
}

2. 资源限制:

# docker-compose.override.yml
services:
  openclaw-gateway:
    deploy:
      resources:
        limits:
          cpus: '2.0'
          memory: 4G
        reservations:
          cpus: '1.0'
          memory: 2G
    restart: unless-stopped
    logging:
      driver: "json-file"
      options:
        max-size: "10m"
        max-file: "3"

3. 日志管理:

# 配置日志轮转
cat > /etc/logrotate.d/openclaw << 'EOF'
/var/lib/docker/containers/*/*.log {
    daily
    rotate 7
    compress
    delaycompress
    missingok
    notifempty
    copytruncate
}
EOF

4. 监控告警:

# 健康检查脚本
#!/bin/bash
# health-check.sh

TOKEN="$OPENCLAW_GATEWAY_TOKEN"
WEBHOOK="https://your-webhook-url"

if ! docker compose exec openclaw-gateway \
  node dist/index.js health --token "$TOKEN" > /dev/null 2>&1; then
  
  curl -X POST "$WEBHOOK" \
    -H "Content-Type: application/json" \
    -d '{"text":"OpenClaw Gateway is down!"}'
  
  # 尝试自动重启
  docker compose restart openclaw-gateway
fi

安全加固

1. 限制网络访问:

# 仅绑定到 loopback
export OPENCLAW_GATEWAY_BIND=loopback

# 通过 SSH 隧道访问
ssh -N -L 18789:127.0.0.1:18789 user@server

2. 启用 TLS/SSL:

# 使用 Let's Encrypt
certbot certonly --standalone -d openclaw.example.com

# 配置反向代理(见上文 Nginx 配置)

3. 定期更新:

# 自动更新脚本
#!/bin/bash
cd /path/to/openclaw
git pull
docker build -t openclaw:local .
docker compose up -d

多环境部署

开发/测试/生产分离:

# 开发环境
OPENCLAW_CONFIG_DIR=~/.openclaw-dev \
OPENCLAW_WORKSPACE_DIR=~/.openclaw-dev/workspace \
OPENCLAW_GATEWAY_PORT=18790 \
bash docker-setup.sh

# 生产环境
OPENCLAW_CONFIG_DIR=/opt/openclaw \
OPENCLAW_WORKSPACE_DIR=/opt/openclaw/workspace \
OPENCLAW_GATEWAY_PORT=18789 \
OPENCLAW_SANDBOX=1 \
bash docker-setup.sh

☁️ 云端 VPS 部署

支持的云平台

平台	成本	推荐配置	一键部署
Railway	按使用付费	2GB RAM	✅ 支持
Northflank	按使用付费	2GB RAM	✅ 支持
Oracle Cloud	永久免费层	ARM, 1GB RAM	❌ 需手动
Fly.io	按使用付费	Shared CPU	❌ 需手动
Hetzner	€4.15/月	2GB RAM	❌ 需手动
GCP	免费试用 $300	e2-micro	❌ 需手动

Railway 一键部署

Railway 提供最简单的部署方式:

1️⃣ 点击部署按钮

2️⃣ 配置环境变量

在 Railway 控制台中设置:

1
2
3

OPENCLAW_GATEWAY_TOKEN=<生成一个随机令牌>
OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...

3️⃣ 连接到已部署的 Gateway

# 使用 Railway 提供的公共 URL
export OPENCLAW_GATEWAY_URL=wss://your-app.railway.app
export OPENCLAW_GATEWAY_TOKEN=your-token

# 测试连接
openclaw --url $OPENCLAW_GATEWAY_URL health

Oracle Cloud 免费层部署

Oracle Cloud 提供永久免费的 ARM 实例:

规格:

CPU: 4核 Ampere A1
内存: 24GB RAM
存储: 200GB
流量: 10TB/月

部署步骤:

# 1. 创建实例后,SSH 连接
ssh ubuntu@<实例-IP>

# 2. 安装 Docker
curl -fsSL https://get.docker.com | sh
sudo usermod -aG docker $USER
newgrp docker

# 3. 安装 Docker Compose
sudo curl -L "https://github.com/docker/compose/releases/latest/download/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose
sudo chmod +x /usr/local/bin/docker-compose

# 4. 部署 OpenClaw
mkdir -p ~/openclaw
cd ~/openclaw

# 下载部署脚本
curl -fsSL https://raw.githubusercontent.com/openclaw/openclaw/main/docker-setup.sh -o docker-setup.sh
chmod +x docker-setup.sh

# 运行部署
./docker-setup.sh

# 5. 配置防火墙(如需外部访问)
sudo iptables -I INPUT 6 -m state --state NEW -p tcp --dport 18789 -j ACCEPT
sudo netfilter-persistent save

GCP Compute Engine 部署

创建实例:

# 使用 gcloud CLI 创建实例
gcloud compute instances create openclaw-instance \
    --zone=us-central1-a \
    --machine-type=e2-medium \
    --image-family=ubuntu-2204-lts \
    --image-project=ubuntu-os-cloud \
    --boot-disk-size=20GB \
    --tags=openclaw-server

# 配置防火墙规则(仅通过 SSH 隧道访问)
gcloud compute firewall-rules create allow-ssh \
    --allow=tcp:22 \
    --target-tags=openclaw-server

SSH 连接并部署:

# SSH 连接
gcloud compute ssh openclaw-instance --zone=us-central1-a

# 安装 Node.js 22
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt-get install -y nodejs

# 安装 OpenClaw
sudo npm install -g openclaw@latest

# 配置并启动
openclaw onboard --install-daemon
openclaw gateway start

通过 SSH 隧道安全访问

对于所有 VPS 部署,推荐保持 Gateway 绑定在 loopback,通过 SSH 隧道访问:

# 本地机器建立 SSH 隧道
ssh -N -L 18789:127.0.0.1:18789 user@vps-ip

# 在另一个终端中使用
openclaw --url ws://127.0.0.1:18789 status

或配置 ~/.ssh/config:

Host openclaw-vps
    HostName <VPS-IP>
    User <用户名>
    LocalForward 18789 127.0.0.1:18789
    IdentityFile ~/.ssh/id_rsa

然后简单地运行:

1 2	ssh -N openclaw-vps & openclaw status

⚙️ 配置说明

配置文件位置

主配置: ~/.openclaw/openclaw.json
环境变量: ~/.openclaw/.env 或 .env
凭证: ~/.openclaw/credentials/
会话: ~/.openclaw/agents/<agentId>/sessions/
工作区: ~/.openclaw/workspace

最小配置示例

{
  // 智能体配置
  agent: {
    workspace: "~/.openclaw/workspace",
    model: { 
      primary: "anthropic/claude-sonnet-4-5" 
    }
  },
  
  // 渠道配置
  channels: {
    whatsapp: {
      allowFrom: ["+15555550123"]  // 允许的发送者
    }
  }
}

完整配置示例

{
  // 🌍 环境变量配置
  env: {
    OPENROUTER_API_KEY: "sk-or-...",
    vars: {
      GROQ_API_KEY: "gsk-..."
    },
    shellEnv: {
      enabled: true,
      timeoutMs: 15000
    }
  },

  // 🔐 认证配置文件
  auth: {
    profiles: {
      "anthropic:me@example.com": {
        provider: "anthropic",
        mode: "oauth",
        email: "me@example.com"
      },
      "openai:default": { 
        provider: "openai", 
        mode: "api_key" 
      }
    },
    order: {
      anthropic: ["anthropic:me@example.com"],
      openai: ["openai:default"]
    }
  },

  // 🎭 身份配置
  identity: {
    name: "Clawd",
    theme: "helpful lobster assistant",
    emoji: "🦞"
  },

  // 📝 日志配置
  logging: {
    level: "info",
    file: "/var/log/openclaw/openclaw.log",
    consoleLevel: "info",
    consoleStyle: "pretty",
    redactSensitive: "tools"
  },

  // 💬 消息格式配置
  messages: {
    messagePrefix: "[openclaw]",
    responsePrefix: ">",
    ackReaction: "👀",
    ackReactionScope: "group-mentions",
    tts: {
      enabled: true,
      provider: "elevenlabs",
      auto: false  // 默认关闭,可通过 /tts 命令开启
    }
  },

  // 🛣️ 路由和队列配置
  routing: {
    groupChat: {
      mentionPatterns: ["@openclaw", "openclaw"],
      historyLimit: 50
    },
    queue: {
      mode: "collect",
      debounceMs: 1000,
      cap: 20,
      drop: "summarize"
    }
  },

  // 🌐 Gateway 配置
  gateway: {
    mode: "local",
    bind: "loopback",  // loopback/lan/tailnet/auto/custom
    port: 18789,
    auth: {
      mode: "token",
      token: "${OPENCLAW_GATEWAY_TOKEN}",
      rateLimit: {
        maxAttempts: 10,
        windowMs: 60000,
        lockoutMs: 300000,
        exemptLoopback: true
      }
    },
    tailscale: {
      mode: "off",  // off/serve/funnel
      resetOnExit: false
    },
    reload: {
      mode: "hybrid",  // off/restart/hot/hybrid
      debounceMs: 300
    }
  },

  // 🤖 智能体配置
  agents: {
    defaults: {
      workspace: "~/.openclaw/workspace",
      model: {
        primary: "anthropic/claude-sonnet-4-5",
        fallbacks: [
          "openai/gpt-4.5-turbo",
          "openrouter/anthropic/claude-3.5-sonnet"
        ]
      },
      
      // 🛡️ 沙箱配置
      sandbox: {
        mode: "non-main",  // off/always/non-main
        scope: "session",  // session/global
        workspaceAccess: "none",  // none/ro/rw
        docker: {
          image: "openclaw-sandbox",
          network: "none",
          readOnlyRoot: true,
          memory: "512m",
          cpus: "1.0",
          env: {
            NODE_ENV: "sandbox"
          }
        }
      },
      
      // 🛠️ 工具策略
      tools: {
        allow: ["bash", "read", "write", "edit"],
        deny: ["browser", "canvas"],
        elevated: {
          enabled: false,
          allowList: []
        }
      }
    },
    
    // 多智能体配置
    list: [
      {
        id: "main",
        default: true,
        workspace: "~/.openclaw/workspace",
        model: { primary: "anthropic/claude-opus-4-6" }
      },
      {
        id: "dev",
        workspace: "~/.openclaw/workspace-dev",
        model: { primary: "openai/gpt-4.5-turbo" },
        sandbox: { mode: "always" }
      }
    ]
  },

  // 📱 渠道配置
  channels: {
    // WhatsApp
    whatsapp: {
      allowFrom: ["+15555550123", "+15555550456"],
      groups: {
        "*": { requireMention: true }  // 所有群组需要提及
      }
    },
    
    // Telegram
    telegram: {
      botToken: "${TELEGRAM_BOT_TOKEN}",
      allowFrom: ["@username"],
      groups: {
        "*": { requireMention: true }
      }
    },
    
    // Discord
    discord: {
      token: "${DISCORD_BOT_TOKEN}",
      allowFrom: ["123456789"],
      guilds: {
        "*": { requireMention: true }
      },
      dmPolicy: "pairing"  // pairing/open/closed
    },
    
    // Slack
    slack: {
      botToken: "${SLACK_BOT_TOKEN}",
      appToken: "${SLACK_APP_TOKEN}",
      allowFrom: ["U123456"],
      dmPolicy: "pairing"
    }
  },

  // 🌍 浏览器控制
  browser: {
    enabled: true,
    color: "#4a9eff",
    profiles: {
      default: { 
        persistent: true,
        controlPort: 18792
      }
    }
  },

  // ⏰ 定时任务
  cron: {
    enabled: true,
    jobs: [
      {
        id: "daily-report",
        schedule: "0 9 * * *",  // 每天 9:00
        task: "Send daily report",
        enabled: true
      }
    ]
  },

  // 🎨 画布配置
  canvasHost: {
    enabled: true,
    port: 18793
  },

  // 🔌 技能配置
  skills: {
    enabled: true,
    allowedSkills: ["*"],
    deniedSkills: [],
    workspace: "~/.openclaw/workspace/skills"
  }
}

环境变量优先级

配置加载顺序(优先级从高到低):

进程环境变量
./.env (项目根目录)
~/.openclaw/.env
openclaw.json 中的 env 块

配置验证

# 验证配置文件语法
openclaw config validate

# 查看当前生效的配置
openclaw config get

# 设置单个配置项
openclaw config set agent.model.primary "anthropic/claude-opus-4-6"

# 重新加载配置(不重启)
openclaw config reload

🚀 快速开始

基础使用

1️⃣ 通过消息平台发送消息

在 WhatsApp/Telegram/Discord 中直接给机器人发送消息:

1	你好! 帮我写一个 Python 脚本来处理 CSV 文件

2️⃣ 使用 CLI 命令

# 发送消息
openclaw agent --message "分析这个错误日志" --thinking high

# 指定渠道发送
openclaw message send --to +15555550123 --message "任务完成"

# 使用特定模型
openclaw agent --message "解释量子纠缠" --model "anthropic/claude-opus-4-6"

3️⃣ 查看会话状态

# 查看所有会话
openclaw sessions list

# 查看会话历史
openclaw sessions history --session agent:main:whatsapp:dm:+15555550123

# 重置会话
openclaw sessions reset --session <session-key>

聊天命令

在消息平台中可以使用的命令:

命令	说明
`/status`	显示会话状态(模型、令牌、成本)
`/new` 或 `/reset`	重置当前会话
`/compact`	压缩会话上下文(生成摘要)
`/think <level>`	设置思考级别: off/minimal/low/medium/high/xhigh
`/verbose on\|off`	开启/关闭详细模式
`/usage off\|tokens\|full`	设置使用情况显示
`/tts on\|off\|always`	开启/关闭文本转语音
`/restart`	重启网关(仅所有者,群组中)
`/activation mention\|always`	群组激活模式切换

群组使用

在群组中提及机器人:

1	@openclaw 帮我总结今天的讨论要点

配置群组行为:

{
  channels: {
    telegram: {
      groups: {
        // 所有群组需要提及
        "*": { requireMention: true },
        
        // 特定群组配置
        "-1001234567890": {
          requireMention: false,  // 该群组不需要提及
          historyLimit: 100
        }
      }
    }
  }
}

工具使用示例

文件操作:

# 读取文件
openclaw agent --message "读取并分析 data.csv 文件"

# 写入文件
openclaw agent --message "创建一个 README.md 文件,包含项目说明"

# 编辑文件
openclaw agent --message "在 config.json 中添加新的配置项"

代码执行:

# 运行 Python 脚本
openclaw agent --message "运行 test.py 并显示结果"

# 执行系统命令
openclaw agent --message "检查磁盘使用情况"

浏览器控制:

# 打开网页并截图
openclaw agent --message "访问 https://example.com 并截图"

# 抓取网页内容
openclaw agent --message "从 Hacker News 首页获取热门文章"

节点功能

macOS/iOS 节点命令:

# 拍照
openclaw nodes invoke <node-id> camera.snap

# 录屏
openclaw nodes invoke <node-id> screen.record --duration 10

# 获取位置
openclaw nodes invoke <node-id> location.get

# 显示通知
openclaw nodes invoke <node-id> system.notify --title "提醒" --body "任务完成"

查看可用节点:

# 列出所有节点
openclaw nodes list

# 查看节点详情
openclaw nodes describe <node-id>

# 节点配对管理
openclaw devices list
openclaw devices approve <request-id>

🔒 安全性

默认安全策略

OpenClaw 连接到真实的消息平台,需要将入站 DM 视为不受信任的输入。

DM 配对模式(默认)

在 Telegram/WhatsApp/Signal/iMessage/Microsoft Teams/Discord/Slack 上:

默认策略: dmPolicy="pairing"
未知发送者会收到配对码,机器人不会处理其消息
批准命令: openclaw pairing approve <channel> <code>
批准后,发送者会被添加到本地允许列表

公开 DM 模式

要允许公开入站 DM,需要显式选择:

{
  channels: {
    telegram: {
      dmPolicy: "open",
      allowFrom: ["*"]  // 必须包含 "*"
    }
  }
}

沙箱隔离

推荐配置:

{
  agents: {
    defaults: {
      sandbox: {
        // 对非主会话(群组/频道)使用沙箱
        mode: "non-main",
        scope: "session",
        workspaceAccess: "none",
        
        docker: {
          image: "openclaw-sandbox",
          network: "none",       // 无网络访问
          readOnlyRoot: true,    // 只读根文件系统
          memory: "512m",        // 内存限制
          cpus: "1.0"           // CPU 限制
        }
      },
      
      tools: {
        // 默认允许的工具
        allow: ["bash", "read", "write", "edit", "process"],
        // 默认拒绝的工具
        deny: ["browser", "canvas", "nodes", "cron", "discord", "gateway"]
      }
    }
  }
}

网络安全

绑定模式:

模式	绑定地址	适用场景
`loopback`	127.0.0.1	本地访问(默认,最安全)
`lan`	0.0.0.0	局域网访问(需要认证)
`tailnet`	Tailscale IP	Tailscale 网络访问
`auto`	自动检测	根据环境自动选择

认证要求:

bind=loopback: 可选认证
bind=lan/tailnet: 必须配置认证(token 或 password)

Tailscale 安全访问

{
  gateway: {
    bind: "loopback",  // 保持 loopback
    tailscale: {
      mode: "serve",   // serve: 仅 tailnet / funnel: 公开
      resetOnExit: true
    },
    auth: {
      mode: "token",   // funnel 模式必须使用 password
      token: "${OPENCLAW_GATEWAY_TOKEN}"
    }
  }
}

安全检查清单

运行安全诊断:

1	openclaw doctor

Doctor 会检查:

✅ 危险的 DM 策略配置
✅ 缺失的 Gateway 认证
✅ 不安全的绑定��式
✅ 沙箱配置问题
✅ 工具权限风险

数据隐私

本地存储: 所有会话和配置存储在 ~/.openclaw/
凭证加密: 敏感凭证使用加密存储
日志脱敏: 可配置日志中的敏感信息脱敏
工作区隔离: 每个智能体可以有独立的工作区

备份建议:

# 使用 Git 管理工作区(推荐私有仓库)
cd ~/.openclaw/workspace
git init
git add .
git commit -m "Initial workspace"
git remote add origin git@github.com:your/private-repo.git
git push -u origin main

# 定期备份配置
cp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.backup

🤝 贡献指南

欢迎社区贡献! 请查看 CONTRIBUTING.md 了解详细信息。

开发环境设置

# 克隆仓库
git clone https://github.com/openclaw/openclaw.git
cd openclaw

# 安装依赖
pnpm install

# 构建 UI
pnpm ui:build

# 运行测试
pnpm test

# 代码检查
pnpm check

# 格式化代码
pnpm format

提交规范

# 功能: feat: 添加 XXX 支持
git commit -m "feat: add PostgreSQL integration"

# 修复: fix: 修复 XXX 问题
git commit -m "fix: resolve WebSocket connection timeout"

# 文档: docs: 更新 XXX 文档
git commit -m "docs: update installation guide"

# 样式: style: 格式化代码
git commit -m "style: format TypeScript files"

# 重构: refactor: 重构 XXX 模块
git commit -m "refactor: simplify config loading logic"

# 测试: test: 添加 XXX 测试
git commit -m "test: add gateway authentication tests"

Pull Request 流程

Fork 项目到您的 GitHub 账户
创建新的功能分支: git checkout -b feature/amazing-feature
提交您的更改: git commit -m 'feat: add amazing feature'
推送到分支: git push origin feature/amazing-feature
提交 Pull Request

社区

Discord: https://discord.gg/clawd
GitHub Discussions: https://github.com/openclaw/openclaw/discussions
Twitter/X: @openclaw

📄 许可证

OpenClaw 基于 MIT 许可证开源。

由 Peter Steinberger 和开源社区用 ❤️ 打造
为空间龙虾 AI 助手 Molty 🦞 而生

openclaw.ai · soul.md · steipete.me

_{AI/vibe 编码的 PR 欢迎! 🤖}