OpenClaw + 飞书机器人部署实战：从踩坑到成功

目录

本文记录了我部署 OpenClaw 个人 AI 助手并接入飞书机器人的完整过程，包括遇到的各种坑和解决方案。

项目介绍

OpenClaw 是一个本地运行的个人 AI 助手，可以连接到各种消息平台（Telegram、Discord、飞书等）。与其他 AI 工具不同，OpenClaw 是”从给建议到做事情”的执行引擎，能够：

• 读取本地文件和执行命令
• 连接飞书、Telegram 等 IM 平台
• 集成多种 AI 模型（OpenAI、Kimi、Claude 等）
• 通过长连接或 Webhook 接收消息

环境准备

系统要求

• Ubuntu 22.04+ / macOS / Windows
• Node.js 22 或更新版本
• 飞书开发者账号

安装 OpenClaw

# 全局安装
npm install -g openclaw

# 验证安装
openclaw --version

部署过程

1. 初始化配置

使用非交互模式快速部署：

openclaw onboard \
  --non-interactive \
  --accept-risk \
  --flow quickstart \
  --auth-choice synthetic-api-key \
  --synthetic-api-key "sk-synthetic-$(date +%s)" \
  --install-daemon

部署成功后，Gateway 服务会在后台运行：

• Dashboard: http://127.0.0.1:18789/
• WebSocket: ws://127.0.0.1:18789
• Systemd 服务: openclaw-gateway.service

2. 配置飞书机器人

在飞书开发者后台（https://open.feishu.cn/app/）创建应用后，配置以下信息：

# 设置飞书 AppID 和 AppSecret
openclaw config set channels.feishu.appId "cli_xxxxxxxxxxxx"
openclaw config set channels.feishu.appSecret "xxxxxxxxxxxx"
openclaw config set channels.feishu.enabled true

# 重启服务
systemctl --user restart openclaw-gateway

3. 配置 Kimi AI 模型

OpenClaw 默认使用 synthetic 模型（模拟环境），要接入真实的 Kimi API：

方法：环境变量配置（推荐）

# 创建 systemd 环境变量配置
mkdir -p ~/.config/systemd/user/openclaw-gateway.service.d/

cat > ~/.config/systemd/user/openclaw-gateway.service.d/env.conf << 'EOF'
[Service]
Environment="MOONSHOT_API_KEY=sk-你的MoonshotAPIKey"
EOF

# 重新加载并重启
systemctl --user daemon-reload
systemctl --user restart openclaw-gateway

踩坑记录

坑 1：401 Invalid Authentication

问题：配置 API Key 后仍然返回 401 错误

原因：API Key 配置在 models.providers.moonshot.apiKey 中，但 OpenClaw 实际从 auth.profiles 读取认证信息

解决：使用环境变量 MOONSHOT_API_KEY 方式配置，避免配置文件格式问题

坑 2：Kimi Code vs Moonshot AI

问题：在 Kimi Code 控制台（www.kimi.com/code）申请的 API Key 无法使用

原因：这是两个不同的服务：

• Kimi Code：面向代码场景的会员服务
• Moonshot AI（platform.moonshot.cn）：开发者 API 平台

解决：必须在 https://platform.moonshot.cn/ 申请 API Key

坑 3：模型 ID 错误

问题：模型不存在错误

Not found the model kimi-k2-5 or Permission denied

原因：OpenClaw 配置的模型 ID 与实际不符

解决：Moonshot API 支持的模型列表：

• kimi-k2.5（注意带点，不是 kimi-k2-5）
• kimi-k2-turbo-preview
• moonshot-v1-8k
• moonshot-v1-32k
• 等

坑 4：飞书权限不足

问题：收到消息但无法获取发送者信息

错误码：99991672

解决：在飞书开发者后台开通权限：

• contact:contact.base:readonly
• im:message:send_as_bot
• im:chat:readonly
• im:message.group_msg

坑 5：消息无回应

问题：飞书发送消息，机器人不回复

原因：ackReactionScope 配置为 group-mentions，只在被 @ 时回复

解决：

openclaw config set messages.ackReactionScope all
systemctl --user restart openclaw-gateway

验证部署

查看服务状态

openclaw status

关键检查项：

• Gateway: reachable
• Feishu: ON / OK
• Sessions: 显示活跃会话

查看实时日志

openclaw logs --follow

测试 API 连通性

curl -X POST https://api.moonshot.cn/v1/chat/completions \
  -H "Authorization: Bearer $MOONSHOT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kimi-k2.5",
    "messages": [{"role": "user", "content": "你好"}]
  }'

最终配置参考

目录结构

~/.openclaw/
├── openclaw.json          # 主配置文件
├── workspace/             # 工作目录
├── agents/
│   └── main/
│       └── sessions/      # 会话存储
└── logs/                  # 日志文件

关键配置项

~/.openclaw/openclaw.json（部分）：

{
  "models": {
    "mode": "merge",
    "providers": {
      "moonshot": {
        "baseUrl": "https://api.moonshot.cn/v1",
        "api": "openai-completions",
        "models": [{
          "id": "kimi-k2.5",
          "name": "Kimi K2.5",
          "contextWindow": 256000,
          "maxTokens": 8192
        }]
      }
    }
  },
  "agents": {
    "defaults": {
      "model": {
        "primary": "moonshot/kimi-k2.5"
      }
    }
  },
  "channels": {
    "feishu": {
      "appId": "cli_xxxxxxxx",
      "appSecret": "xxxxxxxx",
      "enabled": true
    }
  },
  "messages": {
    "ackReactionScope": "all"
  }
}

常用命令

# 查看状态
openclaw status
openclaw status --deep

# 查看日志
openclaw logs --follow

# 重启服务
systemctl --user restart openclaw-gateway

# 安全配置检查
openclaw security audit

# 查看飞书通道日志
openclaw channels logs --channel feishu

总结

通过本文的踩坑记录，希望你能在 10 分钟内完成 OpenClaw + 飞书的部署，而不是像我一样折腾几个小时 😅

核心要点：

1. 使用 Moonshot AI 平台（不是 Kimi Code）的 API Key
2. 通过 环境变量 配置 API Key 最稳定
3. 注意模型 ID 是 kimi-k2.5（带点）
4. 飞书后台需要开通通讯录和消息权限

现在，你的飞书机器人已经可以智能回复消息了！🎉

---

参考链接：

• OpenClaw 文档：https://docs.openclaw.ai/
• Moonshot AI：https://platform.moonshot.cn/
• 飞书开放平台：https://open.feishu.cn/

文章作者：阿文

文章链接： https://www.awen.me/post/fa547307.html

版权声明：本博客所有文章除特别声明外，均采用 CC BY-NC-SA 4.0 许可协议。转载请注明来自 阿文的博客！