feat: define model via KIMI_MODEL_* environment variables

.changeset/env-var-model-config.md

@@ -0,0 +1,6 @@
+---
+"@moonshot-ai/agent-core": minor
+"@moonshot-ai/kimi-code": minor
+---
+
+Add a `KIMI_MODEL_*` environment-variable channel that lets you run Kimi Code against a specific model (provider type, base URL, API key, context size, capabilities, and thinking settings) without editing `config.toml`.

apps/kimi-code/src/tui/components/chrome/welcome.ts

@@ -51,9 +51,10 @@ export class WelcomeComponent implements Component {
       primary(logo[1]!.padEnd(logoWidth)) + gap + rightRow1,
     ];
 
+    const activeModel = this.state.availableModels[this.state.model];
     const modelValue = isLoggedOut
       ? chalk.hex(this.colors.warning)('not set, run /login or /connect')
-      : this.state.model;
+      : (activeModel?.displayName ?? activeModel?.model ?? this.state.model);
 
     const infoLines = [
       labelStyle('Directory: ') + this.state.workDir,

docs/en/configuration/config-files.md

@@ -138,6 +138,8 @@ model = "gpt-4.1"
 max_context_size = 1047576
 ```
 
+For testing, you can also synthesize a model entirely from `KIMI_MODEL_*` environment variables without editing this file — see [Define a model from environment variables](./env-vars.md#define-a-model-from-environment-variables-kimi-model).
+
 ## `thinking`
 
 `thinking` controls the default behavior of Thinking mode. Even when the top-level `default_thinking = true`, setting `mode` to `"off"` will still force Thinking off.

docs/en/configuration/env-vars.md

@@ -3,7 +3,7 @@
 Kimi Code CLI uses environment variables to override default paths, switch OAuth endpoints, and adjust runtime behavior. Most variables are read when the `kimi` process starts up; a few (such as the telemetry switch, the OAuth lock, and diagnostic logging) are read when the relevant subsystem initializes. Kimi's own variables use the `KIMI_*` prefix; in addition, the CLI also reads a number of standard system variables.
 
 ::: warning Note
-**Provider credentials are not in this list**: key variables such as `KIMI_API_KEY`, `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, and `GOOGLE_API_KEY` are **not** read automatically from `process.env`. They must be written into the `[providers.<name>]` section of `config.toml` (as `api_key` / `base_url`) or into the `[providers.<name>.env]` subtable; merely `export`ing them in your shell will not give a provider credentials automatically. See [Configuration overrides](./overrides.md#provider-credentials) and [Providers](./providers.md) for details.
+**Provider credentials are not in this list**: key variables such as `KIMI_API_KEY`, `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, and `GOOGLE_API_KEY` are **not** read automatically from `process.env`. They must be written into the `[providers.<name>]` section of `config.toml` (as `api_key` / `base_url`) or into the `[providers.<name>.env]` subtable; merely `export`ing them in your shell will not give a provider credentials automatically. See [Configuration overrides](./overrides.md#provider-credentials) and [Providers](./providers.md) for details. **Exception:** the `KIMI_MODEL_*` variables are an explicit channel that *does* read a model and its credentials from the shell — see [Define a model from environment variables](#define-a-model-from-environment-variables-kimi-model).
 :::
 
 ## Core paths
@@ -67,6 +67,36 @@ When neither `KIMI_CODE_OAUTH_HOST` nor `KIMI_OAUTH_HOST` is set, the OAuth auth
 `KIMI_CODE_BASE_URL` and the `KIMI_BASE_URL` from the previous section are two different variables: the former targets the OAuth-logged-in hosted service and defaults to `kimi.com`; the latter targets providers that use a Kimi API key directly and defaults to `moonshot.ai`. Distinguish them by use case.
 :::
 
+## Define a model from environment variables (`KIMI_MODEL_*`)
+
+For testing you can make Kimi Code use a specific model **without editing `config.toml` at all**. When `KIMI_MODEL_NAME` is set, the CLI synthesizes one provider and one model alias from the `KIMI_MODEL_*` variables — in memory only, nothing is written back to `config.toml` — and selects it as the default model. These variables take priority over `default_model` in `config.toml`; a `-m <alias>` flag still wins for that launch.
+
+| Environment variable | Required | Purpose | Default |
+| --- | --- | --- | --- |
+| `KIMI_MODEL_NAME` | Yes (also the enable switch) | Model id sent to the API | — |
+| `KIMI_MODEL_API_KEY` | Yes | API key | — |
+| `KIMI_MODEL_PROVIDER_TYPE` | No | Provider type; one of `kimi`, `anthropic`, `openai` | `kimi` |
+| `KIMI_MODEL_BASE_URL` | No | API base URL | `kimi` → `https://api.moonshot.ai/v1`; `openai` → `https://api.openai.com/v1`; `anthropic` → SDK default |
+| `KIMI_MODEL_MAX_CONTEXT_SIZE` | No | Max context length in tokens (positive integer) | `262144` (256K) |
+| `KIMI_MODEL_CAPABILITIES` | No | Comma-separated capability tags (e.g. `image_in,thinking`); unioned with auto-detected capabilities | `image_in,thinking` |
+| `KIMI_MODEL_DISPLAY_NAME` | No | Name shown in `/model` | Falls back to `KIMI_MODEL_NAME` |
+| `KIMI_MODEL_MAX_OUTPUT_SIZE` | No | Per-request output cap (`anthropic` only) | Per-model default |
+| `KIMI_MODEL_REASONING_KEY` | No | Reasoning field-name override (`openai` only) | Auto-detected |
+| `KIMI_MODEL_DEFAULT_THINKING` | No | Default Thinking toggle for new sessions | Unset follows the global default (Thinking on) |
+| `KIMI_MODEL_THINKING_MODE` | No | Thinking trigger policy; `auto`/`on`/`off` | — |
+| `KIMI_MODEL_THINKING_EFFORT` | No | Thinking effort (e.g. `low`/`medium`/`high`/`xhigh`/`max`; available levels depend on the provider) | — |
+
+The synthesized entries use the reserved keys `__kimi_env__` (provider) and `__kimi_env_model__` (model alias). When `KIMI_MODEL_NAME` is set but a required variable is missing or invalid, startup fails with a clear error.
+
+```sh
+export KIMI_MODEL_NAME="kimi-for-coding"
+export KIMI_MODEL_BASE_URL="https://api-staff.msh.team/v1"
+export KIMI_MODEL_API_KEY="$MOONSHOT_STAFF_KEY"
+export KIMI_MODEL_MAX_CONTEXT_SIZE="262144"
+export KIMI_MODEL_CAPABILITIES="image_in,thinking"
+kimi
+```
+
 ## Runtime switches
 
 | Environment variable | Purpose | Valid values / Default |

docs/en/configuration/overrides.md

@@ -20,7 +20,7 @@ For other runtime parameters (model alias, Plan / yolo mode, Skills directories,
 A few environment variables explicitly override related config fields. For example, `KIMI_CODE_BACKGROUND_KEEP_ALIVE_ON_EXIT` has higher priority than `[background].keep_alive_on_exit`. These exceptions are called out in [Environment variables](./env-vars.md) and in the corresponding [Config files](./config-files.md) field reference.
 
 ::: warning Note
-Ordinary runtime parameters **do not** fall back to shell environment variables. For example, provider `api_key` / `base_url` are read only from fields in `config.toml` (including the `[providers.<name>.env]` subtable); they do not fall back to shell exports like `export KIMI_API_KEY`. See [Provider credentials](#provider-credentials) below.
+Ordinary runtime parameters **do not** fall back to shell environment variables. For example, provider `api_key` / `base_url` are read only from fields in `config.toml` (including the `[providers.<name>.env]` subtable); they do not fall back to shell exports like `export KIMI_API_KEY`. See [Provider credentials](#provider-credentials) below. The one exception is the explicit `KIMI_MODEL_*` channel, which synthesizes a model (and its credentials) from the shell; see [Define a model from environment variables](./env-vars.md#define-a-model-from-environment-variables-kimi-model).
 :::
 
 Kimi Code CLI currently reads only one user-level config file. There is no project-level (in-repo) config file mechanism. To isolate configuration between projects, point `KIMI_CODE_HOME` at a different data directory (see [Typical scenarios](#typical-scenarios) below) or temporarily override specific fields with CLI flags at launch.
@@ -31,7 +31,7 @@ The config file location is controlled by the `KIMI_CODE_HOME` environment varia
 
 ## Provider credentials
 
-Provider credentials (`api_key`, `base_url`) have their own resolution rules: Kimi Code CLI reads provider fields only from `config.toml` and **does not** fall back to shell environment variables. Running `export KIMI_API_KEY` in your terminal alone will not give a `[providers.<name>]` entry credentials — you have to write them into the config file explicitly.
+Provider credentials (`api_key`, `base_url`) have their own resolution rules: Kimi Code CLI reads provider fields only from `config.toml` and **does not** fall back to shell environment variables. Running `export KIMI_API_KEY` in your terminal alone will not give a `[providers.<name>]` entry credentials — you have to write them into the config file explicitly. The one exception is the explicit `KIMI_MODEL_*` channel, which synthesizes a model (and its credentials) from the shell; see [Define a model from environment variables](./env-vars.md#define-a-model-from-environment-variables-kimi-model).
 
 For a single provider, credentials are resolved in this order:
 

docs/zh/configuration/config-files.md

@@ -138,6 +138,8 @@ model = "gpt-4.1"
 max_context_size = 1047576
 ```
 
+为了便于测试，你也可以完全不修改本文件，直接用 `KIMI_MODEL_*` 环境变量合成出一个模型 —— 详见 [用环境变量定义模型](./env-vars.md#用环境变量定义模型-kimi-model)。
+
 ## `thinking`
 
 `thinking` 控制 Thinking 模式的默认行为。即便顶层 `default_thinking = true`，将 `mode` 设为 `"off"` 也会强制禁用 Thinking。

docs/zh/configuration/env-vars.md

@@ -3,7 +3,7 @@
 Kimi Code CLI 通过环境变量来覆盖默认路径、切换 OAuth 端点以及调整运行时行为。大部分变量在 `kimi` 进程启动时读取，少数（如遥测开关、OAuth 锁、诊断日志）在相关子系统初始化时读取。Kimi 自有变量使用 `KIMI_*` 前缀；此外，CLI 也会读取若干系统标准变量。
 
 ::: warning 注意
-**供应商凭证不在此列**：`KIMI_API_KEY`、`ANTHROPIC_API_KEY`、`OPENAI_API_KEY`、`GOOGLE_API_KEY` 等密钥变量**不会**从 `process.env` 自动读取。它们必须写在 `config.toml` 的 `[providers.<name>]` 段（`api_key` / `base_url`）或 `[providers.<name>.env]` 子表中；仅在 shell 中 `export` 不会让某个供应商自动获得凭证。详见 [配置覆盖](./overrides.md#供应商凭证) 与 [供应商](./providers.md)。
+**供应商凭证不在此列**：`KIMI_API_KEY`、`ANTHROPIC_API_KEY`、`OPENAI_API_KEY`、`GOOGLE_API_KEY` 等密钥变量**不会**从 `process.env` 自动读取。它们必须写在 `config.toml` 的 `[providers.<name>]` 段（`api_key` / `base_url`）或 `[providers.<name>.env]` 子表中；仅在 shell 中 `export` 不会让某个供应商自动获得凭证。详见 [配置覆盖](./overrides.md#供应商凭证) 与 [供应商](./providers.md)。**例外：** `KIMI_MODEL_*` 这组变量是一个显式通道，*确实*会从 shell 读取一个模型及其凭证 —— 详见 [用环境变量定义模型](#用环境变量定义模型-kimi-model)。
 :::
 
 ## 核心路径
@@ -67,6 +67,36 @@ OAuth 流程默认连接 Kimi 官方的认证与托管端点，下列变量可
 `KIMI_CODE_BASE_URL` 与上一节的 `KIMI_BASE_URL` 是两个不同变量：前者面向 OAuth 登录的托管服务，默认指向 `kimi.com`；后者面向直接使用 Kimi API 密钥的供应商，默认指向 `moonshot.ai`。请按场景区分。
 :::
 
+## 用环境变量定义模型(`KIMI_MODEL_*`)
+
+为了便于测试，你可以**完全不修改 `config.toml`** 就让 Kimi Code 使用指定的模型。当设置了 `KIMI_MODEL_NAME` 时，CLI 会从 `KIMI_MODEL_*` 变量合成出一个供应商和一个模型别名 —— 仅存在于内存中，不会写回 `config.toml` —— 并将其选为默认模型。这些变量的优先级高于 `config.toml` 中的 `default_model`；而 `-m <alias>` 选项在本次启动中仍然优先。
+
+| 环境变量 | 必填 | 用途 | 默认值 |
+| --- | --- | --- | --- |
+| `KIMI_MODEL_NAME` | 是（同时是启用开关） | 发送给 API 的模型 id | — |
+| `KIMI_MODEL_API_KEY` | 是 | API 密钥 | — |
+| `KIMI_MODEL_PROVIDER_TYPE` | 否 | 供应商类型，可选 `kimi`、`anthropic`、`openai` | `kimi` |
+| `KIMI_MODEL_BASE_URL` | 否 | API 基础 URL | `kimi` → `https://api.moonshot.ai/v1`；`openai` → `https://api.openai.com/v1`；`anthropic` → SDK 默认值 |
+| `KIMI_MODEL_MAX_CONTEXT_SIZE` | 否 | 最大上下文长度（token 数，正整数） | `262144`（256K） |
+| `KIMI_MODEL_CAPABILITIES` | 否 | 逗号分隔的能力标签（如 `image_in,thinking`）；与自动探测的能力做并集 | `image_in,thinking` |
+| `KIMI_MODEL_DISPLAY_NAME` | 否 | 在 `/model` 中显示的名称 | 回退到 `KIMI_MODEL_NAME` |
+| `KIMI_MODEL_MAX_OUTPUT_SIZE` | 否 | 单次请求的输出上限（仅 `anthropic`） | 模型默认值 |
+| `KIMI_MODEL_REASONING_KEY` | 否 | 推理字段名覆盖（仅 `openai`） | 自动探测 |
+| `KIMI_MODEL_DEFAULT_THINKING` | 否 | 新会话的默认 Thinking 开关 | 未设时跟随全局默认（Thinking 开启） |
+| `KIMI_MODEL_THINKING_MODE` | 否 | Thinking 触发策略，可选 `auto`/`on`/`off` | — |
+| `KIMI_MODEL_THINKING_EFFORT` | 否 | Thinking 强度（如 `low`/`medium`/`high`/`xhigh`/`max`；实际可用等级由供应商决定） | — |
+
+合成出的条目使用保留键 `__kimi_env__`（供应商）和 `__kimi_env_model__`（模型别名）。当设置了 `KIMI_MODEL_NAME` 但缺少必填变量或变量取值非法时，启动会以清晰的错误信息失败。
+
+```sh
+export KIMI_MODEL_NAME="kimi-for-coding"
+export KIMI_MODEL_BASE_URL="https://api-staff.msh.team/v1"
+export KIMI_MODEL_API_KEY="$MOONSHOT_STAFF_KEY"
+export KIMI_MODEL_MAX_CONTEXT_SIZE="262144"
+export KIMI_MODEL_CAPABILITIES="image_in,thinking"
+kimi
+```
+
 ## 运行时开关
 
 | 环境变量 | 用途 | 合法值 / 默认值 |

docs/zh/configuration/overrides.md

@@ -20,7 +20,7 @@ Kimi Code CLI 的运行参数来自用户配置文件、命令行选项，以及
 少数环境变量会明确覆盖配置文件中的相关字段，例如 `KIMI_CODE_BACKGROUND_KEEP_ALIVE_ON_EXIT` 的优先级高于 `[background].keep_alive_on_exit`。这类例外会在 [环境变量](./env-vars.md) 与对应的 [配置文件](./config-files.md) 字段说明里标出。
 
 ::: warning 注意
-普通运行参数**不会**从 shell 环境变量取后备值。例如供应商 `api_key` / `base_url` 只读取 `config.toml` 中的字段（包括 `[providers.<name>.env]` 子表），不会回退到 `export KIMI_API_KEY` 这类终端变量；详见下文 [供应商凭证](#供应商凭证)。
+普通运行参数**不会**从 shell 环境变量取后备值。例如供应商 `api_key` / `base_url` 只读取 `config.toml` 中的字段（包括 `[providers.<name>.env]` 子表），不会回退到 `export KIMI_API_KEY` 这类终端变量；详见下文 [供应商凭证](#供应商凭证)。唯一的例外是显式的 `KIMI_MODEL_*` 通道，它会从 shell 合成出一个模型（及其凭证）；详见 [用环境变量定义模型](./env-vars.md#用环境变量定义模型-kimi-model)。
 :::
 
 Kimi Code CLI 目前只读取一份用户级配置文件，没有项目级（仓库内）配置文件机制。如果需要在不同项目之间隔离配置，可以通过 `KIMI_CODE_HOME` 指向不同的数据目录（详见下文 [典型场景](#典型场景)），或在启动时用 CLI 选项临时覆盖具体字段。
@@ -31,7 +31,7 @@ Kimi Code CLI 目前只读取一份用户级配置文件，没有项目级（仓
 
 ## 供应商凭证
 
-供应商凭证（`api_key`、`base_url`）的解析有自己的规则：Kimi Code CLI 只从 `config.toml` 中读取供应商字段，**不会**从 shell 环境变量取后备值。仅在终端里 `export KIMI_API_KEY` 不会让某个 `[providers.<name>]` 自动获得凭证，必须显式写到配置文件里。
+供应商凭证（`api_key`、`base_url`）的解析有自己的规则：Kimi Code CLI 只从 `config.toml` 中读取供应商字段，**不会**从 shell 环境变量取后备值。仅在终端里 `export KIMI_API_KEY` 不会让某个 `[providers.<name>]` 自动获得凭证，必须显式写到配置文件里。唯一的例外是显式的 `KIMI_MODEL_*` 通道，它会从 shell 合成出一个模型（及其凭证）；详见 [用环境变量定义模型](./env-vars.md#用环境变量定义模型-kimi-model)。
 
 对单个供应商而言，凭证按以下顺序解析：