OpenClaw 小白使用手册

📱 OpenClaw 是什么？

OpenClaw 是一个开源的 AI 网关工具，把各种 AI 接入飞书、企业微信等国内办公平台。

核心功能

🚀 快速开始

1. 环境准备

系统要求：

• Node.js 22+
• macOS / Linux / Windows

node --version

2. 安装 OpenClaw

# 一键安装
curl -fsSL https://openclaw.ai/install.sh | bash

# 或用 npm
npm install -g openclaw@latest

3. 启动 Gateway

openclaw onboard --install-daemon

启动后运行在 http://127.0.0.1:18789

📲 接入飞书（重点）

第一步：创建飞书应用

1. 打开 飞书开放平台
2. 创建企业自建应用
• 应用名称：如「AI 助手」
• 应用描述：随意填写
3. 获取凭证（记录这些信息）
• App ID
• App Secret

第二步：配置权限

在飞书开放平台，给应用开通以下权限：

⚠️ 重要：开通权限后，需要发布应用版本。

第三步：配置事件订阅

1. 在飞书开放台进入「事件订阅」
2. 添加事件：
   im.message.receive_v1（接收消息）
3. 配置请求 URL：
• 需要 OpenClaw Gateway 能被外网访问
• 使用内网穿透（如 ngrok、frp）或公网服务器
• URL 格式：https://你的域名/feishu/events
4. 验证 URL：
   飞书会发送验证请求，OpenClaw 会自动处理

第四步：配置 OpenClaw

编辑配置文件 ~/.openclaw/openclaw.json：

{
  "channels": {
    "feishu": {
      "appId": "cli_xxxxxxxxxxxxx",
      "appSecret": "你的AppSecret",
      "encryptKey": "你的加密Key（可选）",
      "verificationToken": "你的验证Token",
      "allowFrom": ["ou_xxxxxxxxxxxx", "ou_yyyyyyyyyyyy"],
      "groups": {
        "*": { "requireMention": true }
      }
    }
  },
  "ai": {
    "provider": "openai",
    "apiKey": "你的OpenAI API密钥",
    "model": "gpt-4"
  }
}

配置说明：

第五步：发布应用并测试

1. 在飞书开放台发布应用
2. 在飞书群里添加应用
3. 在群里发送：
   @AI 你好
4. AI 应该会回复

⚙️ 配置详解

获取用户 ID

在飞书中获取用户 ID 的方法：

# 方法1：通过 OpenClaw 日志查看首次互动的用户 ID
openclaw gateway logs

# 方法2：在飞书管理后台查看成员信息

群组配置

"groups": {
  "oc_xxxxxxxxxxxx": { "requireMention": false },
  "*": { "requireMention": true }
}

- 指定群 ID 可以设置该群不需要 @AI
- 通配符 * 表示其他所有群需要 @AI

AI 服务配置

支持多种 AI 服务：

"ai": {
  "provider": "openai",  // 或 anthropic、gemini、qwen
  "apiKey": "sk-xxxxxx",
  "baseURL": "https://api.openai.com/v1",  // 可选，自定义 API 地址
  "model": "gpt-4"
}

🔐 内网部署方案

方案一：内网穿透

使用 ngrok：

# 安装 ngrok
brew install ngrok  # macOS
choco install ngrok  # Windows

# 启动穿透
ngrok http 18789

将生成的 https://xxxx.ngrok.io 填入飞书事件订阅 URL。

使用 frp（自建）：

# frpc.ini
[common]
serverAddr = 你的服务器IP
serverPort = 7000

[openclaw]
type = http
localPort = 18789
customDomains = your-domain.com

方案二：公网服务器

将 OpenClaw 部署到公网服务器：

# 服务器上安装
curl -fsSL https://openclaw.ai/install.sh | bash

# 配置 0.0.0.0 监听
openclaw gateway --host 0.0.0.0 --port 18789

# 配置 Nginx 反向代理（可选）

🛠️ 常见问题

Q1: 飞书事件订阅验证失败？

检查：

1. Gateway 是否运行：openclaw gateway status
2. URL 是否可访问：用浏览器打开测试
3. 服务器防火墙是否开放端口

Q2: AI 不回复？

排查：

1. 检查 allowFrom 是否包含发送者 ID
2. 群聊是否使用了 @AI
3. 查看 Gateway 日志：openclaw gateway logs
4. 验证 AI API 配置是否正确

Q3: 如何获取群组 ID？

在群里 @AI 发送任意消息，然后运行：

openclaw gateway logs | grep "chat_id"

Q4: 内网环境如何使用？

内网环境需要：

1. 使用内网穿透暴露 Gateway 到公网
2. 或使用飞书企业版内网机器人（需申请）
3. 或在内部服务器部署 OpenClaw

📊 进阶用法

1. 多 AI 切换

"ai": {
  "providers": {
    "gpt4": {
      "provider": "openai",
      "model": "gpt-4"
    },
    "claude": {
      "provider": "anthropic",
      "model": "claude-3-opus"
    }
  },
  "default": "gpt4"
}

在群里使用：@AI[gpt4] 问题 或 @AI[claude] 问题

2. 自定义指令

"channels": {
  "feishu": {
    "systemPrompt": "你是一个专业的技术顾问，回答简洁专业。"
  }
}

3. 会话隔离

每个用户/群组独立会话，自动记忆上下文。

🔗 相关资源

📌 总结

三步接入飞书：

1. ✅ 创建飞书应用，获取 App ID/Secret
2. ✅ 配置 OpenClaw，填写凭证
3. ✅ 发布应用，群里 @AI 使用

版本： v2026.3.14

工具的价值在于解决问题，而不是增加复杂度。

让 AI 在你熟悉的飞书里待命，用的时候喊一声就好。

如果这篇文章对你有帮助

点个「在看」，让更多人看到~