跳转至

openclaw models

模型发现、扫描和配置(默认模型、回退、认证配置文件)。

相关:

常用命令

openclaw models --json
openclaw models status
openclaw models list
openclaw models refresh
openclaw models set <model-or-alias>
openclaw models set-image <model-or-alias>
openclaw models scan

status、list 和 auth 子命令接受 --agent <id> 以指定已配置的代理。未指定时,模型检查在已配置的情况下使用 agents.defaults.systemAgent.agentId,否则使用唯一已配置的代理。当配置了多个代理时,认证变更要求提供 --agent <id>。

对于 models status,当省略 --agent 时,OPENCLAW_AGENT_DIR 会覆盖被检查的认证目录。匹配的已配置 agentDir 会在凭据刷新期间保留该代理的所有权。显式的 --agent <id> 优先于环境变量覆盖。

set、set-image、scan、refresh、aliases 以及 fallbacks/image-fallbacks 的 add、remove 和 clear 操作全局默认值,并拒绝 --agent。

models set 和 models set-image 要求提供商由已安装的插件声明,或配置在 models.providers 下。未知提供商会以非零状态退出,且不更改配置。如果提供商已知,但模型不在本地目录中,命令会保存该选择并打印警告,因为新发布和自托管模型可能尚未编入目录。使用 openclaw config set 写入 agents.defaults.model 比 models set 更严格:它会拒绝无法解析的模型引用,而不是发出警告。该检查仅针对文本模型;config set 完全不验证 agents.defaults.imageModel,因此对于 set-image 设置而言,它并不是更严格的路径。openclaw doctor --json 会报告已配置的未知提供商;添加 --severity-min info 还可以查看本地目录无法确认的活动模型。

默认模型、别名和回退更改会使用当前插件配置解析提供商拥有的模型别名。当已存储的条目解析到所选模型时,其设置会移动到该模型的规范键;现有规范设置优先。添加别名会替换该模型之前的别名。如果配置在该准备期间发生变化,命令会拒绝写入;请针对更新后的配置重新运行。

与已配置提供商模型匹配的显式 provider/model 会保留其字面身份,即使另一个模型存在冲突的别名。裸别名和不冲突的 provider/alias 选择仍会正常解析。

状态

单独的 openclaw models 等同于 openclaw models status。 openclaw models --json 返回与 openclaw models status --json 相同的对象。

openclaw models status 显示解析后的默认/回退以及认证概览。活动配置文件的冷却期会显示在 不可用认证配置文件 下,并附带存储的原因和恢复操作;JSON 输出在 auth.unusableProfiles 中公开相同数据。对于由插件拥有的代理运行时(例如 Codex),状态还会检查拥有该运行时的插件是否已启用并通过启动负载验证。具有有效凭据但运行时不可用的路由会报告 status: unavailable,而不是 usable;JSON 输出包含单独的 authStatus、runtimeStatus 和有界运行时诊断。当提供商使用量快照可用时,OAuth/API 密钥状态部分会包含提供商使用窗口和配额快照。当前使用窗口提供商:Anthropic、GitHub Copilot、OpenAI、MiniMax、通过 xAI OAuth 的 SuperGrok、Xiaomi 和 z.ai。使用量认证在可用时来自提供商特定钩子;否则 OpenClaw 会回退到从认证配置文件、环境变量或配置中匹配的 OAuth/API 密钥凭据。

诊断某个代理的选择时,请使用显式代理:

openclaw models list --agent <agentId>
openclaw models status --agent <agentId>
openclaw models status --agent <agentId> --json --check

列表显示模型清单。状态说明其路由的已配置默认值、回退和认证。它不会检查聊天会话的模型覆盖;请在该会话中使用 /model status。

对于具有 runtime.type: "acp" 的代理,状态和认证检查会检查原生默认值和原生回退策略。代理的 model.primary 会选择其 ACP 框架,并且不是原生检查的模型候选项。使用 ACP 会话控制来检查或更改外部框架模型。

