OpenClaw+Coze集成常见问题大全：20个报错解决方案

前言

在用 OpenClaw 集成 Coze 时，你是否遇到过各种奇怪的报错？Token 不够、权限不足、连接失败...这些问题消耗了大量调试时间。

本文汇总了 20 个最常见的报错，按照问题类型分为 5 大类，每类提供 4 个典型问题的解决方案。收藏这份手册，下次遇到问题直接查，节省你的排错时间。

一、权限与认证问题

问题1：token_expired - Access Token 已过期

错误信息：

复制代码

{"code": 99991663, "msg": "token_expired"}

原因：飞书 Access Token 有效期为 2 小时，过期后需要刷新。

解决方案：

复制代码

# 方案1：使用 OAuth 刷新 Token
from feishu_oauth import refresh_token

new_token = refresh_token(refresh_token="your_refresh_token")

# 方案2：撤销授权让系统自动重新授权
# 调用 feishu_oauth revoke 后，系统会自动重新发起授权流程

预防措施：设置 Token 刷新机制，在过期前自动更新。

问题2：permission denied - 缺少必要权限

错误信息：

复制代码

{"code": 99991400, "msg": "permission denied"}

原因：应用没有开通所需的权限范围。

解决方案：

登录飞书开放平台
进入应用管理 → 权限管理
添加缺失的权限，如 contact:contact.base:readonly
重新发布应用

常见权限对照表：

|--------|-------------------------------|
| 功能 | 所需权限 |
| 读取用户信息 | contact:contact.base:readonly |
| 发送消息 | im:message:send_as_bot |
| 创建日历 | calendar:event:write |
| 管理任务 | task:task:write |

问题3：unauthorized - 签名验证失败

错误信息：

复制代码

{"code": 99991664, "msg": "unauthorized"}

原因：请求签名不正确或 App Secret 错误。

解决方案：

复制代码

# 检查签名生成逻辑
import hashlib
import base64
import time

def generate_sign(app_id, app_secret):
    t = str(int(time.time()))
    sign_str = app_id + t
    sign = hashlib.sha256(sign_str.encode()).digest()
    return base64.b64encode(sign).decode(), t

# 确保使用正确的 App Secret

问题4：invalid app access token - App Token 无效

错误信息：

复制代码

{"code": 99991668, "msg": "invalid app access token"}

原因：App Access Token 格式错误或已过期（有效期 24 小时）。

解决方案：

复制代码

# 重新获取 App Access Token
import requests

def get_app_access_token(app_id, app_secret):
    url = "https://open.feishu.cn/open-apis/auth/v3/app_access_token/internal"
    data = {
        "app_id": app_id,
        "app_secret": app_secret
    }
    resp = requests.post(url, json=data)
    return resp.json().get("app_access_token")

二、API 调用问题

问题5：invalid parameter - 参数格式错误

错误信息：

复制代码

{"code": 400, "msg": "invalid parameter"}

原因：参数类型、格式或必填项不符合要求。

解决方案：

检查参数是否为 JSON 格式
确认必填参数已填写
验证字段类型（字符串、数字、数组）
人员选择器字段使用 [{"id": "ou_xxx"}] 格式

常见参数错误：

复制代码

# 错误示例
{"name": 123}  # name 应该是字符串

# 正确示例
{"name": "张三"}

# 人员字段错误示例
{"user": "ou_xxx"}  # 错误

# 人员字段正确示例
{"user": [{"id": "ou_xxx"}]}

问题6：rate limit exceeded - 请求频率超限

错误信息：

复制代码

{"code": 429, "msg": "rate limit exceeded"}

原因：短时间内请求次数过多。

解决方案：

复制代码

import time
from requests.adapters import HTTPAdapter
from urllib3.util.retry import Retry

# 设置重试机制
session = requests.Session()
retry = Retry(
    total=3,
    backoff_factor=1,  # 指数退避：1s, 2s, 4s
    status_forcelist=[429, 500, 502, 503, 504]
)
adapter = HTTPAdapter(max_retries=retry)
session.mount('http://', adapter)
session.mount('https://', adapter)

频率限制参考：

|----------|--------|
| 接口类型 | 限制 |
| 发送消息 | 50次/秒 |
| 读取消息 | 100次/秒 |
| 用户信息 | 10次/秒 |

问题7：invalid message type - 消息类型不支持

错误信息：

复制代码

{"code": 230001, "msg": "invalid message type"}

原因：发送的消息类型不被支持。

解决方案：

复制代码

# 支持的消息类型
msg_types = ["text", "post", "image", "file", "audio", "media", "interactive", "share_chat", "share_user"]

# 发送文本消息
message = {
    "msg_type": "text",
    "content": '{"text": "Hello World"}'
}

# 发送富文本消息
message = {
    "msg_type": "post",
    "content": '{"zh_cn": {"title": "标题", "content": [["tag": "text", "text": "正文"]]}}'
}

问题8：chat not found - 会话不存在

错误信息：

复制代码

{"code": 230017, "msg": "chat not found"}

原因：指定的 chat_id 不存在或已失效。

解决方案：

复制代码

# 确认 chat_id 格式正确（oc_xxx）
# 群聊 chat_id 以 oc_ 开头
# 单聊需要先创建或获取 conversation

# 正确获取单聊 chat_id
def get_p2p_chat_id(open_id):
    url = f"https://open.feishu.cn/open-apis/im/v1/chats?user_id_type=open_id"
    # 通过 API 创建单聊会话

三、OpenClaw 配置问题

