文档信息

• 版本: v1.0
• 最后更新: 2026-03-05
• 适用环境: Ubuntu 22.04/24.04 LTS
• 前置条件: 域名、公网服务器、飞书开发者账号

---

一、环境准备

1.1 系统更新

sudo apt update && sudo apt upgrade -y

1.2 安装Node.js (≥22.x)

# 安装nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.4/install.sh | bash
source ~/.bashrc

# 安装Node.js 22
nvm install 22
nvm alias default 22
node --version  # 应显示 v22.x.x
npm --version   # 应显示 10.x.x

1.3 配置npm镜像（可选，国内服务器推荐）

npm config set registry https://registry.npmmirror.com

---

二、安装Nginx并配置域名反向代理

2.1 安装Nginx

sudo apt install nginx -y
sudo systemctl start nginx
sudo systemctl enable nginx

2.2 配置域名反向代理

sudo nano /etc/nginx/sites-available/openclaw.xxxx.com

配置文件内容：

server {
    listen 80;
    server_name openclaw.xxxx.com;

    location / {
        proxy_pass http://127.0.0.1:18789;
        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;
        proxy_read_timeout 3600s;
        proxy_send_timeout 3600s;
    }
}

2.3 启用配置

sudo ln -s /etc/nginx/sites-available/openclaw.xxxx.com /etc/nginx/sites-enabled/
sudo rm /etc/nginx/sites-enabled/default  # 删除默认配置
sudo nginx -t && sudo systemctl reload nginx

2.4 配置HTTPS（使用Certbot）

# 安装Certbot
sudo apt install certbot python3-certbot-nginx -y

# 获取SSL证书
sudo certbot --nginx -d openclaw.xxxx.com

# 选择选项2：HTTP自动跳转HTTPS
# 输入邮箱地址用于证书续期通知

---

三、安装OpenClaw

3.1 一键安装

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

3.2 验证安装

openclaw --version  # 应显示 2026.3.2 或更高

3.3 初始化配置

# 启动配置向导并安装守护进程
openclaw onboard --install-daemon

配置选项：

• 风险提示: Yes
• 模式: QuickStart
• 模型配置: Skip for now（后续配置）
• 通道配置: Skip for now
• 技能配置: No
• 推荐钩子: Yes

3.4 启动Gateway服务

openclaw gateway start
openclaw gateway status  # 确认运行状态

---

四、OpenClaw基础配置

4.1 性能优化（可选，适用于小内存VPS）

sudo mkdir -p /var/tmp/openclaw-compile-cache
sudo chown $USER:$USER /var/tmp/openclaw-compile-cache

echo 'export NODE_COMPILE_CACHE=/var/tmp/openclaw-compile-cache' >> ~/.bashrc
echo 'export OPENCLAW_NO_RESPAWN=1' >> ~/.bashrc
source ~/.bashrc

4.2 配置CORS允许域名

# 配置允许的来源
openclaw config set gateway.controlUi.allowedOrigins '[
  "https://openclaw.xxxx.com",
  "http://localhost",
  "http://127.0.0.1"
]'

# 允许不安全HTTP认证（HTTPS配置后可关闭）
openclaw config set gateway.controlUi.allowInsecureAuth true

4.3 配置令牌认证

# 生成新令牌
NEW_TOKEN=$(openssl rand -hex 16)
openclaw config set gateway.auth.token "$NEW_TOKEN"
openclaw config set gateway.auth.mode "token"

# 查看令牌
openclaw config get gateway.auth.token

# 重启Gateway
openclaw gateway restart

4.4 访问Web界面

https://openclaw.xxxx.com/?token=你的令牌

首次访问会提示配对，执行：

openclaw pairing approve  # 批准配对请求

---

五、接入飞书机器人

5.1 安装飞书插件

# 安装官方飞书插件
openclaw plugins install @overlink/openclaw-feishu

# 验证安装
openclaw plugins list

5.2 删除重复渠道（如有）

如果配置中出现两个飞书渠道：

# 禁用并删除旧渠道
openclaw config set channels.feishu.enabled false
openclaw config delete channels.feishu

# 清理channelOrder
openclaw config set channelOrder '["openclaw-feishu"]'
openclaw config set channelLabels '{"openclaw-feishu": "Feishu"}'
openclaw config set channelDetailLabels '{"openclaw-feishu": "Feishu/Lark (飞书)"}'

5.3 配置飞书应用凭证

# 启用飞书渠道
openclaw config set channels.openclaw-feishu.enabled true

# 设置飞书应用凭证（替换为实际值）
openclaw config set channels.openclaw-feishu.appId "cli_你的AppID"
openclaw config set channels.openclaw-feishu.appSecret "你的AppSecret"
openclaw config set channels.openclaw-feishu.domain "feishu"

# 配置私聊策略（开放模式，无需配对）
openclaw config set channels.openclaw-feishu.dmPolicy "open"
openclaw config set channels.openclaw-feishu.allowFrom '["*"]'

# 重启Gateway
openclaw gateway restart

5.4 飞书开放平台配置

5.4.1 创建应用

1. 登录 飞书开放平台
2. 创建企业自建应用
3. 记录 App ID 和 App Secret
4. 添加机器人能力

5.4.2 配置权限