正确读取状态

这些部分回答不同的问题:

输出 含义
认证概览 / auth.providers 在环境变量、提供商配置或认证存储中找到的凭据来源。
OAuth/令牌状态 / auth.oauth 已存储配置文件的健康状况和过期时间。JSON 对象还包括 API 密钥配置文件。
模型路由问题 / auth.modelRouteIssues 不兼容的路由、缺少路由凭据,或无法确认的就绪状态。
运行时认证 / auth.runtimeAuthRoutes 使用独立代理运行的路由的认证和运行时可用性。

已存储的配置文件或 static 健康条目并不能证明其凭据现在可用。例如,已存储的 file 或 exec SecretRef(对密钥的引用)可能出现在概览中,而其路由仍保持 indeterminate。这意味着在此命令路径中无法确认就绪状态;这并不意味着提供商拒绝了该凭据。在替换凭据之前,请检查路由诊断和已配置的密钥来源。

不带 --probe 的 Status 不是模型调用测试。它仍可以解析目标配置密钥并检查提供商拥有的认证状态。仅当你打算发出下文所述的实时请求时,才使用 --probe。

使用 --check 时,退出码为:

  • 0:未发现已配置路由的认证或运行时问题,且没有所选凭证即将过期。这并不能证明模型请求会成功。
  • 1:某个路由缺少或已过期认证、存在不兼容路由、运行时不可用,或就绪状态无法确定。
  • 2:某个所选凭证即将过期,且不存在需要退出码 1 的条件。

命令失败(例如无法解析必需的配置密钥)也会以非零退出。在 JSON 模式下,这些情况可能返回命令错误而不是状态对象;请同时检查进程退出码和输出。

非机密占位符可能以 marker(<value>) 形式出现,例如 secretref-managed 或环境变量名。这些标签描述凭证来源;它们不是已解析的机密。

选项:

标志 效果
--json JSON 输出;认证配置、提供商和启动诊断信息会写入 stderr,因此 stdout 仍可管道传入 jq。
--plain 纯文本输出。
--check 返回上文所述的认证/运行时检查退出码,其中就绪状态无法确定时返回 1。
--probe 对已配置的认证配置进行实时检查。会发出真实请求;可能消耗 Token 并触发速率限制。
--probe-provider <name> 仅检查一个提供商。
--probe-profile <id> 检查特定的认证配置 id(可重复或逗号分隔)。
--probe-timeout <ms> 每次检查的超时时间。
--probe-concurrency <n> 并发检查。
--probe-max-tokens <n> 每次检查的最大 Token 数(尽力而为)。
--agent <id> 已配置的 agent id;覆盖 OPENCLAW_AGENT_DIR。

--probe-timeout 需要一个正数;--probe-concurrency 和 --probe-max-tokens 需要正整数。省略这些选项会使用默认值(分别为 8000、2 和 8);显式空值会被拒绝。

检查行可能来自认证配置、环境变量凭证或 models.json。检查状态分类:ok、auth、rate_limit、billing、timeout、format、unknown、no_model。

直接运行 models status --probe 会在所选 agent 的规范数据库中创建临时内部会话,因此该命令需要独占拥有已配置的状态目录。检查前,请使用 openclaw gateway stop 停止正在运行的 Gateway。检查结果可能在缓慢的清理完成之前报告。临时认证目录、内部会话和状态锁会一直保留,直到已接受的工作和清理完成,包括中断之后。清理失败会被报告;超时并不能证明资源已关闭。

当检查从未到达模型调用时,预期会出现以下检查详情/原因代码:

  • excluded_by_auth_order:存在已存储的配置,但显式的 auth.order.<provider> 将其省略,因此检查会报告排除而不是尝试它。
  • missing_credential、invalid_expires、expired、unresolved_ref:配置存在但不符合条件或无法解析。
  • ineligible_profile:配置因其他原因与提供商配置不兼容。
  • no_model:提供商认证存在,但 OpenClaw 无法解析出可用于测试该提供商的模型候选项。

