模型与引擎选择
选择后端引擎、挑选模型、使用实时模型列表，并为新会话保存偏好的模型选择。
在 Kaiwu 应用界面中，运行会话所选用的后端称为引擎（engine）。
引擎可以是：
- 内置的提供商后端，例如 Claude、Codex、Gemini、OpenCode 或 Pi
- 配置好的自定义 ACP（Custom ACP）后端
- 提供商集成所提供的后端变体
引擎内部的模型（Model）区域用于控制由该提供商的哪个模型来运行会话。
入口位置
打开新建会话流程，使用底栏中的引擎选择器。
选择器左侧显示可选引擎，右侧显示当前选中引擎的详细信息，包括：
- 模型选项
- 提供商或 ACP 配置项
- Kaiwu 探测所选设备时的刷新状态
- 提供商开放的模型专属控制项
运行中的会话也可以在当前会话的输入设置中打开模型/配置选择器。收藏夹则属于新建会话引擎选择器的一部分。
在运行中的会话内部，该选择器还可以用来切换 Agent 本身——详见使用其他 Agent 继续。
选择引擎
挑选用来启动会话的引擎。
列表具备能力感知特性：
- 已禁用的提供商或隐藏的后端不会出现
- 配置好的 ACP 后端会作为常规引擎选项显示
- 配置文件可以过滤兼容的引擎
- 引擎详情会因设备、工作目录、配置文件以及连接服务状态的不同而有所差异
如果只有一个可用引擎，Kaiwu 会跳过大部分选择器界面，直接使用该引擎。
选择模型
大多数模型选择器首项都是使用 CLI 设置（Use CLI settings）。
如果你希望 Kaiwu 不要覆盖模型设置，而是由提供商 CLI/运行时依据自身配置决定，请使用此选项。
选择具体模型后，Kaiwu 会保存该选项用于启动会话。具体的生效行为取决于提供商和运行时：部分提供商可以在下一条提示词或通过 ACP 实时切换模型；其他提供商则只有在启动新的提供商进程时才会应用模型。
关于运行中会话的生效时机，请参阅权限。
动态模型列表
部分引擎会动态暴露模型。Kaiwu 会探测所选的设备或后端，并列出该后端当前报告的模型。
这一机制非常实用，因为可用列表可能取决于：
- 已安装的提供商 CLI 版本
- 提供商是否已登录
- 账户或订阅权益
- 所选的连接服务配置文件
- 自定义 ACP 后端的参数与环境变量
- 提供商使用项目本地配置时所选的工作目录
在更改提供商登录状态、CLI 配置、自定义 ACP 设置或工作目录后，请点击模型区域的刷新按钮。
静态模型列表
并非所有提供商都具备动态模型 API。
对于仅支持静态列表的提供商，Kaiwu 会改用内置的提供商目录。Claude 就是典型代表：尽管其模型列表是静态的而非动态探测得出，但 Claude 模型依然可以正常选择与收藏。
当 Kaiwu 更新其提供商目录时，静态模型列表也会随之更新。
自定义模型 ID
部分引擎支持输入自定义模型 ID。
如果明确知道具体的模型 ID，但该 ID 未显示在列表中，可以在对应的提供商或配置文件中使用此功能。
注意事项：
- Kaiwu 会将 ID 发送给提供商，依然由提供商决定该 ID 是否有效。
- 自定义 ID 适用于兼容提供商协议的网关、自定义端点或新发布的模型。
- 自定义 ID 不会自动成为收藏候选对象。收藏功能仅支持 Kaiwu 能从当前动态列表或静态目录中验证的模型。
模型专属选项
部分模型会提供额外的控制项，例如思考（thinking）、推理（reasoning）、算力消耗（effort）或提供商专属模式。
当存在这些控制项时，Kaiwu 会将其展示在所选模型的卡片内。它们属于所选引擎配置面板的一部分，并非独立的全局设置页面。
并非所有提供商都会提供这些选项，同一提供商旗下的不同模型所提供的选项也可能各不相同。
收藏模型
收藏模型有助于整理出一份常用模型的精简列表。
收藏模型的步骤：
- 打开新建会话引擎选择器。
- 选择一个引擎。
- 选择一个具体模型。
- 点击所选模型卡片上的星标按钮。
实心星标表示该模型已被收藏；空心星标表示可以添加收藏。
默认的使用 CLI 设置选项无法收藏，因为它不是具体的模型选项。
收藏夹区域
保存至少一个收藏模型后，引擎选择器的左侧栏会显示收藏夹（Favorites）区域。
你可以借此直接跳转到已保存的引擎/模型组合，无需在长长的模型列表中翻找。
选择收藏项将会：
- 切换至该收藏对应的引擎
- 应用该收藏对应的模型
- 其余启动设置（例如配置文件、权限、模式和配置项）依然遵循普通新建会话的控制逻辑
收藏属于账户级设置。它们按后端身份标识和模型 ID 分别保存，因此同一个模型 ID 可以在两个不同的引擎或自定义 ACP 后端下分别独立收藏。
取消收藏
点击实心星标即可取消收藏：
- 在常规模型列表中，当已收藏的模型可见时点击
- 在收藏夹区域中点击
已收藏的模型会始终显示实心星标，无需先选中即可直接取消收藏。
可用性规则
收藏虽然已保存，但选用时依然取决于后端的当前状态。
对于动态探测的引擎：
- 只有当前探测报告该模型可用时，收藏项才可被选中
- 若因认证变更、CLI 变动或提供商下架导致模型消失，Kaiwu 不会使用该不可用模型启动会话
- 修复登录状态或配置后，请刷新探测
对于仅静态列表的引擎：
- 收藏项会对照 Kaiwu 的静态提供商目录进行校验
- Claude 模型无需动态探测，即可直接从目录中收藏和选用
若保存的收藏项不再出现在当前的动态/静态模型列表中，Kaiwu 会将其保留在收藏夹区域并附带设置提示，以便你将其移除。在后端重新报告该模型前，该项将无法选用。
配置文件与后端兼容性
收藏项会遵循当前的引擎列表规则。
如果选中的配置文件过滤掉了某个引擎，那么在当前选择器状态下，该不兼容引擎对应的收藏项会在收藏夹区域中隐藏。
这样可以确保收藏夹区域始终聚焦于适合当前启动配置的选项。
收藏不保存的内容
收藏项仅保存“引擎/模型”配对，无法替代配置文件或后端设置。
收藏不保存以下内容：
- API 密钥或连接服务凭据
- 环境变量
- 工作目录
- 权限模式
- 会话模式
- 推理力度（reasoning effort）等模型专属控制项
如需复用环境、密钥、端点和后端默认配置，请使用配置文件。
常见使用场景
在以下场景中推荐使用模型收藏功能：
- 常用 Claude、Codex 或 Gemini 模型，希望一键直达
- 需要在轻量快速模型与深度推理模型之间迅速切换
- 为多个自定义 ACP 后端保存各自常用的模型
- 不想在冗长的动态模型列表中反复翻找
- 提供商登录或权益问题暂时导致模型隐藏时，仍想保留该收藏配置
故障排查
收藏项可见但无法启动
模型配置已保存，但当前后端未报告其可用。
请检查提供商登录状态、连接服务配置文件、自定义 ACP 配置以及所选设备，随后刷新模型探测。
收藏项从左侧栏消失
收藏夹区域仅显示当前可见且与选择器状态兼容的引擎收藏。
请检查是否有选中的配置文件或功能设置隐藏了对应的引擎。
无法收藏自定义模型 ID
收藏功能仅支持 Kaiwu 能从动态探测或静态目录中验证的具体模型。
临时 ID 请直接使用自定义模型输入框。如果提供商后续在其模型列表中列出了该 ID，届时便可加入收藏。