在「权限管理」页面，批量导入权限：

{
  "scopes": {
    "tenant": [
      "im:message",
      "im:message.p2p_msg:readonly",
      "im:message.group_at_msg:readonly",
      "im:message:send_as_bot",
      "im:resource",
      "contact:user.base:readonly"
    ]
  }
}

5.4.3 配置事件订阅

1. 进入「事件与回调」页面
2. 订阅方式选择：「使用长连接接收事件」（WebSocket）
3. 添加事件：「接收消息 v2.0」(im.message.receive_v1)
4. 点击保存

5.4.4 发布应用

1. 进入「版本管理与发布」
2. 创建版本，填写版本号和更新说明
3. 设置可见范围（至少包含自己）
4. 提交发布并等待审批

5.5 验证飞书接入

# 查看渠道状态
openclaw channels list

# 应该看到：
# openclaw-feishu | enabled | running | OK

# 查看实时日志
openclaw logs follow
# 应看到 "Feishu websocket connected"

5.6 测试飞书机器人

1. 在飞书中搜索机器人应用
2. 发送消息（如"你好"）
3. 应收到自动回复

---

六、模型配置（可选）

6.1 阿里云百炼 Coding Plan

# 配置阿里云百炼
openclaw config set models.bailian.enabled true
openclaw config set models.bailian.apiKey "你的API密钥"

6.2 DeepSeek 官方API

# 配置DeepSeek
openclaw config set models.deepseek.enabled true
openclaw config set models.deepseek.apiKey "你的API密钥"

6.3 禁用内存搜索（如不配置模型）

openclaw config set agents.defaults.memorySearch.enabled false

---

七、常用运维命令

7.1 服务管理

# 状态查看
openclaw gateway status
openclaw status

# 启动/停止/重启
openclaw gateway start
openclaw gateway stop
openclaw gateway restart

# 日志查看
openclaw logs follow

7.2 配置管理

# 查看配置
openclaw config get gateway
openclaw config get channels

# 设置配置
openclaw config set key value

# 运行诊断
openclaw doctor
openclaw doctor --fix

7.3 设备管理

# 查看设备
openclaw devices list

# 批准配对
openclaw pairing approve <配对码>

---

八、常见问题排查

8.1 访问问题

错误	解决方案
origin not allowed	在 allowedOrigins 中添加当前访问的域名
unauthorized: token missing	URL中添加 ?token=你的令牌
pairing required	执行 openclaw pairing approve
disconnected (1006)	检查Nginx WebSocket配置

8.2 飞书问题

问题	解决方案
机器人收不到消息	检查事件订阅是否为「长连接」，是否添加了im.message.receive_v1事件
机器人无法回复	检查权限是否包含im:message:send_as_bot
私聊需要配对	设置 dmPolicy: "open" 和 allowFrom: ["*"]
群聊不回复	确保在群聊中@机器人，并添加了群聊权限

8.3 Gateway问题

问题	解决方案
Config token differs	执行 openclaw gateway install --force
端口冲突	检查 lsof -i:18789，修改配置中的端口
性能警告	设置 NODE_COMPILE_CACHE 环境变量

---

九、安全建议

9.1 必做配置

1. 始终使用HTTPS访问
2. 启用令牌认证 (auth.mode: "token")
3. 定期更新令牌
4. 合理设置 allowedOrigins，避免使用 ["*"]

9.2 飞书安全

1. 私聊策略建议使用 "pairing" 或 "allowlist"
2. 群聊建议设置 requireMention: true
3. 敏感操作（如shell、文件写入）设置权限控制

9.3 定期维护

# 每月执行
openclaw security audit --deep
openclaw doctor --fix
sudo certbot renew  # 证书续期

---

十、后续扩展

10.1 安装技能

openclaw skills list
openclaw skills install <skill-name>

10.2 接入更多渠道

• Telegram: openclaw plugins install @openclaw/telegram
• Slack: openclaw plugins install @openclaw/slack
• Discord: openclaw plugins install @openclaw/discord

10.3 配置更多模型

openclaw models list-providers
openclaw configure --section model

---

附录：配置文件示例

最终 ~/.openclaw/openclaw.json 的核心配置：

{
  "gateway": {
    "port": 18789,
    "mode": "local",
    "bind": "loopback",
    "controlUi": {
      "allowedOrigins": [
        "https://openclaw.xxxx.com",
        "http://localhost",
        "http://127.0.0.1"
      ],
      "allowInsecureAuth": false
    },
    "auth": {
      "mode": "token",
      "token": "你的令牌"
    }
  },
  "channels": {
    "openclaw-feishu": {
      "enabled": true,
      "appId": "cli_你的AppID",
      "appSecret": "你的AppSecret",
      "domain": "feishu",
      "dmPolicy": "open",
      "allowFrom": ["*"],
      "requireMention": false
    }
  },
  "channelOrder": ["openclaw-feishu"]
}

---

版本历史

版本	日期	更新内容
v1.0	2026-03-04	初始版本，包含基础部署、Nginx配置、HTTPS、飞书接入

---

🎉 现在你的OpenClaw已经成功部署，并接入了飞书机器人，可以通过 https://openclaw.xxxx.com 访问Web控制台，在飞书中与机器人对话。