清单设置和身份验证字段

设置、载入和配置 UI 表面在插件运行时加载之前读取的清单字段。 插件清单参考的一部分； 顶级字段引用 列出了每个字段。

Native 对话发现

暴露在 OpenClaw 外部创建的会话的插件使用 label、可选的 description 和包含其目录 read/list/resume 命令名称的可选 nodeCommands 来声明 setup.nativeSessionCatalog。该合约使用插件现有的 config.sessionCatalog.enabled 首选项。核心在注册目录读取、列表、活动检查和声明的节点命令执行之前检查此首选项。 enabled 的架构生成的默认值在插件本地配置中仍然可用，但根运行时配置仅保留创作值，因此默认值无法冒充同意。

声明公开本机目录的命令，而不是独立授权的执行传输。禁用发现必须保留已绑定对话中的轮流；这些回合保留其现有的执行和节点权限。

当未编写首选项时，新声明默认为关闭，包括创建配置后安装的插件。他们的模式也应该默认 enabled 为 false。新的配置文件将 false 保留在主机生成的目录清单中，包括可安装的官方插件。始终保留显式值。这些仅限选择退出的条目不会请求安装或扩大插件白名单；显式的插件选择或其他创作的配置仍然有效。它们也不会产生禁用插件配置警告。现有的选择退出仍然有效，不需要医生重写；删除一个可以恢复旧的发现行为。

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

当所有声明的目录都关闭时，入门引导提供未经检查的启用选择；选择智能体并不意味着同意。显式选择也保留了已安装声明的选择。检测本身不写入任何偏好。

更改这些声明和 pnpm native-catalogs:check 后运行 pnpm native-catalogs:gen 以验证官方目录元数据和打包的 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 设置；省略选择主要角色。安装程序会验证实用程序角色，而无需替换工作主节点或其运行时和凭据。如果没有配置常规主系统，系统设置助手可以使用显式实用程序模型。自动实用程序默认从不引导安装。配置后，常规主节点优先，普通代理准备情况与实用程序设置保持独立。显式 provider-plugin:<provider>:<method> 选择保留为同一插件、提供程序和方法声明的角色。运行时向导元数据不需要重复清单的角色。裸提供程序选择还保留安装程序选择的方法的作用。确切的清单选择 ID 仍然拥有对无前缀选择的调度。

激活实用程序选项时，客户端必须回显 modelTarget: "utility"。在提供程序准备之前，丢失或不匹配的角色确认将被拒绝，因此较旧的客户端不会意外地将实用程序激活视为主要就绪。检测并成功报告activation/verification的作用。检测使 configuredModel 和 setupComplete 仅作为主要实用程序，公开显式 utilityModel，并仅当该实用程序是非主要设置后备时公开 setupModel。验证明确接受实用程序目标，包括与主要目标一起。

当 appGuidedDiscovery 为 true 时，匹配的提供程序身份验证方法必须公开 appGuidedSetup.detect 和 appGuidedSetup.prepare。检测必须是​​只读的：不能登录、模型拉取、下载或配置写入。准备工作会重新检查确切选择的模型并返回配置建议。 OpenClaw 保存所有返回的凭证，无需工具即可运行一轮确认，并仅在成功后激活提案。激活失败会保留保存的凭据以供重试；在用户接受激活之前，替代品将保持非活动状态。当本地服务可访问但没有模型符合自动设置条件时，提供商还可以公开 appGuidedSetup.detectAvailability 以将其设置选择标记为已检测到。可用性检查也是只读的。

登录选择

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

裸 /login 将可见的浏览器和设备代码选项分组到提供商按钮中，而无需开始登录。具有多种方法的提供者打开了第二个选择。没有命令按钮的通道显示要复制的命令。 Core 从清单构建此菜单；频道不保留单独的提供商列表。

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

基于浏览器的 channelLogin 方法在主机提供 ctx.oauth.authorize 时使用它。通过提供商生成的 state、timeoutMs 截止日期和 buildAuthorizationUrl(redirectUrl)。主机拥有 HTTPS 回调，消耗每个响应一次，并返回 { code, state }。该插件保留其 PKCE 验证器并交换代码。转发 ctx.signal 并在外部效果之前重新检查 ctx.assertCurrent。当不存在此功能时，保持本地和远程 CLI 完成。收到的代码不是持久的凭证；保存后主机才报告成功。

