OpenClaw 小白使用手册

📱 OpenClaw 是什么？

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

核心功能

功能	说明
🤖 多 AI 支持	ChatGPT、Claude、Gemini、通义千问、文心一言等
💬 平台接入	飞书、企业微信、钉钉
🔌 本地部署	数据自主可控，支持内网环境
🛡️ 权限管理	支持白名单、群组@触发

🚀 快速开始

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

📲 接入飞书（重点）

第一步：创建飞书应用

打开飞书开放平台
创建企业自建应用

应用名称：如「AI 助手」
应用描述：随意填写

获取凭证（记录这些信息）

App ID
App Secret

第二步：配置权限

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

权限名称	权限值	用途
接收群聊消息	`im:message`	接收群消息
发送消息	`im:message`	发送 AI 回复
获取群组信息	`im:chat`	识别群组

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

第三步：配置事件订阅

在飞书开放台进入「事件订阅」
添加事件：
im.message.receive_v1（接收消息）
配置请求 URL：

需要 OpenClaw Gateway 能被外网访问
使用内网穿透（如 ngrok、frp）或公网服务器
URL 格式：https://你的域名/feishu/events

验证 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"
  }
}

配置说明：

字段	说明
`appId`	飞书应用的 App ID
`appSecret`	飞书应用的 App Secret
`encryptKey`	加密 Key（事件订阅中获取）
`verificationToken`	验证 Token（事件订阅中获取）
`allowFrom`	白名单用户 ID，只有这些用户可以调用 AI
`requireMention`	群聊是否需要 @AI 才触发

第五步：发布应用并测试

在飞书开放台发布应用
在飞书群里添加应用
在群里发送：
@AI 你好
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: 飞书事件订阅验证失败？

检查：

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

Q2: AI 不回复？

排查：

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

Q3: 如何获取群组 ID？

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

openclaw gateway logs | grep "chat_id"

Q4: 内网环境如何使用？

内网环境需要：

使用内网穿透暴露 Gateway 到公网
或使用飞书企业版内网机器人（需申请）
或在内部服务器部署 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. 会话隔离

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

🔗 相关资源

资源	链接
官网	openclaw.ai
文档	docs.openclaw.ai
GitHub	github.com/openclaw/openclaw

📌 总结

三步接入飞书：

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

版本： v2026.3.14

工具的价值在于解决问题，而不是增加复杂度。
让 AI 在你熟悉的飞书里待命，用的时候喊一声就好。

如果这篇文章对你有帮助

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