OpenClaw 安装配置指南

文档版本: 1.0
创建日期: 2026-03-08
适用平台: Windows 10/11

目录

  1. 系统要求
  2. 安装 OpenClaw
  3. 初始配置
  4. 启动与停止
  5. 飞书集成配置
  6. 常见问题排查

1. 系统要求

项目 最低要求
操作系统 Windows 10/11, macOS, Linux
Node.js >= 14.0.0
内存 >= 4GB
网络 能访问 AI API 服务

检查 Node.js 版本：

node --version

2. 安装 OpenClaw

2.1 通过 npm 安装（推荐）

npm install -g openclaw

2.2 验证安装

openclaw --version
openclaw --help

2.3 更新 OpenClaw

npm update -g openclaw

3. 初始配置

3.1 运行配置向导

openclaw configure

配置向导会引导你设置：

  • 模型配置: 选择 AI 模型提供商（智谱 AI、OpenAI 等）
  • 网关配置: 端口、绑定地址等
  • 频道配置: 飞书、Discord 等消息渠道

3.2 配置 AI 模型

智谱 AI (GLM)
# 方法1: 使用配置向导
openclaw configure --section model

# 方法2: 直接编辑配置文件
# 文件位置: ~/.openclaw/openclaw.json

配置文件示例：

{
  "models": {
    "providers": {
      "zai": {
        "baseUrl": "https://open.bigmodel.cn/api/paas/v4",
        "apiKey": "你的API Key",
        "api": "openai-completions",
        "models": [
          {
            "id": "glm-5",
            "name": "GLM-5",
            "contextWindow": 204800,
            "maxTokens": 131072
          }
        ]
      }
    }
  },
  "agents": {
    "defaults": {
      "model": {
        "primary": "zai/glm-5"
      }
    }
  }
}
API Key 配置位置

OpenClaw 有两个地方存储 API Key：

  1. 主配置文件: ~/.openclaw/openclaw.json 中的 models.providers.zai.apiKey
  2. 认证配置: ~/.openclaw/agents/main/agent/auth-profiles.json

确保两处 API Key 一致！

3.3 验证配置

# 检查配置状态
openclaw doctor

# 测试 Agent 响应
openclaw agent --agent main --message "你好"

4. 启动与停止

4.1 启动 Gateway

# 前台启动
openclaw gateway

# 后台启动（Windows 任务计划）
openclaw gateway start

4.2 停止 Gateway

openclaw gateway stop

# 如果停止失败，强制杀死进程
taskkill /F /PID <pid>

4.3 查看状态

# 基本状态
openclaw status

# 详细状态
openclaw status --deep

4.4 查看日志

# 查看日志
openclaw logs

# 实时监控日志
openclaw logs --follow

4.5 打开 Dashboard

openclaw dashboard
# 或直接访问: http://127.0.0.1:18789/

5. 飞书集成配置（详细步骤）

5.1 创建飞书应用

步骤 1：登录飞书开放平台
  1. 打开 https://open.feishu.cn/
  2. 使用飞书账号登录
  3. 点击右上角 「开发者后台」
步骤 2：创建企业自建应用
  1. 点击 「创建企业自建应用」
  2. 填写应用信息：
    • 应用名称: 如 OpenClaw Bot
    • 应用描述: 如 AI 研发团队助手
    • 应用图标: 上传一个图标
  3. 点击 「创建」
步骤 3：记录凭证信息

创建成功后，在 「凭证与基础信息」 页面记录：

┌─────────────────────────────────────────┐
│  App ID:     cli_a92e98273f38dcb3       │
│  App Secret: RSDs7rjItFT7bQYcXwgjN...   │
└─────────────────────────────────────────┘

⚠️ 重要：妥善保管 App Secret，不要泄露！

5.2 配置机器人能力

步骤 1：进入应用能力设置
左侧菜单 → 应用能力 → 机器人
步骤 2：启用机器人
  1. 点击 「启用机器人」 按钮
  2. 填写机器人信息：
字段 填写内容
机器人名称 OpenClaw Bot
机器人描述 AI 研发团队助手，支持代码开发、审查、部署等功能
机器人头像 上传头像图片
  1. 点击 「保存」
步骤 3：确认启用状态

确保看到：

☑ 机器人能力已启用

5.3 配置权限管理

步骤 1：进入权限管理
左侧菜单 → 权限管理
步骤 2：开通消息相关权限

在权限管理页面，搜索并开通以下权限：

消息权限（必选）：

权限名称 权限ID 用途
✅ 获取与更新群组信息 - 获取群组列表和信息
✅ 以应用身份读取群消息 - 读取群组中的消息
✅ 以应用身份发送群消息 - 在群组中发送消息
✅ 读取用户发给机器人的单聊消息 - 接收私聊消息
✅ 接收群聊中@机器人消息事件 - 被@时接收通知

可选权限：