对于 OpenAI ChatGPT/Codex OAuth 故障排查,openclaw models status、openclaw models auth list --provider openai 和 openclaw config get agents.defaults.model --json 是确认某个 agent 是否通过原生 Codex 运行时拥有可用于 openai/* 的 openai OAuth 配置的最快方式。参见 OpenAI 提供商设置。

列表

openclaw models list 会返回已发布的模型清单,而不会等待提供商发现或重写 models.json。这也适用于 --all 和 --provider <id>。由 Gateway 支持的请求可以在后台更新过期的清单,如下文所述。

openclaw models list --agent <agentId>
openclaw models list --agent <agentId> --provider <providerId> --json
openclaw models list --agent <agentId> --refresh

当本地 Gateway 正在运行,或通过配置或环境选择了远程 Gateway 时,该命令会读取该 Gateway 的目录。--agent 选择该 Gateway 上的一个 agent。提供商过滤、模型可见性和可用性使用 Gateway 捕获的配置和认证事实。该命令不会为该请求解析本地模型提供商机密。

当某个提供商的已保存清单过期时,清单请求会返回已保存的行,同时 Gateway 在后台刷新该提供商。内部聊天和会话元数据读取不会安排发现。后续的清单请求会显示新发布的模型。刷新失败会保留已保存的行;使用 --refresh 重试。聊天模型菜单、Control UI 和 models list 会显示目录的刷新警告。CLI 会将警告写入 stderr,以保持 JSON 和纯文本 stdout 机器可读。

拒绝目录认证的提供商会生成一个单独的 CLI 诊断,其中包含其提供商以及(如果可用)profile ID。在 Control UI 中打开 Models 以检查登录和目录访问,然后使用 --refresh 重试。仅目录拒绝不会导致通用刷新警告,也不能证明模型请求会失败。超时和其他发现失败仍会产生刷新警告,即使另一个提供商需要登录。

发现诊断信息在所有输出模式下都会输出到 stderr。当 Gateway 或本地目录发布它们时,JSON 输出还会包含 providerOutcomes:每个条目包含 provider、可选的 profileId 和 status(ready、auth-rejected 或 unavailable)。这些是目录范围的结果,独立于 --provider 和 --local 等模型行过滤器。不包含提供商错误正文和凭据。纯 stdout 仍保持每行一个模型键。

所选 Gateway 必须声明 published-model-catalog。如果没有,请更新或重启它并重试。连接、授权和能力错误会直接报告;它们不会将命令切换到另一个本地列表。

在没有运行中的本地 Gateway 或显式 Gateway 目标时,命令会标识其正在显示本地缓存目录。此回退可以准备已配置和静态事实,并解析其已配置的认证,但仅在提供 --refresh 时才开始模型发现。

使用 --refresh 在列出之前获取提供商清单。刷新失败时,会在显示可用已发布行的同时发出警告。成功的空获取保持为空;它不会恢复旧的已发现行。如果发布所有者未就绪,请在 Gateway 启动或当前刷新完成后重试。

选项:--all(完整已发布目录)、--refresh(提供商发现)、--local(本地端点)、--provider <id>、--agent <id>、--json 和 --plain。提供商过滤器会读取该提供商的完整已发布清单,因此不需要 --all。

说明:

  • Auth 列使用已准备的凭据和运行时证据。单独的 API 密钥不能证明原生 CLI 登录。未知就绪状态保持未知,目录元数据不能证明模型请求会成功。参见 正确读取状态。
  • 提供商级别的 models.providers.<id>.baseUrl 如果位于插件声明的原生端点之外,会排除其隐式目录行,包括缓存的发现。将您的代理支持的模型添加到 models.providers.<id>.models;显式编写的行、名称、默认值和别名保持不变。仅模型级别的 URL 覆盖不会排除提供商目录。
  • 静态目录行可以在未认证时保持可见。列出它们不会授予选择受限模型或更改 modelPolicy.allow 的权限。
  • 在合并模式下,刷新生成的目录会保留手动根模型,包括其提供商也具有生成目录的模型。显式替换模式保持其现有替换行为。
  • 对于仅在需要时加载的插件(activation.onStartup: false),缓存目录中的合格提供商需要在目录贡献隐式行之前具有当前 profile、环境或提供商配置认证。仅保留在生成目录内部的凭据不符合条件。显式模型声明保持可见。
  • Ctx 在运行时上限与原生上下文窗口不同时显示 contextTokens/contextWindow。JSON 在提供时保留 contextTokens。
  • Input 和 Ctx 使用所选物理路由加上显式配置的逻辑覆盖。未解析的路由元数据保持未知,而不是借用另一条路由的能力。
  • 已配置的模型 ID 保留大小写。例如,Reader 和 reader 仍然不同。提供商拥有的别名仍然适用,已配置的别名保留在表格标签和 JSON 输出中。
  • --provider 接受提供商 ID,例如 moonshot,而不是选择器标签,例如 Moonshot AI。
  • 未知提供商 ID 会以非零退出码失败,并指明被拒绝的提供商。运行 openclaw models list --all 以列出模型及其提供商 ID。
  • 模型引用按第一个 / 拆分。当模型 ID 包含 / 时,包含提供商前缀,例如 openrouter/moonshotai/kimi-k2。

通过 models list --refresh 进行的提供商发现与下面描述的由 models refresh 执行的托管元数据下载是分开的。有关线路控制,参见 Gateway 目录请求。

刷新托管目录

openclaw models refresh [--json] 检查托管元数据目录。它不会登录提供商、测试凭据或在运行中的 Gateway 中激活已下载的行。由于托管目录是全局的,它会拒绝 --agent。

该命令要求本地 Gateway 已停止。通过其服务所有者停止它,运行刷新,然后再次启动它。它通过下载和写入结算获得独占离线所有权,并在 Gateway 拥有状态目录时拒绝。成功结果描述已保存的下载;下次 Gateway 启动时加载兼容元数据。运行中的 Gateway 继续执行其自身的计划目录刷新。 如果 models.catalogRefresh.enabled 为 false,该命令会报告刷新已禁用。

参见 托管目录更新 了解更新生命周期。公开变更历史位于 openclaw/catalog。

设置默认 / 图像模型

openclaw models set <model-or-alias>
openclaw models set-image <model-or-alias>

set 写入 agents.defaults.model.primary;set-image 写入 agents.defaults.imageModel.primary。两者都接受 provider/model 或已配置的别名。当新选择的模型需要时,set 还会修复 Codex/Copilot 运行时插件安装;set-image 不会。两个命令都不接受 --agent;它们始终写入 agent 默认值。

选择模型时如果省略提供商,OpenClaw 会先尝试已配置的别名,然后尝试针对该确切模型 ID 的唯一已配置提供商匹配,最后尝试已配置的默认提供商,并给出弃用警告。如果该提供商不再暴露已配置的默认值,则使用第一个已配置的提供商/模型。

扫描

models scan 会读取 OpenRouter 的公开 :free 目录,并为回退用途对候选项进行排名。目录本身是公开的,因此仅元数据扫描不需要 OpenRouter 密钥。

默认情况下,OpenClaw 会尝试通过实时模型调用来检查工具支持和图像支持。如果未配置 OpenRouter 密钥,命令会回退到仅元数据输出,并说明 :free 模型仍需要 OPENROUTER_API_KEY 才能进行检查和推理。

选项:

  • --no-probe(仅元数据;不查找配置/密钥)
  • --min-params <b>
  • --max-age-days <days>
  • --provider <name>
  • --max-candidates <n>
  • --timeout <ms>(目录请求和每项检查的超时时间)
  • --concurrency <n>
  • --yes
  • --no-input
  • --set-default
  • --set-image
  • --json

数值型扫描选项会拒绝空值和仅包含空白字符的值。省略某个标志可保留其默认行为。

探测扫描会写入配置,即使未使用 --set-default。它会用所选模型替换 agents.defaults.model.fallbacks,当选择了支持图像的模型时会替换 agents.defaults.imageModel.fallbacks,并将所选模型添加到 agents.defaults.models。--set-default 和 --set-image 还会设置相应的主模型。--json 仍会写入。使用 --no-probe 可在不更改配置的情况下检查候选项。

--set-default 和 --set-image 需要实时检查;仅元数据扫描结果仅供参考,不会应用到配置。

别名

openclaw models aliases list [--json] [--plain]
openclaw models aliases add <alias> <model-or-alias>
openclaw models aliases remove <alias>

别名按模型条目存储为 agents.defaults.models.<key>.alias。add 会先将 <model-or-alias> 解析为规范的提供商/模型键,因此为别名设置别名会重新指向它,而不是形成链式引用。 添加别名不会更改 agents.defaults.modelPolicy.allow 或限制模型覆盖。

回退

openclaw models fallbacks list [--json] [--plain]
openclaw models fallbacks add <model-or-alias>
openclaw models fallbacks remove <model-or-alias>
openclaw models fallbacks clear

管理 agents.defaults.model.fallbacks。openclaw models image-fallbacks list|add|remove|clear 管理并行的 agents.defaults.imageModel.fallbacks 列表,子命令形式相同。

个人模型账户

使用 models accounts 管理所选 Gateway 上由你已登录人员拥有的账户。CLI 和 设置 → 个人资料 → 已连接账户 使用相同的 Gateway 账户存储,包括服务器共享时。

范围 命令 凭据所属位置
个人 models accounts login [provider] 所选 Gateway 上经过验证的个人资料,该 Gateway 可能是远程的。
系统 / 代理 models auth login --provider <id> [--agent <id>] 运行命令的机器上的 OpenClaw 安装。

要为远程服务器配置系统/代理凭据,请在该服务器上运行 models auth,并使用其 OpenClaw 状态/配置。在笔记本电脑上配置远程 Gateway URL 并不会使 models auth 写入服务器。

openclaw models accounts list
openclaw models accounts login
openclaw models accounts login anthropic --method api-key
openclaw models accounts login openai --method device-code
openclaw models accounts login xai --method api-key
openclaw models accounts use <account-id>
openclaw models accounts clear-default <provider>

每个账户命令在访问账户或请求提供商凭据之前,都会显示 Gateway、人员 和 范围:个人。此上下文会输出到 stderr,因此 --json 输出仍可管道处理。该人员是 Gateway 保存的、经过验证的个人资料,而不是你的操作系统用户名或未保存的显示名称编辑。

Gateway 访问和提供商登录是分开的。账户所有权遵循 Gateway 在此连接上分配的个人资料。单用户 Control UI 连接可以使用持久的 Owner 个人资料,但短生命周期的 CLI 连接不会自动分配该个人资料。因此,个人账户 CLI 需要一个携带身份信息的端点,即使本地 Control UI 已显示 Owner。

对于共享服务器上的不同人员,请使用其携带身份信息的 WebSocket 端点,例如 Tailscale Serve 或 受信任代理。如果请求,请单独批准设备配对:配对授予设备访问权限,而不是某个不同人员的身份。提供共享 Gateway 令牌/密码凭据优先于 Tailscale 身份验证。浏览器登录不会将其身份转移到 CLI。对于身份感知边缘,请遵循 远程边缘身份验证。

如果未识别出人员,命令会在提供商登录之前停止,并说明如何使用携带身份信息的端点。它不会推断所有权或更改 Gateway 身份验证。这些命令不接受 --agent 或所有者 ID,也不会修改本地共享身份验证存储或模型配置。顶层 openclaw connect 命令用于注册节点;它不是个人账户登录。

list 需要 operator.read,并返回一页最多 50 个已保存账户:id、提供商、友好标签、身份验证类型,以及每个账户是否为新会话默认值。它从不返回凭据。使用 --json 获取结构化输出,使用 list --cursor <nextCursor> 获取下一页。

login、use 和 clear-default 需要 operator.write。login 需要交互式终端,并提供与 Control UI 中 添加账户 相同的提供商和登录方式。省略提供商参数可从 Gateway 目录中选择;使用 --method <id> 直接选择一种方式。目录仅包含其提供商插件为个人账户启用的方法,而不是所有系统/代理设置方法。

Anthropic 的个人设置使用 API 密钥,而不是 Claude 订阅令牌。OpenAI 提供 API 密钥、浏览器登录和设备代码方式;Grok(xai)提供 API 密钥和设备登录。请按照所选 Gateway 显示的步骤操作。凭据和授权代码应输入到受保护的输入框中,切勿作为命令参数或聊天内容。在浏览器登录期间,即使重定向提示处于打开状态,CLI 也会持续检查是否完成。

保持命令运行,直到它报告最终结果。Ctrl-C 会取消该次登录尝试,并等待 Gateway 确认;如果连接已关闭,必须开始一次新的尝试。保存账户本身并不能证明模型请求一定会成功。

use 为新的会话选择已保存的账户,无需再次登录。clear-default 仅移除该提供商的个人默认设置:它会保留已保存的凭据和现有会话选择。这两种操作都不会撤销提供商访问权限。有关协作者、fork 和故障转移行为,请参阅 个人模型账户。

所有账户子命令都接受 --url <url>、--port <port>、--token-file <path>、--password-file <path>、--timeout <ms>(默认 30000)和 --json。令牌/密码文件用于对 Gateway 进行身份验证,而不是对提供商进行身份验证,并且不会为此 CLI 建立个人身份。显式 --url 可以使用携带身份的端点,而无需提供共享令牌。它不会将环境中的或已配置的共享凭据发送到覆盖端点;已配置的边缘凭据仍绑定到其自身端点。标志可以位于叶子命令之前或之后:

openclaw models accounts --timeout 45000 list --json
openclaw models accounts list --timeout 45000 --json

身份验证配置

这些命令管理 系统 / 代理 凭据,而不是个人 Gateway 账户。在提供商登录之前,models auth login 会显示所选代理,并说明它正在运行 OpenClaw 的机器上操作。

models auth 命令要求对所选本地状态拥有独占的离线所有权。通过其服务所有者停止 Gateway,等待其释放所有权,然后运行该命令。当 Gateway 拥有该状态时,OpenClaw 会在加载身份验证状态或启动提供商登录之前拒绝操作;它绝不会绕过活动所有者进行写入。这也适用于 list 和 order get,因为它们的配置和身份验证存储加载器可以初始化持久状态。所有权会一直保留,直到命令的数据库工作和清理完成。命令完成后,再次启动 Gateway。

要在 Gateway 保持运行期间管理凭据,请使用其 Models 页面。仅限 CLI 的设置选项、本地提供商 CLI 导入和部分配置文件顺序覆盖仍属于离线操作。个人 models accounts 命令将继续使用所选 Gateway。

openclaw models auth add
openclaw models auth list [--provider <id>] [--json]
openclaw models auth login --provider <id> [--agent <agentId>]
openclaw models auth login --provider openai --profile-id openai:work
openclaw models auth login-github-copilot
openclaw models auth activate <profileId> [--agent <id>]
openclaw models auth logout <profileId> [--yes]
openclaw models auth paste-api-key --provider <id>
openclaw models auth setup-token --provider <id>
openclaw models auth paste-token --provider <id>
openclaw models auth order get --provider <id>
openclaw models auth order set --provider <id> <profileIds...>
openclaw models auth order clear --provider <id>

models auth add 是交互式身份验证助手。根据你选择的提供商,它可以启动提供商身份验证流程(OAuth/API 密钥),或引导你手动粘贴令牌。

models auth list 会列出所选代理已保存的身份验证配置,而不会打印令牌、API 密钥或 OAuth 机密材料。活动冷却和禁用条目会包含其原因和恢复操作。旧版 Gemini CLI OAuth 冷却会引导你使用受支持的 Google AI Studio API 密钥设置,而不是提供不可用的 Gemini CLI 登录流程。使用 --provider <id> 可筛选到某个提供商,例如 openai,并使用 --json 用于脚本。

models auth login 会运行提供商插件的身份验证流程(OAuth/API 密钥)。使用 openclaw plugins list 查看已安装哪些提供商。login 接受 --profile-id <id>,用于在登录期间支持命名配置文件的提供商(使用此选项可将同一提供商的多个登录保持分离),--method <id> 用于选择特定身份验证方法,--device-code 作为 --method device-code 的快捷方式,--set-default 用于应用提供商推荐的默认模型,以及 --force 用于先移除该提供商的现有配置文件(当缓存的 OAuth 配置文件卡住或你想切换账户时使用)。

保存凭据后,现有的模型限制可能会提示 显示所有 <Provider> 模型 或 保留当前限制。只有第一个选项会将该提供商的通配符添加到当前限制中。无论哪种情况,凭据都会保持保存。CLI、私有聊天登录和 Control UI 使用相同的选择。当提供商已不受限制时,不会出现提示。如果登录期间限制发生变化,OpenClaw 会保留较新的设置,并要求你再次选择模型访问权限。

CLI 会将已保存的模型访问权限与已确认的 Gateway 应用分开报告。 离线更改会在 Gateway 下次启动时生效。

如果没有 --set-default,登录会保留当前默认设置,包括未设置的默认值,并保留登录运行期间所做的无关配置编辑。如果凭据已保存但无法应用提供商设置,错误会单独报告已保存的凭据。Gateway 刷新警告不会撤销已保存的更改;在离线操作完成后启动 Gateway。

对于 shared-main 代理,--force 会清除提供方的共享凭据和主代理本地覆盖,包括它们的顺序和健康状态。对于其他代理,它仅清除该代理的本地配置,共享凭据保持不变。繁忙的认证存储会在登录开始前停止命令;请关闭其他使用相同状态目录的 OpenClaw 命令,然后重试。SQLite 锁诊断可能指向共享状态数据库或某个代理数据库,因此仅检查旧版认证文件中的打开句柄并不能排除争用。

models auth activate <profileId> 测试已保存的登录,并为所选代理选择其已验证的模型和账户。使用无人值守替换设置后打印的准确命令,或使用 models auth list --json 查找已保存的 id。该命令无需再次提示即可确认激活;测试失败时,当前连接保持不变。

models auth logout <profileId> 从所选代理的认证存储中移除一个已保存的认证配置。使用 models auth list 显示的配置 ID。它还会从 auth.profiles 以及配置中的每个 auth.order 列表中移除该配置,因此不会留下过期引用,并删除一个否则会被清空的 auth.order.<provider> 条目(手工编写的空顺序表示“不选择任何配置”,并会禁用该提供方)。在 TTY 上会提示确认;脚本和代理请传入 --yes。提供方密钥引用会在凭据删除前清除。模型默认值和连接设置保持不变。如果配置不在存储中,登出会拒绝执行。

登出还会从生成的插件模型目录缓存中移除所选凭据的副本,包括保留的迁移副本,同时保留模型清单和其他账户。无法使用的生成缓存行会被丢弃,而不是保留未知秘密。清理会一起检查候选存储,并只写入需要移除凭据或丢弃不可用行的目录。已在进行的目录刷新会在发布前重新检查已保存的凭据。Doctor 的目录凭据恢复保持不变。此清理适用于所选配置仍被保存时;它无法识别已由旧版本移除的配置所缓存的凭据。

如果最终目录清理失败,登出会恢复已保存的凭据及其配置引用,以便你可以使用相同的配置 ID 重新运行同一命令。错误会报告恢复是否完成;并发的认证更改可能阻止完全恢复,需要检查当前配置后再重试。

models auth login-github-copilot 是 models auth login --provider github-copilot --method device(GitHub 设备流)的快捷方式;它接受 --yes 以覆盖现有配置而不提示。

使用 openclaw models auth --agent <id> <subcommand> 或 openclaw models auth <subcommand> --agent <id> 来针对特定已配置代理存储。add、list、login、activate、logout、paste-api-key、setup-token、paste-token、login-github-copilot 以及 order get/set/clear 均支持这两种形式。

对于 OpenAI 模型,--provider openai 默认使用 ChatGPT/Codex 账户登录。仅当你要添加 OpenAI API 密钥配置时,才使用 --method api-key,通常作为 Codex 订阅限制的备用。运行 openclaw doctor --fix 将旧版遗留 OpenAI Codex 前缀认证/配置状态迁移到 openai。

参见 OpenAI 身份验证,比较 Codex OAuth、设备代码、API 密钥以及使用 ChatGPT 登录(Beta)(--method siwc),包括模型访问、托管插件以及共享与个人设置。

示例:

openclaw models auth login --provider openai --set-default
openclaw models auth login --provider openai --method api-key
openclaw models auth paste-api-key --provider openai
openclaw models auth list --provider openai
openclaw models auth logout openai:manual --yes

说明:

  • paste-api-key 接受在其他地方生成的 API 密钥,提示输入密钥值,并使用与 Models 页面相同的凭据写入器。它会更新已配置的配置或当前活动的已保存密钥,或者在两者都不存在时创建 <provider>:manual。使用 --profile-id 可更新命名配置或添加备用,而不更改当前活动的提供方连接。已配置的提供方存储配置引用,而密钥材料保留在认证存储中。保存的更改会报告任何 Gateway 刷新失败及恢复步骤。在自动化中,通过 stdin 管道传入密钥,例如 printf "%s\n" "$OPENAI_API_KEY" | openclaw models auth paste-api-key --provider openai。
  • setup-token 和 paste-token 仍然是面向暴露令牌认证方法的提供方的通用令牌命令。
  • setup-token 需要交互式 TTY,并运行提供方的令牌认证方法(如果该提供方暴露了 setup-token 方法,则默认使用该方法)。
  • paste-token 需要 --provider,默认提示输入令牌值,除非传入 --profile-id,否则将其写入默认配置 ID <provider>:manual。在自动化中,请通过 stdin 管道传入令牌,而不是作为参数传递,以免提供方凭据出现在 shell 历史或进程列表中。
  • paste-token --expires-in <duration> 从相对时长(例如 365d 或 12h)存储绝对令牌过期时间。
  • 对于 openai,OpenAI API 密钥和 ChatGPT/OAuth 令牌材料是不同的认证形式。对 sk-... OpenAI API 密钥使用 paste-api-key,仅对令牌认证材料使用 paste-token。
  • Anthropic:setup-token/paste-token 是 anthropic 支持的 OpenClaw 认证路径,但当主机上可用时,OpenClaw 更倾向于复用 Claude CLI(claude -p)。
  • auth order get/set/clear 管理 SQLite 认证存储中针对单个提供方的按代理认证配置顺序覆盖,独立于 auth.order.<provider> 配置键。set 按优先级顺序接受一个或多个配置 ID。存储的顺序在配置选择和 CLI 运行时路由中优先于配置;clear 回退到配置/轮询顺序。

本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw