排错速查

报错了？先按这张急救表排查

正在报错的人先不要换一堆工具。先判断是哪类问题，再按 Key、Base URL、日志、额度、端口和权限顺序查。

你现在是哪类问题？

错误码速查

错误码：401 鉴权失败

先查：

  1. 先看日志

    用失败时间或请求 ID 找到对应请求，确认认证头是否到达网关

  2. Key 是否粘错

    对照后台重新复制 Key，留意首尾空格

  3. BASE_URL 是否配套

    官方 Key 配 api.openai.com，中转 Key 配中转地址

  4. Key 是否被禁

    去后台看是否被作废 / 触发风控，必要时重新生成

错误码：403 权限或分组拒绝

先查：

  1. 先看日志

    确认拒绝来自 Key 分组、模型权限、接口权限还是安全策略

  2. 检查分组

    确认当前 Key 所属分组允许使用目标模型和接口

  3. 不要盲目换 Key

    先定位权限项；重复创建同权限 Key 通常不会解决问题

错误码：404 路径、协议或资源不存在

先查：

  1. 先看日志

    区分 endpoint 不存在、模型不存在和网关没有匹配到路由

  2. 按工具核对

    Codex、Claude Code 与 OpenAI 兼容客户端使用不同入口，去 Help 选择对应教程

  3. 检查拼接

    确认没有重复 `/v1`、把完整 endpoint 填进 Base URL，或照抄旧模型 ID

错误码：429 频率、并发或配额受限

先查：

  1. 先看日志

    确认限制来自请求频率、并发、配额还是上游模型

  2. 降并发

    把并发降到 1，确认单请求能跑通

  3. 看 RPM / TPM

    对照平台限制，必要时升档

  4. 拆批 + 间隔

    批量任务加 sleep，分批跑

错误码：503 网关或上游暂时不可用

先查：

  1. 先看日志

    用失败时间或请求 ID 确认错误来自网关还是上游模型

  2. 对比模型

    用同一 Key 测另一个当前可用模型，确认是否只有某型号失败

  3. 限制重试

    短暂故障可退避重试；不要无上限连续请求

错误码：522 网关到上游连接超时

先查：

  1. 先看日志

    用失败时间或请求 ID 确认连接在哪个上游节点超时

  2. 按工具核对入口

    不要套通用 `/v1`；从 Help 进入 Codex、Claude Code 或对应客户端教程

  3. 限次对比

    可退避重试一次或对比另一个当前可用模型，不要连续无上限重试

错误码：524 请求链路超时

先查：

  1. 先看日志

    确认网关已连接上游但等待响应超时，并记录请求耗时

  2. 拆任务

    把长输入拆段处理，避免单次请求过长

  3. 按工具核对入口

    地址与超时排查按对应客户端的 Help 教程处理，不套通用 `/v1`

  4. 对比可用模型

    若任务允许，从当前 Key 分组换一个响应更快的模型复测

错误码：Gateway OpenClaw 网关启动失败

先查：

  1. 跑官方排查阶梯

    status → gateway status → logs --follow → doctor → channels status --probe

  2. 核对默认端口

    本地默认 18789；先确认 PID，再正常停止目标服务或调整配置

  3. 按安装方式查配置

    普通安装看 onboarding/openclaw.json/auth profile；Docker 看官方 setup 与 Compose

错误码：chat not found Telegram Bot 找不到聊天

先查：

  1. Bot 是否进群

    群聊场景下 Bot 必须被邀请进群且有发消息权限

  2. 用户是否 /start

    私聊场景下用户必须先发 /start 才能被 Bot 主动 push

  3. Chat ID 是否真实

    先查 webhook；未配置时用 getUpdates，已配置时看投递日志。群常用负数 ID，公开频道可用 @channelusername

错误码：ECONNREFUSED 连接被拒绝

先查：

  1. 目标服务是否启动

    确认你要连的服务（OpenClaw、数据库、本地 API）正在运行

  2. 端口是否正确

    检查 URL 里的端口号和服务实际监听的端口是否一致

  3. 防火墙 / 代理

    检查拦截日志、回环地址和精确规则，只放行明确的目标进程或端口；不要整体关闭防火墙、VPN 或安全防护

错误码：model_not_found 模型名不存在

先查：

  1. 模型名拼写

    从当前 Key 分组或模型列表复制完整 ID，不照抄旧文章型号

  2. Key 权限

    有些 Key 没有开通该模型的权限，去后台确认

  3. 中转站是否支持

    不是所有中转站都转发所有模型，确认你的中转站支持该模型名

