设置与认证字段

插件运行时加载之前，设置、引导和配置 UI 界面读取的清单字段。属于插件清单参考的一部分；顶层字段参考列出了所有字段。

原生会话发现¶

暴露 OpenClaw 外部创建的会话的插件，声明 setup.nativeSessionCatalog，其中包含 label、可选的 description，以及可选的 nodeCommands，后者包含其目录读取/列出/恢复命令名称。该契约使用插件现有的 config.sessionCatalog.enabled 偏好设置。核心会在已注册的目录读取、列出、活动检查以及已声明的节点命令执行之前检查此偏好设置。为 enabled 生成的模式默认值仍可在插件本地配置中使用，但根运行时配置仅保留一个显式编写的值，因此默认值不能冒充同意。

声明用于暴露原生目录的命令，而不是独立授权的执行传输。禁用发现必须保留已绑定会话中的轮次；这些轮次保留其现有的执行和节点权限。

当未编写偏好设置时，新声明默认关闭，包括在配置创建之后安装的插件。它们的模式也应将 enabled 默认为 false。新配置文件会为宿主生成的目录清单持久化 false，包括可安装的官方插件。显式值始终保留。这些仅用于选择退出的条目不会请求安装或扩大插件允许列表；显式插件选择或其他已编写配置仍会请求安装或扩大允许列表。它们也不会产生已禁用插件配置警告。现有选择退出项保持有效，无需 Doctor 重写；移除其中一个可以恢复旧版发现行为。

宿主生成的 legacyDefaultEnabled: true 声明仅为现有可读配置保留随附的 Claude/Codex 隐式开启行为。这是一个升级例外，而不是已安装的第三方清单可以授予的权限。未来的目录不会仅因加入生成的清单就继承该例外。现有未声明的目录保留其先前行为。

当所有已声明目录均关闭时，引导会提供一个未勾选的启用选项；选择某个代理并不意味着同意。显式选择也会为已安装的声明持久化该选择。检测本身不会写入任何偏好设置。

更改这些声明后，运行 pnpm native-catalogs:gen，并运行 pnpm native-catalogs:check 以验证官方目录元数据和打包的 macOS 资源。必需的 pnpm check 预检会运行此验证。如果其隐私默认资源缺失，创建新的原生配置将失败。

providerAuthChoices 参考¶

每个 providerAuthChoices 条目描述一个引导或身份验证选项。OpenClaw 会在 provider 运行时加载之前读取此内容。Provider 设置列表使用这些清单选项、由描述符派生的设置选项以及安装目录元数据，而无需加载 provider 运行时。

当选择某个清单选项时，设置会在所属的已安装插件中解析其 provider 和 method。运行时身份验证方法无需在其向导元数据中重复 choiceId。不同的插件或身份验证方法无法满足该已声明选项。显式的 provider-plugin:<provider>:<method> 选项保留其编码目标。

platforms 使用 Node.js 平台名称；未知名称会被移除。该限制在提供设置、登录、CLI 标志和安装目录选项之前生效。它描述的是运行 OpenClaw 的主机，而不是已连接的应用或浏览器。它不会更改已保存的插件启用状态或提供商配置。当所选设置方法运行时，提供商仍会检查模型和操作系统可用性。

assistantVisibility: "detected-only" 会将该选择排除在仅元数据配置、登录、启用和安装行之外，包括手动选择器。应用引导配置仅将其作为提供商当前 appGuidedSetup.detect 探测返回的候选项提供。经典配置仅在 detectAvailability 成功后包含提供商选择。两个探测都必须应用提供商实际的模型资格规则。显式 CLI 身份验证选择仍受支持，并且配置方法仍会在激活前重新检查可用性。

对于所有配置方法都需要检测的提供商，已保存和已配置的模型也不会作为提供的候选项出现，直到当前发现确认匹配的模型。已配置的模型和配置完成状态仍会记录；不可用的模型不会将现有安装变为全新配置。具有普通受支持配置方法的提供商保留其现有行为。

可选的 modelTarget: "utility" 使用现有的按代理或默认 utilityModel 设置；省略时选择主角色。配置会验证 utility 角色，而不会替换可用的主模型或其运行时和凭据。如果未配置常规主模型，系统配置助手可以使用显式 utility 模型。自动 utility 默认值永远不会引导配置。一旦配置了常规主模型，它将优先；普通代理就绪状态与 utility 配置保持分离。 显式 provider-plugin:<provider>:<method> 选择保留为同一插件、提供商和方法声明的角色。运行时向导元数据无需重复清单中的角色。 裸提供商选择也保留由配置选择的方法的角色。精确的清单选择 ID 仍然拥有无前缀选择的分发。

客户端在激活 utility 选择时必须回显 modelTarget: "utility"。缺失或不匹配的角色确认会在提供商准备之前被拒绝，因此旧客户端不会意外地将 utility 激活视为主模型就绪。检测和成功的激活/验证会报告角色。检测保持 configuredModel 和 setupComplete 仅主模型，暴露显式 utilityModel，并且仅当该 utility 是无主模型配置回退时暴露 setupModel。验证显式接受 utility 目标，包括与主模型并存。