当 personalAccount 为 true 时，该方法通过共享向导协议运行，具有无凭据 environment/config、无代理目录或预置机密以及纯文本输入模式。它必须为其提供者返回一个内联凭证并取消荣誉。它不得导入本机 CLI 登录、解析 SecretRef、写入 credentials/config 或要求共享模型激活。网关拥有私人的每人提交； configPatch、defaultModel 和返回的共享配置文件 ID 不适用。将凭据提示标记为敏感。仅当提供商允许使用此凭据时才使用此功能。

个人帐户呼叫始终提供 ctx.assertCurrent。通过提供程序帮助程序保留此闭包绑定检查，并在外部效果之前立即调用它，包括在任何交互式或异步等待之后的发现、轮询和令牌交换。对于 fetchWithSsrFGuard，将其作为 beforeRequest 传递，以便它在 DNS/proxy 准备后和重定向时运行。继续转发ctx.signal取消飞行中工作；单独的信号不会重新检查该人当前的许可。独立 CLI/onboarding 呼叫可能会忽略检查，因为它们不携带网关人员的权限。

可选的 matchesPersonalAccount(credential, existing) auth-method hook 可以证明 OAuth 重新连接是同一提供商帐户。匹配完整的身份，而不仅仅是电子邮件或共享工作空间。如果没有该证明，则会创建一个新的 OAuth 帐户槽，并且旧的聊天 pin 会保留其原始凭据。 API 键和静态令牌仅在其字面值匹配时才重用槽。

setup 参考

在 setup 和 onboarding 界面需要在运行时加载之前就能获取插件自有的廉价元数据时，请使用 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 是控制 plane/setup 流的特定于设置的描述符表面，应仅保留元数据。

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

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

OpenClaw 会将 setup.providers[].envVars 纳入通用 provider 认证和环境变量查找。请将 setup 和状态环境元数据放在那里。

当计费或组织级凭证必须激活 resolveUsageAuth 而不成为推理凭证时，请使用 providerUsageAuthEnvVars。这些名称加入了工作区 dotenv 阻止、ACP 子进程剥离、沙箱秘密过滤和广泛的秘密清理。提供程序运行时仍然读取 resolveUsageAuth 内的值并对其进行分类。

当没有可用的设置条目或当 setup.requiresRuntime: false 声明不需要设置运行时时，OpenClaw 还可以从 setup.providers[].authMethods 导出简单的设置选择。对于自定义标签、CLI 标志、入门范围和助理元数据，显式 providerAuthChoices 条目仍然是首选。

只有在这些描述符足以满足 setup 界面的需要时，才设置 requiresRuntime: false。OpenClaw 会将显式的 false 视为仅描述符契约，并且不会为了 setup 查找而执行 setup-api 或 openclaw.setupEntry。如果一个仅描述符插件仍然提供了这些 setup 运行时入口之一，OpenClaw 会报告一个附加诊断并继续忽略它。省略 requiresRuntime 会保留旧版回退行为，因此不会破坏那些在未设置该标志的情况下添加了描述符的现有插件。

由于安装查找可以执行插件拥有的 setup-api 代码，因此规范化的 setup.providers[].id 和 setup.cliBackends[] 值必须在发现的插件中保持唯一。不明确的所有权会阻止设置查找，而不是从发现顺序中挑选获胜者。

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

setup 字段

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）；关系保持明显的秩序。属性按每个组中创建的顺序显示。

有一层部分，默认情况下全部可见。设置搜索匹配字段名称、标签、描述和组标题。未分配的属性显示在 Other 下。缺少或无效的分组元数据使完整的平面表单可用；它永远不会隐藏字段或阻止插件加载。不支持分组的主机会忽略此可选元数据。

uiHints 参考

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

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

每个字段提示可以包含：

通道配置部分继承 help，用于通道根处和 accounts.<id> 下每个通道共享的叶子（enabled、allowFrom、dmPolicy、groupPolicy、streaming 等）。为这些密钥之一声明自己的 help 的通道总是获胜，因此只要共享措辞对您的提供商来说是错误的，请覆盖它。特定于提供商的密钥（例如凭据、主机和 Webhook）仍然需要自己的提示。

当多个插件声明同一通道时，所选插件拥有其架构和表示提示。密文会保留每个已发现所有者的 sensitive: true 和 tags: ["url-secret"] 声明，因此在切换插件后，配置中保留的凭据仍会受到保护。 url-secret 标签可保护嵌入在 URL 中的凭据，同时使公共 URL 可见。设置 sensitive: false 会禁用基于名称的秘密检测，但不会覆盖其他所有者的肯定声明或 URL 凭证保护。