OpenClaw API Key 错误怎么修：401、No API Key、429 与网关认证

OpenClaw 报 API Key 错误，先找到最早失败的请求及其接收方，再修改对应的凭证或配置。 No API key found for provider 要查所选 agent 的模型认证；Gateway 的 AUTH_TOKEN_MISMATCH 要查客户端连接令牌；429 要先分清模型服务商限流与 Gateway 入口认证限流。换一把模型 key 无法同时解决这三类问题。

开始排查时，保留失败时间、agent、会话所选模型、错误原文和已完成动作。随后在 Gateway 实际运行的主机与服务用户下查看状态和日志，对照运行中的配置，而不是只看个人终端里刚保存的设置。以下操作依据截至 2026 年 10 月 7 日的官方说明；本文没有执行账户认证、真实模型请求或生产服务恢复，末尾代码只验证虚构输入下的恢复决策。

快速答案：按第一条失败找到修复入口

先用下表选择方向。最后一句 all in cooldown、聊天窗口的“请求失败”或 HTTP 状态码，都可能缺少真正原因。

这张表按错误来源分流，不代表每个状态码只有一种原因。例如 Gateway 的 HTTP 429 可以是失败认证尝试过多，上游 401 也可能带有计费相关说明。Gateway HTTP 错误说明和模型失败分类都要求结合错误正文判断。

先核对实际进程、agent 和会话模型

在发生问题的 Gateway 环境中，先查看下面几项。把 YOUR_AGENT_ID 换成出错 agent 的准确 ID；本文没有在你的机器上执行这些命令。

openclaw status
openclaw gateway status
openclaw models status --agent YOUR_AGENT_ID
openclaw logs --follow

记录 Gateway 连接的地址、服务用户、配置与状态目录，以及失败请求实际使用的 provider/model。日志定位到该次运行后可停止跟随，保留必要的脱敏片段；不要把完整凭证、私人提示和整份环境变量贴进求助记录。

在出错聊天会话中继续查看：

/model status
/status

models status --agent 看 agent 配置中的默认与备用模型；它不检查聊天会话临时固定的模型。会话状态还要区分所选模型与本回合实际回答的备用模型。外部运行时自身的登录与可用性也可能独立于 OpenClaw 保存的认证记录。模型 CLI 文档说明了这些诊断的范围。

“配置状态正常”还没有证明模型请求成功。 不带 --probe 的状态命令不是推理测试，但可能解析凭证来源或检查服务商状态，也不能笼统称为完全离线。--check 返回 0 表示未发现相应认证、运行时或到期问题；返回 1 包含缺失、过期、不兼容、运行时不可用或不确定等问题；2 表示只有即将到期的问题。命令退出状态和输出正文要一起看，不能把错误对象或缺少的字段读成健康。

同样，Gateway 握手成功、/healthz 存活、模型目录可见，都不证明上游接受了这次请求。先确定到底是客户端连不上 Gateway，还是 Gateway 已连接但调用模型失败，后面的修复才有明确对象。

No API Key：有 key，为什么这个 agent 仍找不到？

这类错误说明当前选择没有找到可用认证，不等于电脑上从来没有保存过 key。按下面顺序检查：

1. 确认 provider 与运行时。 对照失败日志和会话选择，检查凭证属于哪个服务商、请求发往哪个地址。模型显示名相同，不代表使用同一登录方式。
2. 确认 Gateway 所在环境。 本机终端有变量、桌面工具已登录，不代表远程主机、服务用户或容器有相同来源。
3. 确认 agent 的覆盖与选择顺序。 共享认证可被同 ID 的 agent 本地记录覆盖，认证顺序也可能排除了有效记录。已存在的有效 key 若未被选中，应修选择原因，而不是立即新增重复凭证。
4. 确认显式凭证引用是否可用。 SecretRef 来源失败是读取或激活问题，不能直接归因于上游拒绝 key。状态中的“不确定”也不是验证成功。