当 appGuidedDiscovery 为 true 时，匹配的提供商身份验证方法必须暴露 appGuidedSetup.detect 和 appGuidedSetup.prepare。检测必须是只读的：不进行登录、模型拉取、下载或配置写入。准备会重新检查确切选定的模型并返回配置提案。OpenClaw 保存任何返回的凭据，运行一次不带工具的确认轮次，并且仅在成功后激活提案。激活失败会保留已保存的凭据以便重试；替换项在用户接受激活之前保持未激活。提供商还可以暴露 appGuidedSetup.detectAvailability，当本地服务可达但没有模型符合自动配置条件时，将其配置选择标记为已检测。可用性探测也是只读的。

登录选项¶

模型中的 连接 需要 credentialOnly: true 加上 appGuidedAuth 或 appGuidedSecret。标记为 appGuidedDiscovery、manual-only 或位于文本推理入门之外的选择不会成为仅凭据操作。仅描述符的 setup.providers[].authMethods 条目不会创建可执行的登录选择。

裸 /login 将可见的浏览器和设备代码选择分组为提供商按钮，而不开始登录。具有多种方法的提供商会打开第二个选择。没有命令按钮的频道显示可复制的命令。核心从清单构建此菜单；频道不维护单独的提供商列表。

channelLogin 将仅凭据的浏览器或设备代码方法选择加入私有聊天。当不需要别名时使用 {}。该方法必须在不要求聊天提供密钥、端点或其他自由文本输入的情况下完成。需要此类输入的方法会移交给匹配的 Control UI 登录或配置流程。宿主在保存凭据后拥有任何模型访问同意；插件不能通过其配置补丁授予它。

基于浏览器的 channelLogin 方法在宿主提供时使用 ctx.oauth.authorize。传递提供商生成的 state、timeoutMs 截止时间以及 buildAuthorizationUrl(redirectUrl)。宿主拥有 HTTPS 回调，每个响应只消费一次，并返回 { code, state }。插件保留其 PKCE 验证器并交换代码。转发 ctx.signal，并在外部副作用前重新检查 ctx.assertCurrent。当此能力缺失时，保留本地和远程 CLI 完成。接收到的代码不是持久化凭据；宿主仅在保存后报告成功。

当 personalAccount 为 true 时，该方法通过共享向导协议运行，使用无凭据的环境/配置，没有代理目录或预置密钥，并使用明文输入模式。它必须为其提供商返回恰好一个内联凭据，并尊重取消。它不得导入原生 CLI 登录、解析 SecretRef、写入凭据/配置，或要求共享模型激活。Gateway 拥有私有的按人提交；configPatch、defaultModel 和返回的共享配置文件 ID 不会被应用。将凭据提示标记为敏感。仅当提供商允许此凭据使用时才使用此能力。

个人账户调用始终提供 ctx.assertCurrent。通过提供商辅助函数保留此闭包绑定检查，并在外部副作用前立即调用它，包括在任何交互式或异步等待之后的发现、轮询和令牌交换。使用 fetchWithSsrFGuard 时，将其作为 beforeRequest 传递，以便它在 DNS/代理准备之后以及重定向时运行。继续转发 ctx.signal 以取消进行中的工作；仅信号不会重新检查该人的当前权限。独立 CLI/入门调用可以省略该检查，因为它们不携带 Gateway 人员的权限。

可选的 matchesPersonalAccount(credential, existing) 认证方法钩子可以证明 OAuth 重新连接的是同一个提供商账户。应匹配完整身份，而不仅仅是电子邮件或共享工作区。如果没有该证明，系统会创建新的 OAuth 账户槽位，旧聊天固定项会保留其原始凭据。API 密钥和静态令牌仅在其字面值匹配时才会复用槽位。

设置参考¶

当设置和入门引导界面需要在运行时加载之前获取低成本的插件自有元数据时，使用 setup。

{
  "setup": {
    "providers": [
      {
        "id": "openai",
        "authMethods": ["api-key"],
        "envVars": ["OPENAI_API_KEY"],
        "authEvidence": [
          {
            "type": "local-file-with-env",
            "fileEnvVar": "OPENAI_CREDENTIALS_FILE",
            "requiresAllEnv": ["OPENAI_PROJECT"],
            "credentialMarker": "openai-local-credentials",
            "source": "openai local credentials"
          }
        ]
      }
    ],
    "cliBackends": ["openai-cli"],
    "configMigrations": ["legacy-openai-auth"],
    "requiresRuntime": false
  }
}

顶层 cliBackends 仍然有效，并继续描述 CLI 推理后端。setup.cliBackends 是设置专用的描述符表面，用于应保持仅元数据的控制平面/设置流程。

当存在时，setup.providers 和 setup.cliBackends 是设置发现的首选描述符优先查找表面。如果描述符仅缩小候选插件范围，而设置仍需要更丰富的设置时运行时钩子，请设置 requiresRuntime: true，并保留 setup-api 作为回退执行路径。

