最后更新：2026-05-07适用版本：OpenClaw 最新版

一、什么是 OpenClaw？

• 🏠 自托管：运行在你自己的服务器或电脑上，数据完全可控
• 💬 多渠道：一套服务同时支持 WhatsApp、Telegram、Discord、飞书等
• 🤖 原生支持 Agent：内置会话管理、工具调用、多 Agent 路由
• 🔓 开源：MIT 许可，社区驱动

二、系统要求

硬件要求

软件要求

• Node.js：推荐 Node 24，最低 Node 22.14+
• 操作系统：macOS、Linux（包括 WSL2）、Windows（推荐 WSL2）
• 包管理器：npm（内置）、pnpm（可选）

三、快速部署（5 分钟）

步骤 1：安装 OpenClaw

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

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

💡 安装脚本会自动检测并安装 Node.js，无需手动准备。

步骤 2：运行初始化向导

openclaw onboard --install-daemon

1. 选择 AI 模型提供商（Anthropic、OpenAI、Google 等）
2. 配置 API Key
3. 设置 Gateway 服务

步骤 3：验证安装

# 检查版本
openclaw --version

# 检查 Gateway 状态
openclaw gateway status

# 健康检查
openclaw doctor

步骤 4：打开控制面板

openclaw dashboard

四、配置详解

4.1 配置文件位置

openclaw configure

# 查看配置
openclaw config get agents.defaults.workspace

# 修改配置
openclaw config set agents.defaults.heartbeat.every "2h"

# 使用你喜欢的编辑器
vim ~/.openclaw/openclaw.json

💡 配置文件支持热重载，修改后自动生效（部分配置需要重启 Gateway）。

4.2 最小可用配置

// ~/.openclaw/openclaw.json
{
  agents: { 
    defaults: { 
      workspace: "~/.openclaw/workspace" 
    } 
  },
  channels: { 
    whatsapp: { 
      allowFrom: ["+8613800138000"] 
    } 
  }
}

4.3 常用配置场景

配置 AI 模型

{
  agents: {
    defaults: {
      model: {
        primary: "anthropic/claude-sonnet-4-6",
        fallbacks: ["openai/gpt-5.4"]
      },
      models: {
        "anthropic/claude-sonnet-4-6": { alias: "Sonnet" },
        "openai/gpt-5.4": { alias: "GPT" }
      }
    }
  }
}

配置飞书渠道

{
  channels: {
    feishu: {
      enabled: true,
      appId: "cli_xxxxxxxxxxxxx",
      appSecret: "xxxxxxxxxxxxxxxxx",
      encryptKey: "xxxxxxxxxxxxxxxxx",
      verificationToken: "xxxxxxxxxxxxxxxxx",
      dmPolicy: "pairing"  // pairing | allowlist | open | disabled
    }
  }
}

配置访问控制

{
  channels: {
    telegram: {
      enabled: true,
      botToken: "123:abc",
      dmPolicy: "pairing",   // 默认：未知用户需配对码
      allowFrom: ["tg:123"]  // 白名单用户
    }
  }
}

配置定时心跳

{
  agents: {
    defaults: {
      heartbeat: {
        every: "30m",        // 每 30 分钟检查一次
        target: "last"       // 发送到上次对话的渠道
      }
    }
  }
}

配置多 Agent 路由

{
  agents: {
    list: [
      { 
        id: "home", 
        default: true, 
        workspace: "~/.openclaw/workspace-home" 
      },
      { 
        id: "work", 
        workspace: "~/.openclaw/workspace-work" 
      }
    ],
    bindings: [
      { 
        agentId: "home", 
        match: { channel: "whatsapp", accountId: "personal" } 
      },
      { 
        agentId: "work", 
        match: { channel: "whatsapp", accountId: "biz" } 
      }
    ]
  }
}

五、渠道配置指南

5.1 支持的渠道

5.2 飞书渠道完整配置

1. 访问 https://open.feishu.cn/app
2. 创建企业自建应用
3. 记录 App ID、App Secret

• 机器人
• 消息
• 通讯录
• 日历
• 云文档

https://<你的服务器 IP>:18789/lark/callback