当前凭证存储说明采用共享 ~/.openclaw/state/openclaw.sqlite，agent 本地状态位于 ~/.openclaw/agents/<agentId>/agent/openclaw-agent.sqlite。没有本地覆盖时可以读取共享记录，不要求把每把 key 复制到每个 agent。这里的路径用于理解来源关系，不是建议手工编辑数据库或从中提取令牌。

确认确实缺少 API key 后，可在实际 Gateway 主机的交互式终端使用当前认证助手：

openclaw models auth paste-api-key --provider YOUR_PROVIDER_ID --agent YOUR_AGENT_ID

将两个占位符换成实际 provider 与 agent，按交互提示输入该服务商的 API key；不要把 key 写在命令行里。这会更新配置或活动认证记录，需要先确认目标。要建立指定名称的备用 profile 时，按认证助手文档选择 --profile-id，不要无意中替换当前连接。paste-token 接收令牌材料，不能当作 API key 的通用入口。

修复后再次查看该 agent 的认证来源与不可用原因，再在原会话发送不含外部动作的短请求。状态不再报缺少凭证是第一步，收到同一路径的完整模型响应才是调用层的成功信号。

401：修服务商凭证，还是修 Gateway 令牌？

服务商拒绝：对照认证方式和实际地址

若最早的错误由模型服务商返回，核对 key 的签发方、账号、实际 baseUrl 和模型权限。某代理签发的 key 通常不能直接作为另一服务商的 key 使用；认证记录正确，也不会自动修正错配的端点。

官方认证说明把端点、API 适配器、模型 ID、headers 和超时等设置放在 models.providers.<id> 的 provider 配置中，而不是凭证记录里。不要沿用旧教程猜一个 model.anthropic.* 字段，也不要仅凭 sk- 前缀判断真假。

接下来按已选方式处理：

原生 Claude CLI 登录和在 OpenClaw 中选择相应运行时是两个动作。OpenClaw 不读取、保存、刷新或转发 Claude 的原生登录令牌；不要从登录文件复制 OAuth token 来填 OpenClaw 的 key。常驻 Gateway 使用 API key 是当前文档给出的可预测选项，已有原生登录或托管 token 则按各自运行时处理，不能凭模型名推断月费覆盖 API 账单。认证说明保留了这些方式的区别。

若错误是 missing authentication header，重点检查请求如何取得凭证以及中间接口是否保留相应认证头；“日志遮挡了认证值”不能证明没有发送 header。需要完成准确的主机、agent 和会话恢复时，继续看 OpenClaw 401 与 missing authentication header 排查。

Gateway 拒绝：按连接详情修客户端身份

客户端连接 OpenClaw Gateway 的凭证与模型 API key 分开。启用 Gateway OpenResponses HTTP 接口后，token/password 模式使用 Gateway 凭证的 Authorization: Bearer；默认未启用的接口可能返回 404。接口开关、模型列表响应和上游推理不是同一个验证对象。Gateway HTTP API 文档说明了入口与认证范围。

对于 Control UI 或 WebSocket，先看详细代码，而不是只看 1008：

按Control UI 排障文档处理对应身份；不要为排障关闭认证或扩大端口暴露。共享令牌也不自动替代设备身份，具有共享凭证的 HTTP 调用可能拥有完整 operator 权限，因此不能把它当作天然只读的测试。

渠道或机器人平台的 401/403 则先核对该渠道的账号、凭证与权限。渠道接收成功但模型失败，再回到模型诊断；模型能回复但渠道无法发送，也应继续处理渠道错误。

429 与 all in cooldown：先判断等待能否恢复

Gateway 入口认证限流先修客户端，模型临时限流才进入模型恢复。 如果 429 来自 Gateway 的失败认证尝试限制，按 Retry-After 等待并纠正连接凭证；切备用模型或换 IP、Origin 不能作为绕过方案。入口错误说明明确区分了这项限制。

若错误来自模型服务商，读取原始错误正文、实际账号与模型、等待或重置提示。恢复动作分三种：

• 临时速率或过载压力： 优先让当前运行完成有界自动恢复，减少后续并发和大工具输出。不要在界面还等待时再提交整条任务。
• 周期用量或账号访问耗尽： 根据真实恢复窗口或账号条件处理；没有 Retry-After 不代表可以无限重试，多个 key 共用账号也不会创造新的共享额度。
• all in cooldown： 回看各候选最早的失败与到期状态。它是暂时无可用候选的结果，不能证明一定是流量太大，更不是无效 key 的专属报错。

截至本次更新，模型重试文档对符合条件的模型临时限流最多执行 10 次总尝试；其他临时故障有另一组重试与连续故障窗口条件。上游要求的更长等待、运行截止时间和取消都可能改变结果，不要把所有错误塞进一个固定“等 60 秒”循环。

冷却和禁用可以保存在 SQLite 状态中。重启不清除上游额度，也不能保证清除持久冷却；计费或永久认证故障与普通冷却的恢复规则不同。先确认失败是否已修正、窗口是否到期、当前候选是否允许使用，再恢复任务，不手工删除数据库。模型 failover 文档给出了这部分状态与选择规则。

需要进一步区分模型配额、ClawHub 下载限流、持久冷却与具体等待条件，可继续看 OpenClaw 429、冷却与回退恢复。ClawHub 安装失败不能靠模型 API key 解除。

400 与 context_length_exceeded：修请求，不清空历史碰运气

Invalid beta flag 表示实际接口不接受相应字段。先查看失败请求采用的 provider/API 适配器，再核对它是否支持该能力。直连服务商、云平台与兼容代理可能接受不同字段；在不影响任务所需能力的前提下，移除不支持的参数或改用支持它的接口，再验证同一请求。

context_length_exceeded 则要检查失败请求实际模型的可用上下文。系统指令、工具定义、工作区文件、历史、附件和工具输出都可能计入请求，不能只数聊天字数。先保存已完成工作及未完成目标，再按运行时支持的压缩或新会话流程继续；不要删除历史来“刷新 key”。详细恢复见 OpenClaw 上下文超限与压缩失败处理。

如果换备用后才出现上下文错误，回看完整尝试链：原模型先失败、备用模型窗口或能力不同，可能是两个连续问题。不能把最后一个错误反推成最初认证失败，也不能假定换更大模型一定适合原任务。

改了配置还报错：查生效来源、Docker 与 SecretRef

先定位配置文件与结构问题：

openclaw config file
openclaw config validate
openclaw doctor

config file 给配置定位入口，validate 检查结构与已注册凭证引用的兼容性；它不能证明凭证后端接受 key，也不能验证 provider 特定参数的全部含义。Doctor 出现迁移或结构诊断时，先备份，按具体发现处理；不把 doctor --fix、强制重装或清认证库作为所有报错的第一步。配置 CLI 文档说明了这些检查与修复的边界。

常见的“我明明改好了”要沿来源继续查：

环境说明规定普通加载过程不会覆盖已经存在的进程环境值，但受管理服务有特定刷新规则；不要扩大成“任何环境变量永远覆盖任何配置字段”。Docker 的修改按官方环境文档通过相应 Compose 流程重新创建 Gateway，先确认持久卷、未完成工作和维护窗口，避免为了换变量重建存储。

排查变量时只记录必要项是否存在、来自哪个文件或服务定义，以及主机与用户是否正确。不要运行完整环境导出来证明配置，更不要把 key、Gateway token 或整个配置贴进公开日志。

显式 SecretRef 失败要修来源。凭证激活说明要求实际发送路径遵守激活条件；某些状态查询还能返回降级信息，不代表发送允许回退到另一把环境 key。删除引用让系统“碰巧能发”会改变原先安全与来源约定，应由对应维护者按授权的修复和重新加载流程处理。

旧 auth-profiles.json、auth-state.json 等文件属于已验证的迁移输入与历史归档，不是今天通用的运行时凭证编辑入口。若只在升级后失败，依 Doctor 的具体迁移发现保留原件再处理，不用旧 JSON 覆盖当前有效存储。存储与迁移说明可用于确认该分支。

502、TLS 与没回复：先排除非 key 故障

502 不自动证明服务商全局宕机。Gateway SSE 在连接成功后仍可能报告 response.failed，客户端未返回必需的结构化工具结果也可能形成本地契约错误。保留请求 ID、连接目标、错误正文及工具结果，先判断是否真的发生了上游失败。Gateway HTTP API 文档说明了流式失败和客户端工具交互。

