【龙虾】OpenClaw部署全流程教程

本文档记录了 OpenClaw AI 助手的完整部署流程，包括阿里百炼模型配置、飞书渠道接入等内容。

环境要求

项目	要求
操作系统	macOS 12+ / Ubuntu 20.04+
Node.js	v22 或更高版本
内存	最低 2GB，推荐 4GB+
磁盘空间	最低 1GB

第一步：安装 OpenClaw

1.1 一键安装

curl -fsSL https://raw.githubusercontent.com/miaoxworld/OpenClawInstaller/main/install.sh | bash

⚠️ 踩坑：安装脚本需要交互式终端确认。如果在非交互环境运行，脚本会报错 /dev/tty: Device not configured。

1.2 验证安装

openclaw --version
# 输出: 2026.3.2

1.3 安装 Gateway 服务

openclaw gateway install

第二步：配置 AI 模型

2.1 阿里百炼模型配置

OpenClaw 支持多种 AI 模型。本教程使用阿里百炼（DashScope）的 API。

获取 API Key

访问阿里云百炼平台
开通服务并创建 API Key
记录 API Key 和 Base URL

阿里百炼 Anthropic 兼容 API 信息：

Base URL: https://coding.dashscope.aliyuncs.com/apps/anthropic
支持的模型: glm-5, qwen3.5-plus, kimi-k2.5, MiniMax-M2.5 等

2.2 配置模型文件

编辑配置文件 ~/.openclaw/openclaw.json，添加模型配置：

{
  "models": {
    "providers": {
      "bailian": {
        "baseUrl": "https://coding.dashscope.aliyuncs.com/apps/anthropic",
        "apiKey": "你的API密钥",
        "models": [
          {
            "id": "glm-5",
            "name": "GLM-5",
            "api": "anthropic-messages",
            "input": ["text"],
            "contextWindow": 128000,
            "maxTokens": 4096
          },
          {
            "id": "qwen3.5-plus",
            "name": "Qwen3.5 Plus",
            "api": "anthropic-messages",
            "input": ["text", "image"],
            "contextWindow": 128000,
            "maxTokens": 8192
          }
        ]
      }
    }
  },
  "agents": {
    "defaults": {
      "model": {
        "primary": "bailian/glm-5",
        "fallbacks": ["bailian/qwen3.5-plus"]
      }
    }
  }
}

⚠️ 踩坑：模型 ID 必须与 API 支持的模型名称完全一致。配置错误的模型会导致 Unknown model 错误。

2.3 验证模型配置

openclaw models status

输出示例：

Config        : ~/.openclaw/openclaw.json
Default       : bailian/glm-5
Fallbacks (1) : bailian/qwen3.5-plus

第三步：配置机器人身份

3.1 创建身份文件

创建 ~/.openclaw/workspace/IDENTITY.md：

# 糯米

## 身份

你是糯米，一个温暖、聪明、有点调皮的 AI 助手。

## 个性特点

- **温暖亲切**：以友善的方式与用户交流
- **聪明高效**：快速理解用户需求
- **有点调皮**：偶尔开轻松的玩笑

## 交流风格

- 使用简体中文回复
- 喜欢用 emoji 增添趣味（🍡 糯米团子）

## 标志性 Emoji

🍡 - 糯米团子

## 核心能力

1. 代码助手
2. 知识问答
3. 创意协作
4. 任务规划

3.2 设置身份信息

openclaw agents set-identity --agent main --name "糯米" --emoji "🍡"
openclaw config set agents.defaults.workspace ~/.openclaw/workspace

3.3 测试 AI 连接

openclaw agent --session-id test --message "你好，请介绍你自己"

第四步：配置飞书渠道

4.1 创建飞书应用

访问飞书开放平台
创建企业自建应用（个人账号即可，无需企业认证）
记录 App ID 和 App Secret

4.2 配置应用能力

启用机器人能力

进入 应用能力 → 确认「机器人」开关已打开

添加权限

进入 权限管理，添加以下权限：

im:message - 获取与发送单聊、群聊消息
im:message:send_as_bot - 以应用身份发消息
im:chat:readonly - 获取群组信息

发布应用

进入 版本管理与发布 → 创建版本 → 发布

⚠️ 踩坑：权限配置后必须发布新版本才会生效！

4.3 配置 OpenClaw 飞书渠道

openclaw config set channels.feishu.enabled true
openclaw config set channels.feishu.appId "你的AppID"
openclaw config set channels.feishu.appSecret "你的AppSecret"
openclaw config set channels.feishu.connectionMode "websocket"
openclaw config set channels.feishu.requireMention false

4.4 配置事件订阅（关键步骤！）

进入飞书开放平台 事件与回调 → 事件订阅
选择「使用长连接接收事件」
添加事件：im.message.receive_v1
点击保存按钮

⚠️ 大坑：必须添加 im.message.receive_v1 事件并保存！否则机器人能发消息但收不到消息。长连接状态应显示"已连接"。

4.5 重启 Gateway 服务

openclaw gateway restart

4.6 验证飞书渠道

openclaw channels status --probe

输出示例：

Gateway reachable.
- Feishu default: enabled, configured, running, works

4.7 将机器人添加到群聊

打开飞书群聊
进入群设置 → 群机器人 → 添加机器人
在群里 @机器人发送消息测试

常见问题与踩坑

问题 1：Gateway 服务启动后无法连接

症状：openclaw gateway status 显示 RPC probe: failed

原因：Gateway 服务需要几秒钟启动

解决：等待几秒后重试，或检查日志 openclaw logs

问题 2：Dashboard 显示 "unauthorized: too many failed authentication attempts"

症状：访问 Dashboard 时被锁定

原因：多次认证失败后触发临时锁定

解决：

等待几分钟后重试

获取正确的 Token：

cat ~/.openclaw/openclaw.json | jq -r '.gateway.auth.token'

在 Dashboard 设置中输入 Token

问题 3：模型调用失败 "Unknown model"

症状：AI 对话时报错 Unknown model: anthropic/xxx

原因：模型 ID 配置错误或未在 providers 中定义

解决：

确保模型 ID 与 API 支持的名称一致
检查 openclaw.json 中的 models.providers 配置
重启 Gateway：openclaw gateway restart

问题 4：飞书能发消息但不能收消息

症状：机器人可以主动发消息，但 @机器人没有回复

原因：飞书事件订阅未正确配置

解决：

进入飞书开放平台 → 事件与回调 → 事件订阅
确认已选择「使用长连接接收事件」
确认已添加事件 im.message.receive_v1
点击保存按钮
确认长连接状态显示"已连接"
重启 Gateway：openclaw gateway restart

💡 这是最大的坑！很多人配置了长连接但忘记添加事件或保存。

问题 5：飞书事件订阅保存失败 "应用未建立长连接"

症状：保存事件订阅时提示应用未建立长连接

原因：Gateway 服务未运行或 WebSocket 未连接

解决：

确保 Gateway 正在运行：openclaw gateway status
检查日志确认 WebSocket 连接成功：openclaw logs | grep -i websocket
日志应显示 [ws] ws client ready

问题 6：群聊消息无响应

症状：私聊正常，群聊无响应

原因：飞书群聊要求 @机器人

解决：在群聊中发送消息时必须 @机器人

问题 7：配置修改后不生效

症状：修改 openclaw.json 后行为未改变

原因：Gateway 服务需要重启或重新加载

解决：

openclaw gateway restart
# 或热重载（部分配置支持）
openclaw gateway call config.reload

附录：配置文件参考

完整的 openclaw.json

{
  "meta": {
    "lastTouchedVersion": "2026.3.2"
  },
  "models": {
    "providers": {
      "bailian": {
        "baseUrl": "https://coding.dashscope.aliyuncs.com/apps/anthropic",
        "apiKey": "sk-sp-xxxxxxxx",
        "models": [
          {
            "id": "glm-5",
            "name": "GLM-5",
            "api": "anthropic-messages",
            "input": ["text"],
            "contextWindow": 128000,
            "maxTokens": 4096
          },
          {
            "id": "qwen3.5-plus",
            "name": "Qwen3.5 Plus",
            "api": "anthropic-messages",
            "input": ["text", "image"],
            "contextWindow": 128000,
            "maxTokens": 8192
          },
          {
            "id": "kimi-k2.5",
            "name": "Kimi K2.5",
            "api": "anthropic-messages",
            "input": ["text"],
            "contextWindow": 128000,
            "maxTokens": 4096
          }
        ]
      }
    }
  },
  "agents": {
    "defaults": {
      "model": {
        "primary": "bailian/glm-5",
        "fallbacks": ["bailian/qwen3.5-plus", "bailian/kimi-k2.5"]
      },
      "workspace": "/Users/你的用户名/.openclaw/workspace"
    },
    "list": [
      {
        "id": "main",
        "identity": {
          "name": "糯米",
          "emoji": "🍡"
        }
      }
    ]
  },
  "channels": {
    "feishu": {
      "enabled": true,
      "appId": "cli_xxxxxxxxxxxxx",
      "appSecret": "xxxxxxxxxxxxxxxx",
      "connectionMode": "websocket",
      "requireMention": false
    }
  },
  "gateway": {
    "mode": "local",
    "auth": {
      "mode": "token",
      "token": "你的访问Token"
    }
  }
}

目录结构

~/.openclaw/
├── openclaw.json              # 主配置文件
├── workspace/
│   ├── IDENTITY.md            # 机器人身份定义
│   └── BOOTSTRAP.md           # 引导文件（可选）
├── agents/main/agent/
│   └── auth-profiles.json     # API 认证配置
└── logs/
    └── gateway.log            # 日志文件

常用命令速查

# 服务管理
openclaw gateway status        # 查看状态
openclaw gateway restart       # 重启服务
openclaw gateway stop          # 停止服务
openclaw logs                  # 查看日志

# 模型管理
openclaw models status         # 查看模型配置
openclaw models set <model>    # 设置默认模型
openclaw models list --all     # 列出所有模型

# 渠道管理
openclaw channels status --probe  # 检查渠道状态
openclaw channels list            # 列出已配置渠道

# 测试对话
openclaw agent --session-id test --message "你好"

# 诊断工具
openclaw doctor                # 运行诊断
openclaw health                # 健康检查