配置方案

使用后端配置方案，在 App 与 CLI 之间复用环境变量、机密绑定以及启动默认值。

后端配置文件可将具名后端配置保存下来，并在每次启动会话时直接复用。

适合使用配置文件的场景：

将提供商切换到其他端点或认证方案
在多个会话间复用相同的环境变量
一次性绑定所需机密，免去重复输入的麻烦
让客户端 UI、守护进程和 CLI 始终使用随账户同步的同一套配置文件定义
使用同一套配置文件模型，对接内置提供商或已配置的 Custom ACP 后端

应用示例：

将 Claude 指向 DeepSeek 或 Z.AI 运行
让 Codex 使用 OpenAI API 密钥或 Azure OpenAI 运行
让 Gemini 使用 API 密钥或 Vertex AI 运行
创建包含专属环境变量的自定义配置文件，例如 “Work Codex” 或 “Staging Claude”

配置文件包含的内容

配置文件可包含以下内容：

会话启动时注入的环境变量
会话启动前必须就绪的变量依赖项
针对所需机密的已保存机密绑定
与一个或多个后端的兼容性设置，包括已配置的 ACP 后端
各后端的默认启动偏好设置，例如支持的默认权限和会话记录存储设置

配置文件仅在启动新会话时生效。会话一旦启动，其配置文件即固定不变。若要切换配置文件，请启动新会话。

内置配置文件与自定义配置文件

Kaiwu 预置了针对常见环境的内置配置文件，同时也支持创建自定义配置文件。

内置示例包括：

面向 CLI 登录环境的 Anthropic (Default)、Codex (Default) 和 Gemini (Default)
用于兼容 Claude 路由的 DeepSeek (Reasoner) 和 Z.AI (GLM-4.6)
面向 Codex 的 OpenAI (GPT-5) 和 Azure OpenAI
Gemini (API key) 与 Gemini (Vertex AI)

你也可以针对自定义端点、模型和环境变量创建专属的配置文件。

注意：在 UI 中编辑内置配置文件会生成一份自定义副本，内置版本本身保持不变。

启用配置文件

配置文件功能在客户端 UI 中默认关闭，需手动开启：

打开 Settings → Features
开启 Profiles
打开 Settings → Profiles

若未开启 Profiles，客户端将直接回退到设备本地环境，无法选择配置文件。

在客户端中创建配置文件

打开 Settings → Profiles
点击 Add Profile
输入清晰易辨的配置名称
选择该配置兼容的后端
添加 Kaiwu 在会话启动时需要注入的环境变量
将所需变量标记为相应类型：
- Secret：由 Kaiwu 通过已保存的机密、设备环境变量或交互式提示输入流程来提供
- Config：目标设备上必须预先存在的环境变量
保存配置文件

推荐实践：

将提供商选择、Base URL 和模型 ID 直接写入配置文件
将 API 密钥/令牌标记为必要机密
针对跨设备复用的凭据，建议使用已保存的机密进行管理

在客户端 UI 中使用配置文件

启用 Profiles 后：

从客户端启动新会话
选择要运行的后端
选择所需的配置文件
若 Kaiwu 提示缺少必要配置，按提示补齐

对于从 UI 启动或远程启动的会话，Kaiwu 可通过以下途径获取所需机密：

守护进程所在主机上的设备环境变量
绑定到该配置文件的已保存机密
在会话启动时输入的仅当前会话有效的临时机密

若目标设备缺少必要的配置环境变量，客户端会阻止启动，避免运行异常会话。

会话启动后，所选配置文件会显示在 Session Info → AI Profile 中。

已配置的 ACP 后端与内置后端遵循相同的处理流程。如果某个配置文件专为特定后端设计，Kaiwu 会直接保持两者的对应关系。

在 CLI 中使用配置文件

CLI 会读取与客户端相同的账户设置，登录后即可直接使用已保存的自定义配置文件。

列出可用配置文件

Kaiwu profiles list
Kaiwu profile list

脚本调用方式：

Kaiwu profiles list --json

若需要强制刷新设置：

Kaiwu profiles list --refresh-settings

若未登录，CLI 仅会显示内置配置文件。

使用指定配置文件启动会话

启动会话时传入 --profile ⟦K6⟧：

Kaiwu --profile anthropic
Kaiwu claude --profile deepseek
Kaiwu codex --profile openai
Kaiwu codex --profile "Work Codex"
Kaiwu gemini --profile gemini-vertex