遇到超时或连接中断，记录“结果未知”，核对文件和外部操作状态后再决定是否重试。HTTP POST 不是天然幂等，同一提示或任务 ID 也不能证明服务商会去重；不能把“没收到响应”写成“没调用、没收费、没执行”。HTTP 幂等语义要求非幂等重试具有相应保证。

TLS 错误先按证书过期、证书链与正确连接目标处理，由服务维护者配置可信证书或企业 CA。保持证书验证开启。Node 的 NODE_EXTRA_CA_CERTS 在进程启动时读取，显式指定客户端 ca 还会改变默认与额外根证书的使用方式，因此在运行进程里临时改变量不等于已修复信任链。Node 官方说明给出了这些条件。

技能未加载、插件启动失败、只读数据库、运行时命令不可用，或渠道策略忽略消息，都有自己的日志与修复入口。模型 key 正确不能解决这些问题；先查看相应组件的首次失败，再按 Gateway 回复与界面排障继续，不用全局改权限或重装替代定位。

生产恢复：不重复已完成动作，并限定等待预算

修复后先做一次同 agent、同会话、同模型路径的短验证，要求完整回复且没有新的认证或限流错误。它可能消耗模型额度；不要让验证消息包含发送、购买或部署等外部动作。若原任务需要工具能力，再确认一个无害的必要工具能返回结果，最后从已核对的未完成步骤恢复。

专门的 models status --probe 会执行真实请求，可能触发额度和限流，还要求规范状态目录的独占使用。需要它时按官方探测流程安排维护窗口，停止 Gateway，等待探测及清理完整结束后再恢复；命令超时或提前显示结果不证明状态已经释放。普通握手或模型目录查询不能替代原先失败路径的验证。

恢复前把任务状态分成 已完成、未完成、结果未知。当前内置模型运行时已有有界重试，不要在它外面叠加“失败就从头跑完整任务”的循环。备用方案还必须满足模型能力、数据去向、账单及选择条件：会话显式选定模型通常是严格选择，默认策略才可能采用已配置链；临时备用成功也不会永久改写所选模型。当前回退规则是这里的判断依据。需要接入备用时，按 OpenClaw 模型配置与验证处理。

下面是一个 纯离线恢复决策示例，可以保存为 recovery_demo.py 后运行 python3 recovery_demo.py。它不读取配置或 key，不发送请求、不等待，也不实现 OpenClaw 重试控制器。输入中的 kind、issuer 和 replay_safe 必须来自已经确认的错误来源与动作状态，不能只按 HTTP 码自动填。例子的作用是检查你设计的外围任务流程是否会提前重试、突破预算或重放未知动作。

from datetime import datetime, timezone
from email.utils import parsedate_to_datetime
import math


def wait_seconds(value, now):
    if value is None:
        return None
    text = str(value).strip()
    if text.isdigit():
        return int(text)
    try:
        target = parsedate_to_datetime(text)
        if target.tzinfo is None:
            return None
        return max(0, math.ceil((target - now).total_seconds()))
    except (ValueError, TypeError, OverflowError):
        return None


def decide(event, *, now, remaining_s, attempt, max_attempts=3):
    # attempt 是已经完成的总尝试次数，示例预算由调用者明确提供。
    if event.get("cancelled") or remaining_s <= 0:
        return ("stop", 0)
    if event["kind"] == "complete":
        return ("done", 0)
    if not event.get("replay_safe", False):
        return ("inspect_unknown_or_completed_actions", 0)
    if event["issuer"] == "gateway_auth":
        wait = wait_seconds(event.get("retry_after"), now)
        return ("repair_client_then_wait", wait)
    if event["kind"] in {"auth", "billing", "payload", "context", "refusal"}:
        return ("repair_corresponding_cause", 0)
    if event["kind"] == "usage_exhausted":
        return ("defer_until_access_recovers", 0)
    if attempt >= max_attempts:
        return ("stop_attempt_budget", 0)
    transient = (
        event["kind"] == "temporary_rate" and event["status"] == 429
    ) or (
        event["kind"] == "transient" and event["status"] in {502, 503, 504, 529}
    )
    if not transient:
        return ("inspect_unclassified_error", 0)
    floor = wait_seconds(event.get("retry_after"), now)
    if event.get("retry_after") is not None and floor is None:
        return ("inspect_invalid_wait_hint", 0)
    delay = max(2 ** max(0, attempt - 1), floor or 0)
    if delay >= remaining_s:
        return ("defer_without_sending_early", delay)
    return ("eligible_for_bounded_retry", delay)


