配置覆盖
Kiki 有三个地方可以影响运行参数：配置文件、命令行选项、环境变量。它们不是简单的"谁优先级高谁赢"——三者面向不同场景，作用范围互不相同：
- 配置文件 保存长期偏好（模型、循环控制等），供应商凭证放在配套的
credentials.toml里；两者每次启动都生效 - 命令行选项 做本次启动的临时切换，退出后失效
- 环境变量 主要负责数据目录定位、OAuth 端点切换，以及少数运行时开关——不是配置字段的通用后备来源
这个区别很关键：很多人会在 shell 里 export KIMI_API_KEY=xxx，以为 CLI 会自动取到，但实际上不会。原因见下文供应商凭证。
环境变量的两类作用
环境变量按作用分两类，不能合并成一条线性优先级：
- 定位配置文件：
KIKI_HOME决定数据根目录，配置文件路径因此变为$KIKI_HOME/config.toml，其配套的凭证文件为$KIKI_HOME/credentials/credentials.toml。这一步先于其他所有解析，不是普通参数的后备来源。 - 运行端点与诊断：
KIKI_CODE_OAUTH_HOST、KIKI_CODE_BASE_URL、KIKI_LOG_LEVEL等在 OAuth 或日志子系统初始化时读取。完整列表见环境变量。
普通运行参数的优先级
对模型别名、Plan 模式、yolo 模式、Skills 目录等普通运行参数，优先级从高到低：
- 命令行选项（
-m、--plan、--yolo等）：仅对本次启动生效 - 用户配置文件（
~/.kiki/config.toml）：保存长期偏好
少数环境变量明确覆盖特定配置字段，例如 KIKI_BACKGROUND_KEEP_ALIVE_ON_EXIT 的优先级高于 [background].keep_alive_on_exit。这类例外在环境变量和配置文件对应字段里都有标注。
WARNING
普通运行参数不会从 shell 环境变量取后备值。 供应商只有在你通过 api_key_env 显式指定变量名时才读取 shell 密钥，具体规则见下文。独立的 KIKI_MODEL_* 通道也能提供临时模型与密钥——详见用环境变量定义模型。
CLI 从 KIKI_HOME（默认 ~/.kiki）读取用户级配置，并从 <项目根目录>/.kiki/local.toml 读取项目级设置。旧的 .kimi-code/local.toml 路径不会读取。需要在不同项目间隔离配置时，用 KIKI_HOME 指向不同的数据目录——见下文典型场景。
供应商凭证
供应商凭证（api_key、base_url）有独立的解析规则，不走普通参数的优先级链。
供应商的 API 密钥存放在数据根目录下的 credentials/credentials.toml。Kiki 把两个文件当作一份文档读取，同一条 TOML 路径上 credentials.toml 的值优先；config.toml 不会保存明文凭证。文件位置、权限以及首次加载迁移见供应商凭证。
模型自身的 API 密钥或 OAuth 引用优先于供应商凭证。对于使用 API 密钥的供应商，其余来源按以下顺序解析：
[providers.<name>].api_key——已保存的密钥；非空值优先于环境来源。- 已设置
api_key_env时，若[providers.<name>.env]中存在同名项，就读该项；否则读取 Kiki 进程的同名环境变量。子表中的显式空值不会回退到进程环境。变量缺失或为空白时，API 密钥仍为未配置状态，也不会改试其他变量。 - 未设置
api_key_env时，沿用供应商类型在[providers.<name>.env]中的原有密钥键（KIMI_API_KEY、ANTHROPIC_API_KEY等）。这些已保存的密钥值同样放在credentials.toml中，不会隐式回退到 shell。
若要把密钥保留在环境中，只在 config.toml 中保存变量名：
[providers.gateway]
type = "openai"
base_url = "https://api.example.com/v1"
api_key_env = "YOUR_PROVIDER_KEY"从已经设置 YOUR_PROVIDER_KEY 的进程启动 Kiki。通过快捷方式启动的桌面应用不一定继承终端里的变量。已有供应商若要改用环境密钥，请先清除 api_key，否则仍优先使用已保存的密钥。Kiki 不会把解析出的环境值复制到凭证存储。供应商就绪状态、模型请求和模型发现使用同一解析规则；就绪只表示有可用值，不表示远端服务已接受该密钥。
供应商的 OAuth 引用仍走原有令牌流程。与已保存的密钥一样，解析成功的环境密钥不能与同一供应商层的 OAuth 同时使用。
base_url 保持原规则：先读 [providers.<name>].base_url，再读 [providers.<name>.env] 中的 *_BASE_URL 键。它不是密钥，仍留在 config.toml。env 子表不会向 shell 环境写入值。
完整的凭证键名列表见环境变量：供应商凭证键。
命令行选项
启动时传入的选项优先级最高，只对本次启动生效：
| 选项 | 作用 |
|---|---|
-S, --session [id] | 恢复指定会话；不带 id 时进入交互式选择 |
-c, --continue | 续上当前目录的上一次会话 |
-y, --yolo | 自动批准普通工具调用，Agent 仍可能提问 |
--auto | 以 auto 权限模式启动：普通操作自动批准，受保护访问先请求审批，Agent 仍可提问 |
--plan | 以 Plan 模式启动 |
-m, --model <model> | 指定本次使用的模型别名 |
-p, --prompt <prompt> | 非交互模式：执行单条提示词后退出 |
--output-format <format> | -p 模式的输出格式：text 或 stream-json |
--skills-dir <dir> | 替换自动发现的 Skills 目录（可重复，仅本次生效） |
互斥规则（违反时启动报错）：
--output-format只能配合-p使用--prompt不能同时用--yolo或--plan--continue和--session不能同时用- 非 prompt 模式下，
--yolo和--plan不能配合--continue或--session
TIP
--skills-dir 是一次性替换，只影响本次启动。如需长期追加搜索目录，在 config.toml 里写 extra_skill_dirs（详见 Agent Skills）。
模型与 effort 解析
先确定本次派发使用的模型，再解析该模型的 thinking effort。Route 与 caller lease 上的 pin 是可以被覆盖的默认值；allowed_models、deny_models、allowed_efforts 在每个 profile、lease、树策略与匹配 model_profiles 作用域都是硬限制——对 subagent 而言，越界会拒绝绑定、人工切换与恢复；在主会话中则以你的选择为准，越界只警示。模型本身不支持的值则无论哪种情况都会报错。
profile 绑定时——新建主会话、新建 subagent、切换模型，或原生 AgentRun 派发——先从该角色自身的来源取出请求的 effort，再对照所绑定的模型解析：
- 调用时显式传入的
effort。 - 主会话中取 persona 或 route 上锁定的 effort；subagent 中取 route 上锁定的 effort，route 未锁定时改用 caller lease 的。两者其后都是匹配的
model_profiles条目，再后是 profile 顶层的thinking_effort。 - 所绑定模型的首选 effort。
[models."<alias>"].overrides.default_effort。- 模型自身的
default_effort。
如果以上都取不到值，或解析出的 effort 不被该模型支持，绑定会以配置错误失败，而不是悄悄替你挑一个。完全没有配置模型时，绑定会同时要求提供模型和 effort。只要 route、lease、profile pin 或模型默认里已经有可用值，就不必每次都传 effort；只有全都取不到时才需要，此时配置相应的 pin 或在本次调用里提供 effort。
这些规则只作用于 profile 绑定。保留既有有效绑定的普通 resume 不会重新计算，因此早先保存的 effort 继续有效。只修改 effort 时保留已保存的模型；resume 时切换模型仍需 allow_model_change: true。
不经过 profile 绑定的路径保持原样：全局 [thinking] 仍提供兜底，[thinking].enabled = false 在这些路径上仍会把未固定的 effort 解析为 Off。
提示词字段优先级
提示词文案字段使用独立的优先级链。从低到高：全局 [prompt.overrides]、模型 [models."<alias>".prompt_overrides]、Agent 或 SYSTEM.md Frontmatter 的 prompt_overrides，然后是匹配的 model_profiles[].prompt_overrides。Agent 文件与 SYSTEM.md 位于同一层，所以 4 层里一共 5 个配置表面。
每个表面都接受 files 与 fields。文件从 Kiki 主目录读取，按列表顺序应用，随后由同一表面的内联字段覆盖。高层未声明的字段继承低层值，字段值绝不会拼接。外部文件 schema、常用字段示例，以及从已移除的 prompt.shared / prompt.tools 键迁出的方法见 prompt。
典型场景
隔离测试环境——用单独的数据目录，避免污染主配置和会话：
KIKI_HOME="$PWD/.kiki-sandbox" kiki在配置文件中保存测试密钥——把密钥写进 credentials.toml。若只想通过环境传入密钥，使用上文的 api_key_env 示例：
# ~/.kiki/credentials/credentials.toml
[providers.kimi.env]
KIMI_API_KEY = "sk-test"本次会话自动批准工具调用：
kiki --yolo--yolo 作用于交互式会话，不能与 -p 组合使用——见上文互斥规则。
临时进入 Plan 模式（若想永久生效，在配置文件设 default_plan_mode = true）：
kiki --plan