## 背景

在将 OpenClaw 的模型从 `aaa` 切换到 `bbb`，并将 API 代理从 `suxxx` 更换为 `rexxx` 之后，飞书机器人出现 403 报错，私聊场景下无法正常回复。

本文记录完整的排查思路和解决过程。

---

## 环境信息

| 项目 | 说明 |
|------|------|
| 服务器 | Tencent Cloud Lighthouse Ubuntu 22.04 |
| OpenClaw 版本 | 2026.4.21 (f788c88) |
| Gateway 端口 | 31xx (lan 模式) |
| 飞书 App ID | `cli_a***3`（已脱敏） |
| 目标模型 | `bbb`（通过 `rexxx` 代理） |

---

## 第一阶段：表面现象分析

### 错误信息

飞书客户端私聊机器人时，返回：

```
HTTP 403 permission_error: This group does not allow /v1/messages dispatch
```

### 初步判断

看到 "group does not allow"，第一反应是**飞书群权限问题**。但用户确认是私聊场景，不存在群组限制。这意味着 403 并非来自飞书平台本身。

---

## 第二阶段：日志深入分析

查看 OpenClaw 日志，发现两种 403 错误交替出现：

```json
{
  "event": "embedded_run_agent_end",
  "isError": true,
  "error": "403 Insufficient account balance",
  "model": "aaa",
  "provider": "api-xxx"
}
```

```json
{
  "event": "embedded_run_agent_end",
  "isError": true,
  "error": "HTTP 403 permission_error: This group does not allow /v1/messages dispatch",
  "model": "bbb",
  "provider": "api-xxx",
  "providerErrorType": "permission_error",
  "httpCode": "403"
}
```

### 关键线索

- 第一个错误（余额不足）是旧 API (`suxxx`) 遗留问题，切换到新 API 后不再出现
- 第二个错误发生在调用 `bbb` 模型时，错误类型是 `providerErrorType: permission_error`
- 注意路径：`/v1/messages` —— 这是 **Anthropic Messages API** 的端点

**推理**：错误来自 `rexxx` 代理服务，而非飞书平台。服务不理解 `/v1/messages` 路径，返回了 403。

### 附带清理：停用旧代理

在排查过程中发现，原配置使用的本地中转代理（Python HTTP proxy，监听 `127.0.0.1:19999`）仍在运行。该代理将请求转发至旧服务 `suxxx`，已完成历史使命。将其停止并清理：

```bash
# 查看 19999 端口进程
ss -tlnp | grep 19999
# LISTEN 0 5  127.0.0.1:19999  ...  users:(("python3",pid=1225546,fd=3))

# 终止进程
kill 1225546

# 清理脚本和缓存文件
rm -f /tmp/echo_server.py /tmp/capture_*.json

# 确认端口已释放
ss -tlnp | grep 19999
# (无输出，清理完成)
```

---

## 第三阶段：API 直连验证

直接用 `curl` 测试 `rexxx` 的连通性：

```bash
curl -s -X POST https://rexxx/v1/chat/completions \
  -H "Authorization: Bearer sk-***REDACTED***" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "bbb",
    "messages": [{"role": "user", "content": "hi"}],
    "max_tokens": 10
  }'
```

返回：

```json
{
  "id": "chxxx",
  "model": "xopglm51",
  "object": "chat.completion",
  "choices": [{
    "message": {
      "role": "assistant",
      "content": "Hello! How can I help you today?"
    },
    "finish_reason": "length"
  }]
}
```

**结论**：API 服务和 API Key 均正常，问题锁定在 OpenClaw 的协议配置上。

---

## 第四阶段：根因确认

查看 `api-xxx` provider 的完整配置：

```bash
openclaw config get models.providers.api-xxx | jq
```

```json
{
  "baseUrl": "https://rexxx/v1",
  "api": "anthropic-messages",
  "models": [{
    "id": "bbb",
    "api": "anthropic-messages"
  }]
}
```

**根因**：`api` 字段被设置为 `"anthropic-messages"`。

- Anthropic Messages API 的调用路径是 `POST /v1/messages`
- 但 `rexxx` 是一个 **OpenAI 兼容**代理，只支持 `POST /v1/chat/completions`
- 服务收到 `/v1/messages` 请求后返回了 `This group does not allow /v1/messages dispatch`