错误码：insufficient_quota 额度不足

先查：

  1. 查额度来源

    去控制台确认余额、订阅或临时权益中的哪一项已用完

  2. 检查 Key 分组

    确认 Key 属于预期分组，并查看该分组的额度和模型权限

  3. 核对实际计费

    结合模型基准价、倍率、计费单位和日志判断消耗，不只看倍率

错误码：context_length_exceeded 输入超过模型上下文窗口

先查：

  1. 缩短输入

    删掉不必要的历史消息或资料，只保留当前任务需要的内容

  2. 切片检索

    长文档不要全塞进去，用 RAG 只检索相关段落

  3. 核对模型限制

    从当前分组选择支持更大有效上下文的模型，并核对上下文、最大输入和最大输出限制

工具速查

  • OpenClawAgent 工作台

    适合：做客服 / 知识库 / Telegram Bot 这类有界面的 Agent

    不适合：纯写代码、跑 IDE 内任务

    看详细 →
  • Claude CodeAI 代码助手

    适合：对话式改代码、单文件调试、验收目标收尾、claude agents 管后台会话

    不适合：没有验收条件就直接放它改生产项目

    看详细 →
  • CodexAI 代码助手

    适合：短任务、长任务、多文件工程、AGENTS 约束与自动验证；Codex App 可按当前支持范围使用 Computer Use

    不适合：把 CLI 当成桌面控制工具，或在敏感窗口里无监督乱点

    看详细 →
  • Codex++Codex Desktop 扩展

    适合：在明确接受第三方 App patch 风险时，为 Codex Desktop 增加快捷键、Better Terminal、Better Browser 等界面 tweak

    不适合：只想稳定使用官方 Codex、不想承担 App patch 和 repair 风险

    看详细 →
  • Windows AI 编程环境本机环境

    适合：稳定运行 Codex App / CLI / Computer Use、Claude Code CLI、WSL2 和 Git Bash

    不适合：不愿区分 Windows 原生与 WSL2 路径的混用场景

    看详细 →
  • CursorAI 代码助手

    适合：编辑器内补全 / 多文件改动 / 团队协作

    不适合：无 IDE 的纯命令行任务

    看详细 →
  • Telegram Bot对外入口

    适合：把 Agent 接到群、私聊、定时通知

    不适合：需要复杂网页交互的场景

    看详细 →
  • 1A1API 中转站API 通道

    适合：开通快、统一接口、多家模型切换

    不适合：对供应商稳定性要求极高的核心生产

    看详细 →
  • 1A1 Listing Studio电商 AI 工具

    适合：用户填自己的 1A1API Key，生成电商文案、图片 Prompt、AI 搜索文件和素材包

    不适合：无 Key 公共白嫖、精准修图或全自动一键上架

    看详细 →
  • 1A1API Image2.0 生图 Skill图像模型

    适合：用生图专用分组 Key 调 gpt-image-2，做电商图、海报、封面和 Agent 配图流程

    不适合：把真实 Key 写进前端、提示词或公开仓库

    看详细 →
  • Skills CLI技能包管理

    适合：搜索、安装、更新 Claude Code / Codex / Cursor 等 Agent 技能

    不适合：不想审查来源、只想一次性跑任务

    看详细 →
  • Open Design设计 Agent 工作台

    适合：用 Claude Code / Codex / OpenCode 生成网页、移动端、海报和 PPT 原型

    不适合：直接当生产级设计系统或无需审查就上线

    看详细 →
  • Awesome DESIGN.md设计参照库

    适合：给 Claude Code、Codex、OpenCode 或 Open Design 选择可读的视觉规则，再生成自己的网页、文档或后台原型

    不适合：照抄第三方品牌、Logo、文案、图片、专有字体或直接当生产设计规范

    看详细 →
  • Agent Reach搜索与读取

    适合：让 Agent 搜网页、GitHub、Reddit、YouTube、小红书、B站和 RSS

    不适合：需要绕过平台规则或用主账号批量自动化

    看详细 →
  • MediaCrawler内容研究采集

    适合：小规模研究小红书、抖音、B站、微博、贴吧、知乎的公开内容和评论

    不适合：商业化大规模爬虫、采集隐私数据或违反平台规则

    看详细 →
  • OpenCLI / 平台 CLI平台自动化

    适合：复用登录态，把平台搜索、阅读、导出转成 Agent 可调用命令

    不适合：自动评论、自动发帖、主账号高频操作

    看详细 →