if __name__ == "__main__":
    now = datetime(2026, 10, 7, 0, 0, tzinfo=timezone.utc)
    base = dict(issuer="provider", kind="temporary_rate", status=429,
                replay_safe=True, retry_after="120")
    assert decide(base, now=now, remaining_s=30, attempt=1)[0] == "defer_without_sending_early"
    assert decide({**base, "retry_after": "2"}, now=now,
                  remaining_s=30, attempt=3)[0] == "stop_attempt_budget"
    assert decide({**base, "replay_safe": False}, now=now,
                  remaining_s=30, attempt=1)[0] == "inspect_unknown_or_completed_actions"
    assert decide({**base, "issuer": "gateway_auth"}, now=now,
                  remaining_s=30, attempt=1)[0] == "repair_client_then_wait"
    assert wait_seconds("Wed, 07 Oct 2026 00:00:02 GMT", now) == 2
    assert decide({**base, "kind": "billing", "status": 401}, now=now,
                  remaining_s=30, attempt=1)[0] == "repair_corresponding_cause"
    print("离线决策示例通过；未执行模型或工具请求。")

例子将服务端等待当作最短间隔，超过本次任务预算就延期，不截短后抢先发送。标准 Retry-After 可以是非负整数秒数或 HTTP 日期，日期不足一秒的部分向上取整；HTTP 规范规定了两种形式。OpenClaw 还支持其文档说明的毫秒或正文等待提示，实际接入应由当前运行时处理，不能把此处的窄示例当作完整协议解析器。

这些断言只验证虚构决策，不证明真实后端接受凭证、某次 POST 可安全重放或任务已恢复。生产接入时应沿用当前运行时的取消、截止时间和结果记录，把延期交给任务队列或人工确认；只有原任务允许、候选已获准且动作可安全继续时，才考虑备用模型。

常见问题

API key 已保存，为什么还是 No API Key？

保存位置可能不属于实际 Gateway 用户，失败 agent 可能选中旧本地覆盖或不同 profile，会话也可能固定了另一 provider。先对照实际进程、models status --agent 和会话状态；显式凭证引用失败还要修来源，不能把“文件里有 key”当作运行时可用。认证存储说明解释了共享与本地覆盖。

Gateway status 正常，为什么模型仍然 401？

Gateway 的服务与认证握手成功只证明相应连接状态，不能证明模型服务商接受了当前 agent 的请求。继续看实际会话模型、上游错误与认证来源。Gateway 查询语义和模型状态说明分别限定了这两种检查。

401 和 429 都应该换 key 吗？

不应统一换。401 要按签发方、认证方式、实际地址与错误正文修正；429 要先分清入口认证限流、临时速率限制和用量耗尽。有效 key 共用受限账号时，新增同账号 key 也不增加共享额度。模型失败与认证选择规则说明了为什么状态码不能代替原因判断。

改完 Compose 的环境变量，restart 就够了吗？

不够。现有容器不会因单纯 restart 读取新增环境，需要按当前 Compose 配置重新创建 Gateway，再核对实际加载来源。先保护持久状态与未完成任务，按官方 Docker 环境说明操作，不重建存储来修变量。

修好后要把原任务重新发一遍吗？

先核对已完成动作和结果未知的操作，再继续未完成部分。超时不证明请求没执行，已完成文件或外部动作不能盲目重放。短模型验证成功后，也要确认原任务需要的工具与上下文满足恢复条件；当前回退规则要求推进候选前保证可安全继续。