---

## 第五阶段：修复

将 provider 和 model 的 API 协议从 `anthropic-messages` 改为 `openai-completions`：

```bash
# 修改 provider 的 API 协议
openclaw config set models.providers.api-xxx.api "openai-completions"

# 修改 model 的 API 协议
openclaw config set models.providers.api-xxx.models '[
  {
    "id": "bbb",
    "name": "xxx",
    "maxTokens": 8192,
    "api": "openai-completions",
    "input": ["text"],
    "contextWindow": 200000,
    "reasoning": false,
    "cost": {
      "input": 0,
      "output": 0,
      "cacheRead": 0,
      "cacheWrite": 0
    }
  }
]'

# 重启 Gateway
openclaw gateway restart
```

### 验证

```bash
openclaw config get models.providers.api-xxx.api
# 输出: openai-completions

openclaw config get models.providers.api-xxx.models | jq '.[0].api'
# 输出: "openai-completions"
```

飞书私聊测试正常回复，问题解决。

---

## 总结

### 故障链路

```
原架构（旧）:
  飞书 Bot → OpenClaw Gateway → api-xxx (anthropic-messages)
      → http://127.0.0.1:19999 (Python 中转代理)
      → https://suxxx

当前架构（新）:
  飞书 Bot → OpenClaw Gateway → api-xxx (openai-completions)
      → https://rexxx/v1/chat/completions

故障时（中间态）:
  飞书 Bot → OpenClaw Gateway → api-xxx (anthropic-messages)
      → POST https://rexxx/v1/messages  ← 协议不匹配
      → 403 This group does not allow /v1/messages dispatch
```

### 关键教训

1. **不要被错误信息字面含义误导**。"group does not allow" 看起来像群权限问题，实际是 API 协议不匹配
2. **对比 API 直接调用和框架调用的差异**。curl 直连正常 → 问题在框架层
3. **检查 provider 的 `api` 字段**。切换模型时，API 协议类型可能不兼容新服务
4. **及时清理旧基础设施**。模型迁移完成后，旧的中转代理、临时脚本应及时停用和清理，避免混淆排查方向

### 配置检查清单

更换 OpenClaw 模型时，确认以下配置项：

| 配置项 | 检查点 |
|--------|--------|
| `baseUrl` | 是否指向正确的代理服务 |
| `apiKey` | 是否为新服务的有效 Key |
| `models[].id` | 模型名称是否与服务端一致 |
| `api`（provider 级） | 协议类型是否匹配服务端 |
| `api`（model 级） | 协议类型是否匹配服务端 |
| agent 的 `model` | 是否指向正确的 provider/model |

---

## 附录：OpenClaw 支持的 API 协议

```
openai-completions     → POST /v1/chat/completions（OpenAI 格式）
openai-responses       → OpenAI Responses API
anthropic-messages     → POST /v1/messages（Anthropic 格式）
google-generative-ai   → Google Gemini API
github-copilot         → GitHub Copilot API
ollama                 → Ollama 本地模型
bedrock-converse-stream → AWS Bedrock
```

> **经验法则**：市面上大多数第三方代理（如 one-api、new-api、lobe-chat 网关）都兼容 `openai-completions` 协议，如不确定，优先选这个。


在将 OpenClaw 的模型从 aaa 切换到 bbb，并将 API 代理从 suxxx 更换为 rexxx 之后，飞书机器人出现 403 报错，私聊场景下无法正常回复。

OpenClaw 飞书机器人报 403 错误排查全记录：从 API 协议错配到完美修复

后端

开发工具

网络与通信

OpenClaw模型切换后飞书机器人403报错排查：从API协议不匹配到完整解决方案。记录错误分析、日志排查、API验证及配置修复全过程，提供关键检查清单和协议兼容性建议，帮助开发者快速定位类似问题。

代码解释

服务器

OpenClaw

Python

4核4G3M云服务器 新用户低至38元/年！

lighthouse

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

EdgeOne AI 安全实战专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

OpenClaw 飞书机器人报 403 错误排查全记录：从 API 协议错配到完美修复-腾讯云开发者社区-腾讯云

OpenClaw 飞书机器人报 403 错误排查全记录：从 API 协议错配到完美修复

OpenClaw 飞书机器人报 403 错误排查全记录：从 API 协议错配到完美修复

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