如果没有显式的 openclaw.setupEntry，OpenClaw 会在包根目录或包本地 dist/ 中解析约定俗成的 setup-api 文件。独立运行时构建会自动包含该公共表面。

OpenClaw 会将 setup.providers[].envVars 包含在通用提供商认证和环境变量查找中。请将设置和状态环境变量元数据放在那里。

当计费或组织级凭据必须激活 resolveUsageAuth 而不成为推理凭据时，使用 providerUsageAuthEnvVars。这些名称会加入工作区 dotenv 阻止、ACP 子进程剥离、沙箱密钥过滤和广泛密钥清除。提供商运行时仍会在 resolveUsageAuth 内部读取并分类该值。

当没有可用的设置入口，或 setup.requiresRuntime: false 声明设置运行时不必要时，OpenClaw 还可以从 setup.providers[].authMethods 派生简单的设置选项。显式的 providerAuthChoices 条目仍优先用于自定义标签、CLI 标志、入门引导范围和助手元数据。

仅当这些描述符足以满足设置表面时，才设置 requiresRuntime: false。OpenClaw 将显式的 false 视为仅描述符契约，并且不会为设置查找执行 setup-api 或 openclaw.setupEntry。如果仅描述符插件仍然附带其中一个设置运行时入口，OpenClaw 会报告附加诊断并继续忽略它。省略 requiresRuntime 会保留旧版回退行为，因此已添加描述符但未设置该标志的现有插件不会中断。

由于设置查找可以执行插件自有的 setup-api 代码，规范化后的 setup.providers[].id 和 setup.cliBackends[] 值必须在已发现的插件之间保持唯一。所有权不明确时会失败关闭，而不是从发现顺序中选择一个获胜者。

当设置运行时执行时，设置注册表诊断会报告 setup-api 注册但没有匹配清单声明的提供商或 CLI 后端。CLI 后端描述符也会报告缺少运行时注册，因为设置查找需要已注册的后端配置。即使同一设置模块贡献了迁移、CLI 后端、探针或选定的提供商运行时，提供商描述符也可以保持仅元数据。

设置字段¶

setup.providers 参考¶

authEvidence 用于提供商自有的本地凭据标记，这些标记可以在不加载运行时代码的情况下进行验证。这些检查必须保持低成本且本地：不进行网络调用，不读取钥匙串或密钥管理器，不执行 shell 命令，也不进行提供商 API 探测。

支持的证据条目：

configGroups 参考¶

configGroups 将插件的设置页面组织为带标题的分区。它是位于 configSchema 旁边的展示元数据；不会添加配置键，也不会更改验证、默认值或运行时行为。

{
  "configGroups": [
    {
      "id": "connection",
      "title": "Connection",
      "order": 10,
      "properties": ["apiKey", "endpoint"]
    },
    { "id": "history", "title": "History", "order": 20, "properties": ["storage"] }
  ]
}

每个条目都需要非空的 id、title 和 properties 数组。属性指定 configSchema.properties 中的确切直接键；它们不是嵌套路径。嵌套对象及其后代保留在该属性的分区中。分组 id 和属性分配必须唯一。可选整数 order 按从低到高对分区排序（默认 0）；相同时保留 manifest 顺序。属性在每个分组内按编写顺序显示。

只有一级分区，默认全部可见。设置搜索会匹配字段名称、标签、描述和分组标题。未分配的属性显示在 其他 下。缺失或无效的分组元数据会保留完整的扁平表单可用；它永远不会隐藏字段或阻止插件加载。不支持分组的宿主会忽略此可选元数据。

uiHints 参考¶

uiHints 是从配置字段名称到小型渲染提示的映射。键可以使用点表示嵌套配置字段，但任何路径段都不得为 __proto__、constructor 或 prototype；setup 会拒绝这些名称。

{
  "uiHints": {
    "apiKey": {
      "label": "API key",
      "help": "Used for OpenRouter requests",
      "placeholder": "sk-or-v1-...",
      "sensitive": true
    }
  }
}

每个字段提示可以包含：

通道配置分区会为每个通道共享的叶子字段（enabled、allowFrom、dmPolicy、groupPolicy、streaming 以及类似项）继承 help，位置在通道根节点以及 accounts.<id> 下。如果某个通道为这些键之一声明了自己的 help，则始终优先，因此当共享措辞对你的提供商不适用时，请覆盖它。凭据、主机和 Webhook 等提供商特定键仍需要它们自己的提示。

当多个插件声明同一通道时，所选插件拥有其 schema 和展示提示。脱敏会保留从每个发现的所有者处发现的 sensitive: true 和 tags: ["url-secret"] 声明，因此配置中遗留的凭据在切换插件后仍受保护。url-secret 标签保护嵌入在 URL 中的凭据，同时让公共 URL 保持可见。设置 sensitive: false 会禁用基于名称的机密检测，但不会覆盖其他所有者的明确声明或 URL 凭据保护。