问题9：gateway.bind failed - 网关绑定失败

错误信息：

复制代码

Gateway bind failed: connection refused

原因：OpenClaw Gateway 服务未启动或端口被占用。

解决方案：

复制代码

# 1. 检查 Gateway 状态
openclaw gateway status

# 2. 如未运行，启动 Gateway
openclaw gateway start

# 3. 检查端口占用
lsof -i :18789

# 4. 如端口被占用，修改配置或关闭占用进程

问题10：pairing required - 设备未配对

错误信息：

复制代码

{"code": "pairing_required", "msg": "bootstrap token invalid or expired"}

原因：移动端 App 未完成配对。

解决方案：

在 OpenClaw App 中进入「设置」→「配对」
扫描网页端显示的配对二维码
或手动输入 6 位配对码
确保手机和电脑在同一网络下

问题11：plugin entry not found - 插件入口缺失

错误信息：

复制代码

Plugin entry not found: feishu

原因：飞书插件未正确安装或配置。

解决方案：

复制代码

# 检查配置文件 plugins/entries/device-pair/config.json
{
  "enabled": true,
  "publicUrl": "https://your-public-url.com"
}

# 重新加载插件
openclaw plugins reload

问题12：webhook signature verification failed - 签名验证失败

错误信息：

复制代码

Webhook signature verification failed

原因：Webhook 回调签名校验失败。

解决方案：

复制代码

import hmac
import hashlib

def verify_webhook_sign(token, timestamp, sign, secret):
    str_to_sign = token + timestamp
    my_sign = hmac.new(
        secret.encode(),
        str_to_sign.encode(),
        hashlib.sha256
    ).digest().hex()
    return my_sign == sign

# 确保使用正确的 Verification Token

四、Coze 集成问题

问题13：API request failed - Coze API 请求失败

错误信息：

复制代码

Coze API request failed: 401 Unauthorized

原因：Coze API Token 错误或过期。

解决方案：

复制代码

# 检查 Coze API Token 配置
import os

coze_api_token = os.getenv("COZE_API_TOKEN")
if not coze_api_token:
    raise ValueError("COZE_API_TOKEN not set")

# 确保使用正确的 API Token（个人令牌 vs Bot 令牌）

问题14：workflow execution timeout - 工作流执行超时

错误信息：

复制代码

Workflow execution timeout after 30s

原因：工作流运行时间超过限制。

解决方案：

简化工作流步骤
将长时间任务拆分为多个子工作流
使用异步执行模式
检查是否有死循环或无限等待节点

问题15：channel not supported - 渠道不支持

错误信息：

复制代码

Channel not supported: telegram

原因：尝试在不支持的渠道执行操作。

解决方案：

复制代码

# 检查当前渠道支持情况
supported_channels = ["feishu", "wechat", "discord", "telegram"]

# 在发送前检查渠道
if channel not in supported_channels:
    raise ValueError(f"Channel {channel} not supported")

问题16：tool call failed - 工具调用失败

错误信息：

复制代码

Tool call failed: feishu_im_user_message - permission denied

原因：以用户身份调用 API 时权限不足。

解决方案：

用户需要完成飞书 OAuth 授权
检查用户是否在授权白名单中
确认应用已开通相应权限

五、数据与格式问题

问题17：invalid date format - 日期格式错误

错误信息：

复制代码

{"code": 11212, "msg": "invalid date format"}

原因：日期字段未使用 ISO 8601 格式。

解决方案：

复制代码

from datetime import datetime
import pytz

# 正确格式：ISO 8601 / RFC 3339
tz = pytz.timezone('Asia/Shanghai')
dt = datetime.now(tz)
correct_format = dt.isoformat()
# 输出：2026-04-06T21:00:00+08:00

# 日历事件时间格式
event_time = {
    "start_time": "2026-04-06T21:00:00+08:00",
    "end_time": "2026-04-06T22:00:00+08:00"
}

问题18：file too large - 文件大小超限

错误信息：

复制代码

{"code": 230026, "msg": "file too large"}

原因：上传的文件超过大小限制。

解决方案：

|----------|----------|
| 文件类型 | 大小限制 |
| 图片 | 30MB |
| 视频 | 20MB |
| 普通文件 | 100MB |

压缩大文件或分块上传。

问题19：record not found - 记录不存在

错误信息：

复制代码

{"code": 130013, "msg": "record not found"}

原因：多维表格中指定的记录不存在。

解决方案：

复制代码

# 先查询确认记录存在
from feishu_bitable_app_table_record import list

result = feishu_bitable_app_table_record(
    action="list",
    app_token="your_app_token",
    table_id="your_table_id",
    filter={
        "conjunction": "and",
        "conditions": [
            {"field_name": "标题", "operator": "is", "value": ["目标"]}
        ]
    }
)

问题20：markdown parse error - Markdown 解析错误

错误信息：

复制代码

Markdown parse error at line 45

原因：飞书文档不支持的 Markdown 语法。

解决方案：

避免使用脚注语法
表格内不支持嵌套列表
代码块语言标识使用小写（如 python 而非 Python）
图片使用飞书支持的格式（jpg、png、gif、webp）

总结

遇到报错时，按以下顺序排查：

看错误码 - 400/401/403/429 不同类型代表不同问题
查文档 - 飞书和 Coze 官方文档有详细说明
看日志 - OpenClaw 日志记录了完整调用链
简化场景 - 最小复现问题更容易定位根因

收藏本文，下次遇到问题直接查，节省 50% 排错时间。

文章来源： 觅合可及coze工作流学习分享