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

> OpenClaw API Key 错误先看最早失败的请求：缺少服务商凭证才补认证，Gateway 令牌或设备权限失败就修客户端连接，429 则区分入口认证限流与模型配额。对照实际 Gateway 进程、agent 和会话模型修复，再从已完成工作继续验证。

- URL: https://blog.laozhang.ai/zh/posts/openclaw-api-key-error
- Published: 2026-02-09
- Updated: 2026-10-08
- Author: LaoZhang AI Team (https://blog.laozhang.ai/zh/about)
- Topic: 故障排查
- Tags: OpenClaw, API Key 错误, 401, 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 状态码，都可能缺少真正原因。

| 最早的错误或现象 | 先检查什么 | 修复与成功判断 |
|---|---|---|
| `No API key found for provider`、`No credentials found` | 失败 agent 的 provider、认证来源、共享记录与本地覆盖 | 缺少认证才补对应 provider；状态不再缺失后，还需同会话短请求成功 |
| 上游 `401`、`invalid bearer token`、`incorrect api key` | 实际服务商、请求地址、认证方式及错误正文 | 修失效凭证或错配地址；用原先失败的 agent、模型与会话验证 |
| `AUTH_TOKEN_MISSING`、`AUTH_TOKEN_MISMATCH`、WS `1008` | Gateway 连接的详细错误码与客户端身份 | 修 Gateway 凭证、设备或权限；握手成功后再检查模型请求 |
| `429`、`all in cooldown` | 谁返回错误、等待提示、各次尝试原因和配额状态 | 入口认证限流修客户端；模型临时限流按提示等待，周期耗尽按真实恢复条件处理 |
| `400`、`Invalid beta flag`、`context_length_exceeded` | 当前接口支持的字段与实际请求上下文 | 修请求或恢复上下文；不要用更换 key 代替请求修正 |
| `502`、超时、TLS 错误 | 连接目标、最早传输错误、是否已有工具结果 | 分清上游故障、本地接口契约与证书链；结果未知时先核对动作，避免整任务重放 |
| 只在 Docker、服务启动或升级后失败 | 实际进程的环境来源、配置文件、状态目录和迁移诊断 | 修那个进程读取的来源；确认新进程实际加载，再做同路径验证 |

这张表按错误来源分流，不代表每个状态码只有一种原因。例如 Gateway 的 HTTP `429` 可以是失败认证尝试过多，上游 `401` 也可能带有计费相关说明。[Gateway HTTP 错误说明](https://docs.openclaw.ai/gateway/openresponses-http-api)和[模型失败分类](https://docs.openclaw.ai/concepts/model-failover)都要求结合错误正文判断。

![按模型认证、Gateway 身份、限流来源与请求运行环境分流 OpenClaw 错误的示意](https://blog.laozhang.ai/posts/zh/openclaw-api-key-error/img/error-diagnosis.webp)

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

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

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

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

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

```text
/model status
/status
```

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

**“配置状态正常”还没有证明模型请求成功。** 不带 `--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。状态中的“不确定”也不是验证成功。

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

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

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

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

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

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

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

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

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

接下来按已选方式处理：

| 当前方式 | 对应恢复动作 |
|---|---|
| 服务商 API key | 确认 key 是否撤销、来源是否选错，以及账号或模型访问是否受限；失效才保存新的有效 key |
| 原生 Claude CLI | 核对同一 Gateway 主机、用户、`PATH` 与 `CLAUDE_CONFIG_DIR` 下的原生登录；恢复该运行时的登录与可用性 |
| OpenClaw 管理的 OAuth 或 setup-token | 对照失效 provider/profile，使用该 provider 当前支持的交互认证方法恢复 |
| 显式 `SecretRef` | 先修指定文件、执行程序或其他来源的解析/激活故障，再验证发送路径 |

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

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

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

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

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

| 连接详情 | 应采取的动作 |
|---|---|
| `AUTH_TOKEN_MISSING` | 为已获授权的客户端配置这个 Gateway 所需的连接凭证 |
| `AUTH_TOKEN_MISMATCH` | 对照当前 Gateway 与客户端使用的凭证；若响应明确允许设备令牌重试，由受信客户端按协议尝试一次 |
| `AUTH_DEVICE_TOKEN_MISMATCH` | 由设备所有者处理设备凭证恢复，不能靠更换模型 key 修复 |
| `AUTH_SCOPE_MISMATCH` | 核对已批准的角色与权限；令牌有效也可能没有当前操作权限 |
| `PAIRING_REQUIRED` | 查看配对原因和待审批请求，由授权管理者审核相应设备 |

按[Control UI 排障文档](https://docs.openclaw.ai/gateway/troubleshooting/agent-replies-and-control-ui)处理对应身份；不要为排障关闭认证或扩大端口暴露。共享令牌也不自动替代设备身份，具有共享凭证的 HTTP 调用可能拥有完整 operator 权限，因此不能把它当作天然只读的测试。

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

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

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

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

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

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

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

需要进一步区分模型配额、ClawHub 下载限流、持久冷却与具体等待条件，可继续看 [OpenClaw 429、冷却与回退恢复](https://blog.laozhang.ai/zh/posts/openclaw-rate-limit-exceeded-429)。ClawHub 安装失败不能靠模型 API key 解除。

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

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

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

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

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

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

```bash
openclaw config file
openclaw config validate
openclaw doctor
```

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

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

| 你改的位置 | 还要核对的运行条件 |
|---|---|
| 个人终端的环境变量 | Gateway 服务用户或容器是否读取该来源，运行进程是否仍保留原值 |
| 工作区 `.env` | 当前规则不把它作为 provider 凭证或受保护控制项的通用来源 |
| 全局状态目录 `.env` 或服务环境 | 变量属于 OpenClaw 管理还是运维自行提供，实际加载规则是否匹配 |
| Docker Compose 环境配置 | 现有容器是否已按新环境重新创建，单纯 restart 不加载新增环境 |
| 配置中的 `SecretRef` | 引用是否激活、指定来源是否可用、是否被更优先的认证记录遮盖 |

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

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

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

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

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

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

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

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

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

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

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

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

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

![核对已完成与未知动作，修复对应原因并有限验证后继续未完成任务的示意](https://blog.laozhang.ai/posts/zh/openclaw-api-key-error/img/production-recovery.webp)

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

```python
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 规范](https://www.rfc-editor.org/rfc/rfc9110.html#section-10.2.3)规定了两种形式。OpenClaw 还支持其文档说明的毫秒或正文等待提示，实际接入应由当前运行时处理，不能把此处的窄示例当作完整协议解析器。

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

## 常见问题

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

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

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

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

### 401 和 429 都应该换 key 吗？

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

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

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

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

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

## 参考来源

本文引用的外部页面，按正文出现顺序排列。最后更新于 2026-10-08。

- [Gateway HTTP 错误说明](https://docs.openclaw.ai/gateway/openresponses-http-api) (docs.openclaw.ai)
- [模型失败分类](https://docs.openclaw.ai/concepts/model-failover) (docs.openclaw.ai)
- [模型 CLI 文档](https://docs.openclaw.ai/cli/models) (docs.openclaw.ai)
- [凭证存储说明](https://docs.openclaw.ai/concepts/oauth) (docs.openclaw.ai)
- [官方认证说明](https://docs.openclaw.ai/gateway/authentication) (docs.openclaw.ai)
- [Control UI 排障文档](https://docs.openclaw.ai/gateway/troubleshooting/agent-replies-and-control-ui) (docs.openclaw.ai)
- [模型重试文档](https://docs.openclaw.ai/concepts/retry) (docs.openclaw.ai)
- [配置 CLI 文档](https://docs.openclaw.ai/cli/config) (docs.openclaw.ai)
- [环境说明](https://docs.openclaw.ai/help/environment) (docs.openclaw.ai)
- [官方环境文档](https://docs.openclaw.ai/install/docker/environment-variables) (docs.openclaw.ai)
- [凭证激活说明](https://docs.openclaw.ai/gateway/secrets/operations) (docs.openclaw.ai)
- [HTTP 幂等语义](https://www.rfc-editor.org/rfc/rfc9110.html) (rfc-editor.org)
- [Node 官方说明](https://nodejs.org/api/cli.html) (nodejs.org)
- [Gateway 查询语义](https://docs.openclaw.ai/cli/gateway/query) (docs.openclaw.ai)