权限名称 权限ID 用途
获取群组中所有消息 - 读取所有群消息（敏感）
获取与上传文件或图片 - 文件处理
步骤 3：确认权限状态

在 「消息」 分类下，确认所有必要权限显示 「已开通」：

消息
├── 获取单聊、群组消息 ───────────── ✅ 已开通
├── 查看消息表情回复 ─────────────── ✅ 已开通
├── 获取与发送单聊、群组消息 ─────── ✅ 已开通
├── 读取用户发给机器人的单聊消息 ─── ✅ 已开通
├── 接收群聊中@机器人消息事件 ────── ✅ 已开通
└── 获取群组中所有消息（敏感权限）─ ✅ 已开通

5.4 配置事件订阅

步骤 1：进入事件订阅
左侧菜单 → 事件与回调 → 事件订阅
步骤 2：选择订阅方式

重要：选择「使用长连接接收事件」

飞书支持两种订阅方式：

方式 适用场景 配置难度
长连接（推荐） 本地开发、内网环境 简单 ⭐
Request URL 有公网服务器 复杂 ⭐⭐⭐

选择长连接的步骤：

  1. 在 「订阅方式」 区域
  2. 选择 「使用长连接接收事件」
  3. 页面会显示类似内容： 
    ☑ 使用长连接接收事件

本地长连接服务已启动，请在客户端配置 App ID 和 App Secret
步骤 3：添加事件

在 「事件」 区域，点击 「添加事件」：

必选事件：

事件名称 事件ID 用途
✅ 接收消息 im.message.receive_v1 接收用户发送的消息

可选事件：

事件名称 事件ID 用途
群成员增加 im.chat.member.added_v1 新成员入群通知
消息已读 im.message.read_v1 消息已读回执
步骤 4：确认事件配置

确保看到：

已添加的事件 (1)
┌──────────────────────────────────────────────────┐
│ 接收消息 v2.0                                     │
│ im.message.receive_v1                            │
│ ✅ 读取用户发给机器人的单聊消息                    │
│ ✅ 接收群聊中@机器人消息事件                       │
│ ✅ 获取群组中所有消息（敏感权限）                   │
└──────────────────────────────────────────────────┘
步骤 5：保存配置

点击页面底部的 「保存」 按钮。

5.5 发布应用

⚠️ 重要：必须发布应用才能正常使用长连接！

步骤 1：进入版本管理
左侧菜单 → 版本管理与发布
步骤 2：创建版本
  1. 点击 「创建版本」
  2. 填写版本信息：
    • 版本号: 如 1.0.0
    • 版本说明: 如 首次发布，支持消息收发功能
  3. 点击 「保存」
步骤 3：申请发布
  1. 在版本列表中，找到刚创建的版本
  2. 点击 「申请线上发布」
  3. 填写发布申请：
    • 发布范围: 选择「所有员工」或指定部门
    • 发布说明: 描述功能
  4. 提交申请
步骤 4：等待审核
  • 企业管理员会收到审核通知
  • 审核通过后，应用状态变为 「已发布」
步骤 5：确认发布状态

确保看到：

版本列表
┌──────────────────────────────────────────────────┐
│ 版本 1.0.0                                        │
│ 状态: ✅ 已发布                                   │
│ 发布时间: 2026-03-08 11:30                        │
└──────────────────────────────────────────────────┘

5.6 配置 OpenClaw

步骤 1：配置飞书频道
# 设置 App ID
openclaw config set channels.feishu.appId "cli_a92e98273f38dcb3"

# 设置 App Secret
openclaw config set channels.feishu.appSecret "你的App Secret"

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

# 设置连接模式为长连接
openclaw config set channels.feishu.connectionMode websocket
步骤 2：重启 Gateway
openclaw gateway stop
openclaw gateway
步骤 3：验证连接
# 检查飞书状态
openclaw status --deep

# 查看日志确认连接成功
openclaw logs | grep -i "ws client ready"

成功日志示例：

[ws] ws client ready ✅

5.7 添加 Bot 到飞书群组

步骤 1：打开飞书客户端
步骤 2：创建或打开群组
步骤 3：添加机器人
  1. 点击群组名称（右上角）
  2. 选择 「设置」
  3. 找到 「群机器人」
  4. 点击 「添加机器人」
  5. 搜索并选择你的机器人（如 OpenClaw Bot）
  6. 点击 「添加」
步骤 4：测试机器人

在群里发送消息：

@OpenClaw Bot 你好

如果配置正确，机器人会回复消息。

5.8 获取群组 chat_id（用于路由配置）

方法 1：通过日志获取
  1. 启动日志监控：
openclaw logs --follow

  1. 在飞书群里 @Bot 发送消息

  2. 从日志中查找 chat_id 或 open_chat_id

方法 2：通过命令获取
openclaw directory groups list --channel feishu

5.9 配置飞书路由（可选）

将不同群组绑定到不同 Agent：

# 绑定开发群 → developer agent
openclaw agents bind --agent developer \
  --bind feishu:oc_xxxxx_developer_group

# 绑定运维群 → devops agent
openclaw agents bind --agent devops \
  --bind feishu:oc_xxxxx_devops_group

5.10 飞书配置检查清单

在完成配置前，请确认以下各项：

检查项 状态
☐ 已创建飞书应用
☐ 已记录 App ID 和 App Secret
☐ 机器人能力已启用
☐ 消息相关权限已开通
☐ 事件订阅选择了「长连接」模式
☐ 已添加 im.message.receive_v1 事件
☐ 应用已发布到线上
☐ OpenClaw 配置了正确的 App ID/Secret
☐ Gateway 已重启
☐ Bot 已添加到测试群组
☐ 在群里 @Bot 测试成功

5.11 常见配置错误

错误 1：长连接一直失败
[ws] ws connect failed

原因：

  • 应用未发布
  • 事件订阅未选择「长连接」
  • 权限未开通

解决方案：

  1. 确认应用已发布
  2. 确认事件订阅选择了「长连接」
  3. 确认消息权限已开通
  4. 重启 Gateway
错误 2：Bot 在群里无响应

原因：

  • Bot 未添加到群组
  • 消息没有 @Bot
  • 权限不足

解决方案：

  1. 确认 Bot 已添加到群组
  2. 发送消息时必须 @Bot
  3. 检查权限配置
错误 3：私聊无响应

原因：

  • 未开通「读取用户发给机器人的单聊消息」权限
  • 用户未与 Bot 建立会话

解决方案：

  1. 开通相关权限
  2. 先主动与 Bot 发起一次对话

6. 常见问题排查

6.1 401 身份验证失败

原因： AI 模型 API Key 无效或配置不一致

解决方案：

# 检查配置文件中的 API Key
cat ~/.openclaw/openclaw.json | grep apiKey
cat ~/.openclaw/agents/main/agent/auth-profiles.json

# 确保两处 API Key 一致

6.2 飞书长连接失败

日志表现：

[ws] ws connect failed

排查步骤：

  1. 确认应用已发布到线上
  2. 确认事件订阅选择了"长连接"
  3. 确认已添加 im.message.receive_v1 事件
  4. 重启 Gateway
openclaw gateway stop
openclaw gateway

6.3 Gateway 端口被占用

错误：

Port 18789 is already in use

解决方案：

# 查找并杀死占用端口的进程
netstat -ano | findstr 18789
taskkill /F /PID <pid>

# 或使用其他端口
openclaw gateway --port 18888

6.4 Gateway 无法启动

解决方案：

# 停止所有相关进程
openclaw gateway stop

# 删除锁文件（如果存在）
rm ~/.openclaw/*.lock

# 重新启动
openclaw gateway

6.5 飞书消息无响应

排查清单：

  • Gateway 正在运行
  • 飞书频道状态为 OK
  • Bot 已添加到群组
  • 消息中 @了 Bot
  • 应用已发布
# 检查飞书状态
openclaw status --deep | grep -A5 "Channels"

# 查看实时日志
openclaw logs --follow

附录

重要文件路径

文件 路径
主配置文件 ~/.openclaw/openclaw.json
Agent 认证 ~/.openclaw/agents/main/agent/auth-profiles.json
技能目录 ~/.openclaw/skills/
工作空间 ~/.openclaw/workspace/
日志文件 %TEMP%/openclaw/openclaw-YYYY-MM-DD.log

常用命令速查

# 状态检查
openclaw status              # 基本状态
openclaw status --deep       # 详细状态
openclaw doctor              # 健康检查

# Gateway 控制
openclaw gateway             # 启动
openclaw gateway stop        # 停止
openclaw logs                # 查看日志

# 配置管理
openclaw configure           # 配置向导
openclaw config get <path>   # 获取配置
openclaw config set <path> <value>  # 设置配置

# Agent 管理
openclaw agents list         # 列出 Agents
openclaw agent --agent <id> --message "消息"  # 测试 Agent

参考链接

# 人工智能
Logo
龙虾开发者社区

小龙虾开发者社区是 CSDN 旗下专注 OpenClaw 生态的官方阵地，聚焦技能开发、插件实践与部署教程，为开发者提供可直接落地的方案、工具与交流平台，助力高效构建与落地 AI 应用

更多推荐

cover

2026年云端新手步骤：如何安装OpenClaw？Coding Plan配置及大模型API Key接入

avatar 龙虾开发者社区
cover

2026年本地简易教程：怎么集成OpenClaw？Coding Plan配置与大模型Skill接入

avatar 龙虾开发者社区
cover

2026年腾讯云零门槛步骤：OpenClaw怎么搭建？Coding Plan配置与大模型接入流程

avatar 龙虾开发者社区