{
  channels: {
    feishu: {
      enabled: true,
      appId: "cli_xxxxxxxxxxxxx",
      appSecret: "xxxxxxxxxxxxxxxxx",
      encryptKey: "xxxxxxxxxxxxxxxxx",
      verificationToken: "xxxxxxxxxxxxxxxxx"
    }
  }
}

六、高级部署

6.1 Docker 部署

# 拉取镜像
docker pull openclaw/openclaw:latest

# 运行容器
docker run -d \
  --name openclaw \
  -p 18789:18789 \
  -v ~/.openclaw:/root/.openclaw \
  openclaw/openclaw:latest

6.2  systemd 服务（Linux）

[Unit]
Description=OpenClaw Gateway
After=network.target

[Service]
Type=simple
User=admin
ExecStart=/usr/bin/openclaw gateway start
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target

sudo systemctl enable openclaw
sudo systemctl start openclaw
sudo systemctl status openclaw

6.3 远程访问配置

{
  gateway: {
    remote: {
      tailscale: {
        enabled: true
      }
    }
  }
}

server {
    listen 443 ssl;
    server_name openclaw.yourdomain.com;

    location / {
        proxy_pass http://127.0.0.1:18789;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}

七、故障排查

7.1 常用诊断命令

# 查看 Gateway 状态
openclaw gateway status

# 查看日志
openclaw logs

# 健康检查
openclaw doctor

# 查看配置
openclaw config get

7.2 常见问题

# 检查 Node 是否安装
node -v

# 检查全局包路径
npm prefix -g

# 添加到 PATH
export PATH="$(npm prefix -g)/bin:$PATH"

# 查看详细日志
openclaw logs --follow

# 检查配置文件
openclaw doctor

• 检查渠道配置是否正确
• 检查 API Token 是否有效
• 检查服务器网络是否能访问外网

# 手动重启 Gateway
openclaw gateway restart

# 检查配置热重载模式
openclaw config get gateway.reload.mode

八、安全建议

8.1 访问控制

1. 配置白名单：只允许信任的用户/群组
2. 启用配对码：新用户需要配对码才能访问
3. 群组@限制：配置 requireMention 防止误触发

8.2 密钥管理

1. 不要硬编码：使用环境变量或 Secret Ref
2. 定期轮换：定期更新 API Key
3. 最小权限：只给必要的权限

{
  models: {
    providers: {
      openai: { 
        apiKey: { 
          source: "env", 
          id: "OPENAI_API_KEY" 
        } 
      }
    }
  }
}

8.3 网络安全

1. 使用防火墙：只开放必要端口
2. 启用 HTTPS：使用反向代理 + SSL
3. 内网部署：配合 Tailscale 等组网工具

九、性能优化

9.1 内存优化

{
  agents: {
    defaults: {
      imageMaxDimensionPx: 800  // 降低图片分辨率节省 token
    }
  }
}

9.2 会话管理

{
  session: {
    dmScope: "per-channel-peer",  // 按渠道 + 用户隔离
    reset: {
      mode: "daily",    // 每天重置
      atHour: 4         // 凌晨 4 点
    }
  }
}

9.3 沙箱隔离

{
  agents: {
    defaults: {
      sandbox: {
        mode: "non-main",  // 非主会话使用沙箱
        scope: "agent"
      }
    }
  }
}

十、资源链接

• 官方文档：https://docs.openclaw.ai
• GitHub：https://github.com/openclaw/openclaw
• Discord 社区：https://discord.com/invite/clawd
• 技能市场：https://clawhub.ai

附录：快速参考卡片

核心命令

openclaw --version          # 查看版本
openclaw onboard            # 初始化向导
openclaw dashboard          # 打开控制面板
openclaw gateway status     # 查看状态
openclaw gateway restart    # 重启服务
openclaw doctor             # 健康检查
openclaw logs               # 查看日志

配置文件路径

~/.openclaw/openclaw.json      # 主配置
~/.openclaw/workspace/         # 工作区
~/.openclaw/memory/            # 记忆文件
~/.openclaw/logs/              # 日志文件

默认端口

18789  - Gateway HTTP 服务