diff --git a/docs/en/configuration/config-files.md b/docs/en/configuration/config-files.md index 28957a03b1b..15119726b21 100644 --- a/docs/en/configuration/config-files.md +++ b/docs/en/configuration/config-files.md @@ -1,12 +1,10 @@ # Configuration files -Kimi Code CLI writes all long-term preferences — which model to use, which API key to fill in, how many steps an Agent can run per turn — into TOML (a plain-text configuration format with a clear structure) files. Change them once and they take effect on every startup. Agent and runtime settings live in `config.toml`; terminal-UI and client preferences (theme, editor, notifications, auto-update) live in a companion `tui.toml`. - -Default location: `~/.kimi-code/config.toml`, created automatically on first run. +Kimi Code CLI writes all long-term preferences into TOML (plain-text configuration) files under `~/.kimi-code/`: runtime settings live in `config.toml`, and terminal-UI preferences live in a companion `tui.toml`. ## Config file location -The CLI reads configuration from `~/.kimi-code/config.toml`. To relocate the data directory, override it with the `KIMI_CODE_HOME` environment variable: +The CLI reads configuration from `~/.kimi-code/config.toml`, created automatically on first run. To relocate the data directory, override it with the `KIMI_CODE_HOME` environment variable: ```sh export KIMI_CODE_HOME=/path/to/kimi-home @@ -15,7 +13,7 @@ export KIMI_CODE_HOME=/path/to/kimi-home The config file path then becomes `$KIMI_CODE_HOME/config.toml`. Regardless of where the directory lives, the file name is always `config.toml`. ::: tip -TOML field names always use snake_case, for example `default_model` and `max_context_size`. If a key contains `.`, you must quote it — for example `[models."gpt-4.1"]` — otherwise TOML treats `.` as a nested table separator. +TOML field names always use snake_case, for example `default_model` and `max_context_size`. If a key contains `.`, you must quote it (for example `[models."gpt-4.1"]`); otherwise TOML treats `.` as a nested table separator. ::: ## Complete example @@ -98,38 +96,36 @@ Fields in the config file fall into two categories: **top-level scalars** that d | Field | Type | Default | Description | | --- | --- | --- | --- | | `default_model` | `string` | — | Default model alias; must be defined in `models` | -| `default_permission_mode` | `string` | `manual` | Default permission mode for new sessions; one of `manual` (Always Ask: auto-read only; everything else needs your approval first), `yolo` (Ask When Needed: routine edits and commands run automatically; risky actions, questions, and plans still ask), or `auto` (Never Ask: never interrupts you; everything runs and is decided automatically, but dangerous commands are always blocked) | -| `default_plan_mode` | `boolean` | `false` | Whether new sessions start in Plan mode (produce a plan before executing) by default | +| `default_permission_mode` | `string` | `manual` | Default permission mode for new sessions: `manual`, `yolo`, or `auto`. See [the three permission modes](../guides/interaction.md#the-three-permission-modes) | +| `default_plan_mode` | `boolean` | `false` | Whether new sessions start in [Plan mode](../guides/interaction.md#plan-mode) by default | | `merge_all_available_skills` | `boolean` | `true` | Whether to merge Agent Skills from all available directories | | `extra_skill_dirs` | `array` | — | Extra skill search directories, layered on top of the default directories | | `extra_agent_dirs` | `array` | — | Extra custom agent search directories, layered on top of the default directories | -| `builtin_product_skills` | `boolean` | `true` | Whether the built-in skills that document Kimi Code itself are offered to the model: `update-config`, `custom-theme`, `mcp-config`, `check-kimi-code-docs`, and `import-from-cc-codex`. Turning them off trims their names and descriptions from the system prompt, at the cost of the guided flows for those tasks. Read by the default `agent-core-v2` engine; ignored when `KIMI_CODE_LEGACY_FLAG=1` selects the legacy engine | +| `builtin_product_skills` | `boolean` | `true` | Whether the built-in skills that document Kimi Code itself are offered to the model | | `telemetry` | `boolean` | `true` | Whether anonymous telemetry is enabled; disabled only when explicitly set to `false` | -| `providers` | `table` | `{}` | API provider table → [`providers`](#providers) | -| `models` | `table` | — | Model alias table → [`models`](#models) | -| `thinking` | `table` | — | Default parameters for Thinking mode → [`thinking`](#thinking) | -| `loop_control` | `table` | — | Agent loop control parameters → [`loop_control`](#loop-control) | -| `background` | `table` | — | Background task runtime parameters → [`background`](#background) | -| `tools` | `table` | — | Global tool switch → [`tools`](#tools) | -| `image` | `table` | — | Image compression parameters → [`image`](#image) | -| `services` | `table` | — | Built-in external service configuration → [`services`](#services) | -| `permission` | `table` | — | Initial permission rules → [`permission`](#permission) | -| `hooks` | `array` | — | Lifecycle hooks; see [Hooks](../customization/hooks.md) | -| `identity` | `table` | — | Custom agent identity → [`identity`](#identity) | - -The following sections cover each of the nested tables in turn: `providers`, `models`, `thinking`, `loop_control`, `background`, `tools`, `image`, `services`, and `permission`. +| [`providers`](#providers) | `table` | `{}` | API provider table | +| [`models`](#models) | `table` | — | Model alias table | +| [`thinking`](#thinking) | `table` | — | Default parameters for Thinking mode | +| [`loop_control`](#loop_control) | `table` | — | Agent loop control parameters | +| [`background`](#background) | `table` | — | Background task runtime parameters | +| [`tools`](#tools) | `table` | — | Global tool switch | +| [`image`](#image) | `table` | — | Image compression parameters | +| [`services`](#services) | `table` | — | Built-in external service configuration | +| [`permission`](#permission) | `table` | — | Initial permission rules | +| [`hooks`](../customization/hooks.md) | `array
` | — | Lifecycle hooks | +| [`identity`](#identity) | `table` | — | Custom agent identity | ## `providers` -Each entry in the `providers` table defines an API provider, keyed by a unique name. The CLI reads credentials only from here — it does **not** fall back to shell environment variables automatically. Running `export KIMI_API_KEY` in the terminal does not give any provider its key; you must write it explicitly in the config file (see [Config overrides](./overrides.md#provider-credentials)). +Each entry in the `providers` table defines an API provider, keyed by a unique name. The CLI reads credentials only from here. It does **not** fall back to shell environment variables automatically: running `export KIMI_API_KEY` in the terminal does not give any provider its key; you must write it explicitly in the config file (see [Config overrides](./overrides.md#provider-credentials)). | Field | Type | Required | Description | | --- | --- | --- | --- | | `type` | `string` | Yes | Provider type: `kimi`, `anthropic`, `openai`, `openai_responses`, `google-genai`, `vertexai` | | `api_key` | `string` | No | API key, written in plain text in the config file | | `base_url` | `string` | No | API base URL | -| `oauth` | `table` | No | OAuth credential reference (`storage` and `key` fields); injected automatically by the login flow — normally no need to write this by hand | -| `env` | `table` | No | Fallback source for provider credentials; see below | +| `oauth` | `table` | No | OAuth credential reference (`storage` and `key` fields); injected automatically by the login flow, so you normally never write this by hand | +| `env` | `table` | No | Fallback source for provider credentials; see the `env` sub-table | | `custom_headers` | `table` | No | Custom HTTP headers attached to each request | **`env` sub-table**: You can write provider-conventional key names (such as `KIMI_API_KEY`) inside `[providers..env]` as a fallback source for `api_key` / `base_url`. This sub-table is **read only from the config file** and does not modify the shell environment: @@ -151,16 +147,16 @@ Each entry in the `models` table defines a model alias (the name used in `defaul | `provider` | `string` | Yes | Name of the provider to use; must be defined in `providers` | | `model` | `string` | Yes | Model identifier sent to the server when calling the API | | `max_context_size` | `integer` | Yes | Maximum context length in tokens; must be at least 1 | -| `max_input_size` | `integer` | No | Declared per-request input limit when it sits below the total window (e.g. gpt-5: 400k window, 272k input). Compaction, context-overflow checks, and usage ratios prefer it; completion budgeting keeps the total window. Resolution clamps it to `max_context_size` | -| `max_output_size` | `integer` | No | Per-request output token cap (maps to `max_tokens`). Currently only the `anthropic` provider honors it. When set for a Claude model, this explicit value overrides the built-in server-side maximum | -| `capabilities` | `array` | No | Capability tags to add explicitly: `thinking`, `always_thinking`, `image_in`, `video_in`, `audio_in`, `tool_use`. Unioned with the capabilities auto-detected by the provider — entries can only be added, never removed | -| `support_efforts` | `array` | No | Thinking effort levels the model accepts. For `kimi`, selecting another value at runtime fails; when model resolution carries an unsupported configured or previous value, the session falls back to the target model's `default_effort` and reports that effective value to the UI. A Thinking-capable Kimi model without this field uses boolean `on` / `off`. Other providers pass concrete values unchanged when their protocol has a native effort field; protocols that expose only levels or token budgets perform the required format conversion. Managed and open-platform refreshes may rewrite this field; to pin it manually, set `[models."".overrides] support_efforts` instead | -| `default_effort` | `string` | No | Default thinking effort for the model. Managed and open-platform refreshes may rewrite this field; to pin it manually, set `[models."".overrides] default_effort` instead | -| `off_effort` | `string` | No | Effort value sent on the wire to disable thinking (e.g. `none` for xai grok). Only meaningful for models that declare such an encoding (catalog imports set it): turning thinking Off then sends this value instead of omitting the effort field — the only way to actually stop reasoning on models that reason by default | -| `base_url` | `string` | No | Per-model endpoint override (written by catalog imports for gateway models served away from the provider default). Resolution prefers it over the provider's `base_url`; only takes effect together with `protocol` | +| `max_input_size` | `integer` | No | Declared per-request input limit; compaction, context-overflow checks, and usage ratios prefer it, completion budgeting keeps the total window | +| `max_output_size` | `integer` | No | Per-request output token cap (maps to `max_tokens`); currently only the `anthropic` provider reads it | +| `capabilities` | `array` | No | Capability tags added explicitly: `thinking`, `always_thinking`, `image_in`, `video_in`, `audio_in`, `tool_use`; only ever added, never removed | +| `support_efforts` | `array` | No | Thinking effort levels the model accepts; unsupported values fall back to `default_effort`, out-of-list values fail; managed refreshes may rewrite it (pin via overrides) | +| `default_effort` | `string` | No | Default thinking effort for the model; managed and open-platform refreshes may rewrite it. Pin via [model overrides](#model-overrides) | +| `off_effort` | `string` | No | Effort value sent on the wire to disable thinking (e.g. `none` for xai grok); the only way to actually stop reasoning on models that reason by default | +| `base_url` | `string` | No | Per-model endpoint override (written by catalog imports); takes precedence over the provider's `base_url`, only effective together with `protocol` | | `display_name` | `string` | No | Name shown in the UI; falls back to `model` when unset | -| `reasoning_key` | `string` | No | `openai` provider only. Override the field name used for reasoning content when the gateway returns it under a non-standard name; by default `reasoning_content`, `reasoning_details`, and `reasoning` are auto-detected | -| `adaptive_thinking` | `boolean` | No | `anthropic` provider only. Force adaptive thinking on or off, overriding the version inference based on the model name. Omit to infer automatically (Claude ≥ 4.6 uses adaptive) | +| `reasoning_key` | `string` | No | `openai` provider only; set when the gateway returns reasoning content under a non-standard field name (`reasoning_content` and friends are auto-detected) | +| `adaptive_thinking` | `boolean` | No | `anthropic` provider only; force adaptive thinking on or off, omit to infer from the model name (Claude ≥ 4.6 uses adaptive) | When an alias contains `.`, use a quoted key: @@ -188,19 +184,17 @@ display_name = "Kimi for Coding (custom)" `[models."".overrides]` accepts ordinary model fields such as `max_context_size`, `max_input_size`, `max_output_size`, `capabilities`, `display_name`, `reasoning_key`, `adaptive_thinking`, `support_efforts`, `default_effort`, and `off_effort`. It does not accept identity / routing fields: `provider`, `model`, `protocol`, `beta_api`, and `base_url`. -You can also switch models temporarily without touching the config file — by setting `KIMI_MODEL_*` environment variables, the CLI synthesizes a temporary provider in memory that does not persist after restart. See [Define a model from environment variables](./env-vars.md#define-a-model-from-environment-variables-kimi-model). +You can also switch models temporarily without touching the config file: setting `KIMI_MODEL_*` environment variables synthesizes a temporary provider in memory that does not persist after restart. See [Define a model from environment variables](./env-vars.md#define-a-model-from-environment-variables-kimi_model_). ## `secondary_model` -Subagents inherit the model the main agent is running by default. The `[secondary_model]` section makes this configurable: it offers subagents a pool of candidate models plus a default binding — typically a cheaper model for subtasks that do not need the main model's capability. +Subagents inherit the model the main agent is running by default. The `[secondary_model]` section makes this configurable: it offers subagents a pool of candidate models plus a default binding. Typically that is a cheaper model for subtasks that do not need the main model's capability. ### Subagent model pool -Configured values take effect in every launch mode, including the interactive TUI. - -The pool is enabled by default in every launch mode, including the interactive TUI. To disable it, set `KIMI_CODE_EXPERIMENTAL_SECONDARY_MODEL=0` (or `secondary-model = false` under `[experimental]` in `config.toml`); while disabled, the pool keys stay inert: subagents inherit the caller's model and session startup skips the pool validation. +The pool is enabled by default and needs no configuration. Set `KIMI_CODE_EXPERIMENTAL_SECONDARY_MODEL=0` to disable it; while disabled, the pool keys stay inert, subagents inherit the caller's model, and session startup skips the pool validation. -The minimal configuration is one line — a lone `default_model` is a pool with a single entry: +The minimal configuration is one line. A lone `default_model` is a pool with a single entry: ```toml [secondary_model] @@ -210,7 +204,7 @@ default_model = "kimi-code/kimi-for-coding-highspeed" | Field | Type | Default | Description | | --- | --- | --- | --- | | `default_model` | `string` | — | The default model for subagents | -| `models` | `table` | — | Subagent model pool. Each key is the alias of a configured [`[models]`](#models) entry; each value is the selection hint shown to the main agent | +| `models` | `table` | — | Subagent model pool; each key is the alias of a configured [`[models]`](#models) entry, each value a selection hint | | `force` | `boolean` | `false` | Pin every subagent to `default_model`, taking the choice away from the main agent | | `default_effort` | `string` | — | The thinking effort every spawned subagent binds with; outranks the bound model entry's own `default_effort` | @@ -218,15 +212,15 @@ Constraints between the fields: - `default_model`: required when a `models` table is configured, and must be one of its keys. - `models`: values may be Chinese or English; an empty string lists the alias with no hint. -- `force`: requires `default_model` and cannot be combined with a `models` table — the table exists to offer a choice, and force removes it. +- `force`: requires `default_model` and cannot be combined with a `models` table: the table exists to offer a choice, and force removes it. - `default_effort` is section-wide: every spawn binds it regardless of the chosen pool entry (or the forced model). For per-entry efforts, leave it unset and use model variants (see below). - `primary` is a reserved alias (see below) and cannot be a pool key. -Pool aliases reference the current `[models]` table: if a provider is later deleted or logged out, or its refreshed model list no longer contains an alias, session startup fails with a configuration error naming the broken alias — fix or remove the entry to recover. The `[secondary_model]` section itself is never rewritten automatically. +Pool aliases reference the current `[models]` table: if a provider is later deleted or logged out, or its refreshed model list no longer contains an alias, session startup fails with a configuration error naming the broken alias. Fix or remove the entry to recover. The `[secondary_model]` section itself is never rewritten automatically. -In the interactive TUI, the [`/secondary-model`](../reference/slash-commands.md) command (alias `/subagent-model`) opens a model selector: the choice is written to `default_model` (when a models table exists and the picked alias is not in it, an entry with an empty description is added), and newly spawned subagents pick up the new default immediately — no session restart needed. +In the interactive TUI, the [`/secondary-model`](../reference/slash-commands.md) command (alias `/subagent-model`) opens a model selector: the choice is written to `default_model` (when a models table exists and the picked alias is not in it, an entry with an empty description is added), and newly spawned subagents pick up the new default immediately, no session restart needed. -A configured pool — an explicit `models` table or a lone `default_model` — enables model selection: the `Agent` / `AgentSwarm` tools gain a `model` parameter, and the tool description lists the pool (the default marked `[default]`) so the main agent can choose per spawn. Pool keys can only reference configured [`[models]`](#models) entries — the `kimi-code/*` aliases below are provisioned by `/login`: +A configured pool (an explicit `models` table or a lone `default_model`) enables model selection: the `Agent` / `AgentSwarm` tools gain a `model` parameter, and the tool description lists the pool (the default marked `[default]`) so the main agent can choose per spawn. Pool keys can only reference configured [`[models]`](#models) entries. The `kimi-code/*` aliases below are provisioned by `/login`: ```toml [secondary_model] @@ -244,7 +238,7 @@ A spawn resolves the subagent's model in this order: Rules for the `model` parameter: -- It accepts any pool alias, or `"primary"` — the model the caller itself is running, always valid even when not in the pool. +- It accepts any pool alias, or `"primary"`, the model the caller itself is running; always valid even when not in the pool. - When neither `default_model` nor `models` is configured, the parameter is not advertised and subagents inherit the caller's model. - Binding a pool alias does not inherit the caller's thinking effort. The section's `default_effort` wins when set. Otherwise, `[thinking].enabled = false` keeps Thinking off; when Thinking is enabled, resolution continues with the bound model entry's `default_effort`, the global `[thinking].effort`, then the middle of the bound model's `support_efforts`. - `"primary"` inherits both the model and the effort level from the caller. @@ -290,7 +284,7 @@ k3-max = "The same model at max thinking effort. Good for the hardest subtasks." Two prerequisites: - The underlying model must declare `support_efforts` (under `managed:kimi-code` only the k3 family currently declares effort levels). -- The variant is a standalone entry and does not inherit fields from the entry it points at — copy `capabilities`, `support_efforts`, and the other metadata over in full, otherwise `default_effort` has no effect (it must be a member of `support_efforts`). +- The variant is a standalone entry and does not inherit fields from the entry it points at: copy `capabilities`, `support_efforts`, and the other metadata over in full, otherwise `default_effort` has no effect (it must be a member of `support_efforts`). Note the asymmetry between the main agent and pool-bound subagents: for the main agent, a configured global `[thinking].effort` overrides the variant's `default_effort`; for subagents the variant's `default_effort` wins over the global value, and only `[secondary_model].default_effort` outranks it. Value and fallback rules follow the [`[models]` entry's `default_effort`](#models). @@ -308,10 +302,10 @@ Configuration errors fail loudly instead of falling back silently. Session creat | Field | Type | Default | Description | | --- | --- | --- | --- | | `enabled` | `boolean` | `true` | Whether Thinking is enabled by default for new sessions; set to `false` to force Thinking off | -| `effort` | `string` | — | Thinking effort level (for example `low`, `medium`, `high`, `xhigh`, `max`). Non-Kimi providers do not remap concrete effort values when the upstream protocol accepts them; if the provider rejects the value, choose one that the model supports. Protocols that expose only levels or token budgets still require format conversion. Kimi models with `support_efforts` fall back to their model default when this configured value is not listed; Kimi models without that list treat every enabled value as boolean `on` | -| `keep` | `string` | `"all"` | Preserved Thinking passthrough. On `kimi` it is sent as `thinking.keep`; on `anthropic` (Claude and Kimi's Anthropic-compatible mode) it is sent as a `context_management` `clear_thinking_20251015` edit (enabling keep routes Anthropic requests to the beta Messages API; an off-value disables keep and returns to the standard endpoint). `"all"` preserves prior turns' reasoning (`reasoning_content` / Anthropic thinking blocks); set to an off-value (`false`/`0`/`no`/`off`/`none`/`null`) to disable. Overridden by `KIMI_MODEL_THINKING_KEEP`; only injected while Thinking is on | +| `effort` | `string` | — | Thinking effort: `low` / `medium` / `high` / `xhigh` / `max`; falls back to the model default when not in its supported list | +| `keep` | `string` | `"all"` | Preserved Thinking passthrough: `kimi` sends it as `thinking.keep`, `anthropic` as a `clear_thinking_20251015` edit (routes to the beta Messages API). An off-value disables it; overridden by `KIMI_MODEL_THINKING_KEEP`; injected only while Thinking is on | -### Deprecated fields +
Deprecated fields | Field | Deprecated in | Description | | --- | --- | --- | @@ -320,6 +314,8 @@ Configuration errors fail loudly instead of falling back silently. Session creat | `loop_control.max_retries_per_step` | 0.32.0 | Replaced by `loop_control.max_attempts_per_step` (the value was always a total-attempt limit, including the first try). The old key is ignored and reports a warning on startup; rename it in `config.toml`. | | `loop_control.max_steps_per_run` | 0.32.0 | Replaced by `loop_control.max_steps_per_turn`. The old key is ignored and reports a warning on startup; rename it in `config.toml`. | +
+ ## `loop_control` `loop_control` governs the step count limit, the per-step attempt limit, and the threshold that triggers automatic context compaction in the Agent execution loop. @@ -332,15 +328,15 @@ Configuration errors fail loudly instead of falling back silently. Session creat `max_steps_per_turn` can be overridden by the `KIMI_LOOP_MAX_STEPS_PER_TURN` environment variable, and `max_attempts_per_step` by `KIMI_LOOP_MAX_ATTEMPTS_PER_STEP`; both take higher priority than the config file. The former `KIMI_LOOP_MAX_RETRIES_PER_STEP` variable is deprecated but still honored (with a startup warning) when the new one is unset. -Retries only apply to transient failures — connection errors, timeouts, HTTP 429 rate limits, and 5xx server errors. A 429 caused by an exhausted quota or insufficient account balance is not retried and fails immediately, since it cannot succeed until the account is recharged. +Retries only apply to transient failures: connection errors, timeouts, HTTP 429 rate limits, and 5xx server errors. A 429 caused by an exhausted quota or insufficient account balance is not retried and fails immediately, since it cannot succeed until the account is recharged. ## `token_counting` -`token_counting` selects which context token count is reported externally — the value behind the context-size display. Internal logic (automatic compaction triggers, budgets, and overflow backoff) always uses both provider-reported usage and estimates, regardless of this setting. +`token_counting` selects which context token count is reported externally, the value behind the context-size display. Internal logic (automatic compaction triggers, budgets, and overflow backoff) always uses both provider-reported usage and estimates, regardless of this setting. | Field | Type | Default | Description | | --- | --- | --- | --- | -| `strategy` | `"measured+estimated" \| "measured" \| "estimated"` | `"measured+estimated"` | `measured+estimated` reports the live size — the provider-reported usage of each exchange plus an estimate of the not-yet-measured tail — floored by the last measured total; `measured` reports provider usage alone, so the display only moves when an exchange completes; `estimated` reports a pure estimate with provider usage ignored — the fallback for providers that do not report usage or report it unreliably | +| `strategy` | `"measured+estimated" \| "measured" \| "estimated"` | `"measured+estimated"` | `measured+estimated` combines measured usage with an estimate of the unmeasured tail; `measured` reports provider usage alone, updated when a request completes; `estimated` is a pure estimate, for providers that do not report usage | `strategy` can be overridden by the `KIMI_TOKEN_COUNTING_STRATEGY` environment variable, which takes higher priority than `config.toml`. @@ -351,13 +347,13 @@ Retries only apply to transient failures — connection errors, timeouts, HTTP 4 | Field | Type | Default | Description | | --- | --- | --- | --- | | `max_running_tasks` | `integer` | — | Maximum number of background tasks running concurrently | -| `keep_alive_on_exit` | `boolean` | `false` | Whether to keep still-running background tasks when the session closes. By default, Kimi Code requests that all background tasks stop before the process exits; set this to `true` only when you want tasks to outlive the session. In print mode (`kimi -p`), this is only a legacy fallback used when `print_background_mode` is unset: `true` is equivalent to `print_background_mode = "drain"` | -| `kill_grace_period_ms` | `integer` | `5000` | Grace period in milliseconds after session close, a manual stop, or a task timeout requests graceful termination. If a task is still running after this period, Kimi Code attempts to force-stop it | -| `bash_auto_background_on_timeout` | `boolean` | `true` | When a foreground `Bash` command hits its timeout, move it to a background task instead of killing it — the agent is notified when it completes, and the backgrounded command is bounded by the `bash_task_timeout_s` default background timeout. Set to `false` to kill timed-out foreground commands instead | -| `bash_task_timeout_s` | `integer` | `600` | Default timeout (seconds) for background `Bash` tasks when the call omits `timeout`; also used to re-arm foreground commands moved to the background on timeout. `0` means no timeout — the task runs until it exits or the model stops it. Explicit per-call `timeout` values are unaffected. In print mode (`kimi -p`) the default is `0` unless explicitly set | -| `print_background_mode` | `"exit" \| "drain" \| "steer"` | `"steer"` | Print mode (`kimi -p`) only. Governs how pending background tasks are handled once the main agent's turn ends: `"exit"` exits immediately; `"drain"` waits for every background task to reach a terminal state before exiting (results are not fed back to the main agent); `"steer"` stays alive so a completing background task — like a background subagent — injects a synthetic user message that steers the main agent into a new turn, looping until a turn ends with no pending background tasks or a limit is hit. Takes precedence over the `keep_alive_on_exit` print fallback | -| `print_wait_ceiling_s` | `integer` | `2147483` | In print mode (`kimi -p`), the wall-clock ceiling (seconds) for the wait/steer loop when `print_background_mode` is `"drain"` or `"steer"` (the default is ~24.8 days — effectively unbounded). Has no effect outside print mode or when it is `"exit"` | -| `print_max_turns` | `integer` | `100000` | In print mode (`kimi -p`) with `print_background_mode = "steer"`, the maximum number of new turns that may be triggered by background-task completions, to keep the steering loop bounded (the default is effectively unbounded) | +| `keep_alive_on_exit` | `boolean` | `false` | Whether to keep still-running background tasks when the session closes; in print mode only a fallback when `print_background_mode` is unset (`true` = `drain`) | +| `kill_grace_period_ms` | `integer` | `5000` | Grace period in milliseconds after a task is asked to terminate; still-running tasks are force-stopped when it elapses | +| `bash_auto_background_on_timeout` | `boolean` | `true` | Move a foreground `Bash` command to a background task on timeout instead of killing it; set to `false` to kill timed-out foreground commands instead | +| `bash_task_timeout_s` | `integer` | `600` | Default timeout (seconds) for background `Bash` tasks when the call omits `timeout`; `0` means no timeout. Explicit per-call `timeout` values are unaffected; print mode defaults to `0` | +| `print_background_mode` | `"exit" \| "drain" \| "steer"` | `"steer"` | Print mode only: how pending background tasks are handled when the main agent's turn ends; `"exit"` exits immediately, `"drain"` waits for terminal states without feeding results back, `"steer"` injects completions as synthetic user messages steering new turns until none are pending | +| `print_wait_ceiling_s` | `integer` | `2147483` | Wall-clock ceiling (seconds) for the print-mode wait/steer loop; no effect outside print mode or with `"exit"` | +| `print_max_turns` | `integer` | `100000` | Maximum number of new turns triggered by background-task completions in `"steer"` mode; keeps the steering loop bounded | `keep_alive_on_exit` can be overridden by the `KIMI_CODE_BACKGROUND_KEEP_ALIVE_ON_EXIT` environment variable, and `max_running_tasks` by `KIMI_CODE_BACKGROUND_MAX_RUNNING_TASKS`; both take higher priority than `config.toml`. @@ -369,7 +365,7 @@ In print mode (`kimi -p ""`), Kimi Code stays alive after the main agent | Field | Type | Default | Description | | --- | --- | --- | --- | -| `timeout_ms` | `integer` | `7200000` (2 hours) | Maximum wall-clock time (milliseconds) a single `Agent` subagent is allowed to run before it is settled as `timed_out`. `0` means no timeout — the subagent runs until it finishes or the model stops it. This is the background-task manager's per-task timeout for each subagent task, so it applies to both foreground and background subagents. In print mode (`kimi -p`) the default is `0` unless explicitly set. Note: any value above `2147483647` (about 24.8 days) is clamped to roughly 24.8 days by the runtime | +| `timeout_ms` | `integer` | `7200000` (2 hours) | Maximum wall-clock time (milliseconds) a single `Agent` subagent may run before it is settled as `timed_out`; `0` means no timeout | `timeout_ms` can be overridden by the `KIMI_SUBAGENT_TIMEOUT_MS` environment variable, which takes higher priority than `config.toml`. @@ -379,7 +375,7 @@ In print mode (`kimi -p ""`), Kimi Code stays alive after the main agent | Field | Type | Default | Description | | --- | --- | --- | --- | -| `timeout_ms` | `integer` | `7200000` (2 hours) | Maximum wall-clock time (milliseconds) a single `AgentSwarm` subagent is allowed to run. On timeout that subagent is aborted and marked as failed in the aggregated report (`Subagent timed out.`); the other subagents are unaffected. `0` means no timeout — the subagent runs until it finishes or the model stops it. In print mode (`kimi -p`) the default is `0` unless explicitly set. Note: any value above `2147483647` (about 24.8 days) is clamped to roughly 24.8 days by the runtime | +| `timeout_ms` | `integer` | `7200000` (2 hours) | Maximum wall-clock time (milliseconds) a single `AgentSwarm` subagent may run; on timeout it is aborted and the aggregated report marks `Subagent timed out.`; `0` means no timeout | `timeout_ms` can be overridden by the `KIMI_CODE_SWARM_TIMEOUT_MS` environment variable, which takes higher priority than `config.toml`. @@ -387,8 +383,8 @@ In print mode (`kimi -p ""`), Kimi Code stays alive after the main agent | Field | Type | Default | Description | | --- | --- | --- | --- | -| `startup_timeout_ms` | `integer` | `30000` (30 seconds) | Global default connection (startup + tool discovery) timeout in milliseconds for all MCP servers. Accepts `1`–`2147483647`. A per-server `startupTimeoutMs` in `mcp.json` always wins over this section and the environment variable; when neither is set, the default applies | -| `tool_timeout_ms` | `integer` | `60000` (60 seconds) | Global default single tool-call timeout in milliseconds for all MCP servers. Accepts `1`–`2147483647`. A per-server `toolTimeoutMs` in `mcp.json` always wins over this section and the environment variable; when neither is set, the client built-in default applies | +| `startup_timeout_ms` | `integer` | `30000` (30 seconds) | Global default connection (startup + tool discovery) timeout in milliseconds for all MCP servers; a per-server `startupTimeoutMs` in `mcp.json` wins | +| `tool_timeout_ms` | `integer` | `60000` (60 seconds) | Global default single tool-call timeout in milliseconds for all MCP servers; a per-server `toolTimeoutMs` in `mcp.json` wins | `startup_timeout_ms` and `tool_timeout_ms` can be overridden by the `KIMI_MCP_STARTUP_TIMEOUT_MS` and `KIMI_MCP_TOOL_TIMEOUT_MS` environment variables respectively, which take higher priority than `config.toml`. See [MCP](../customization/mcp.md) for the full MCP server configuration. @@ -399,7 +395,7 @@ Customizes how the agent identifies itself. Leave it unset and nothing changes. | Field | Type | Default | Description | | --- | --- | --- | --- | | `name` | `string` | — | Display name the agent calls itself in the system prompt (fills the `${product_name}` slot, including in your own `SYSTEM.md` and agent files) | -| `slug` | `string` | derived from `name` | Machine identifier used in protocol fields: the `User-Agent` product token sent to third-party providers, and the client name announced to MCP servers. Derived from `name` when omitted: lowercased, with every run of non-alphanumeric characters folded to `-` | +| `slug` | `string` | derived from `name` | Machine identifier in protocol fields (`User-Agent` product token, MCP client name); derived from `name` when omitted: lowercased, non-alphanumeric runs folded to `-` | ```toml [identity] @@ -407,11 +403,11 @@ name = "Acme Dev Agent" slug = "acme-dev" # optional ``` -Both fields can be set through the `KIMI_CODE_IDENTITY_NAME` and `KIMI_CODE_IDENTITY_SLUG` environment variables, which take higher priority than `config.toml` and are never written back to it — convenient for containers and CI, where writing a config file is awkward. +Both fields can be set through the `KIMI_CODE_IDENTITY_NAME` and `KIMI_CODE_IDENTITY_SLUG` environment variables, which take higher priority than `config.toml` and are never written back to it, making them convenient for containers and CI, where writing a config file is awkward. A name that contains no ASCII letters or digits (for example a purely Chinese name) leaves nothing to derive a slug from and falls back to `agent`; write `slug` explicitly if you need a specific protocol token. -The identity is resolved once at startup and holds for the life of the process — it is announced to MCP servers and providers when connections are made, so it cannot change midway. Edits to this section take effect on the next start, for new sessions: a resumed session keeps the system prompt it was recorded with, since its past turns already speak under that identity. Likewise, an MCP OAuth authorization keeps the client registration it was granted under; reset that server's authentication to register under the new identity. +The identity is resolved once at startup and holds for the life of the process: it is announced to MCP servers and providers when connections are made, so it cannot change midway. Edits to this section take effect on the next start, for new sessions: a resumed session keeps the system prompt it was recorded with, since its past turns already speak under that identity. Likewise, an MCP OAuth authorization keeps the client registration it was granted under; reset that server's authentication to register under the new identity. This section is read by the default `agent-core-v2` engine. It is ignored by the legacy `kimi` / `kimi -p` path selected with `KIMI_CODE_LEGACY_FLAG=1`; `kimi web` always uses `agent-core-v2`. @@ -424,7 +420,7 @@ This section is read by the default `agent-core-v2` engine. It is ignored by the | `enabled` | `array` | — | Global allowlist: when non-empty, only the listed tools are available; omitting the field or setting an empty array imposes no constraint | | `disabled` | `array` | — | Global denylist, applied after `enabled` | -Name matching follows the same rules as the same-named fields in an agent file: built-in tools match by exact name (such as `Read`), and MCP tools match with globs (such as `mcp__github__*`). Three entry shapes never match anything and are reported with a warning: a wildcard outside an `mcp__` pattern (`enabled = ["*"]` disables every tool, `disabled = ["*"]` disables none), an `mcp__` literal missing the tool segment (`mcp__github` — use `mcp__github__*` for a whole server), and a name no registered or built-in tool has (matching is case-sensitive). +Name matching follows the same rules as the same-named fields in an agent file: built-in tools match by exact name (such as `Read`), and MCP tools match with globs (such as `mcp__github__*`). Three entry shapes never match anything and are reported with a warning: a wildcard outside an `mcp__` pattern (`enabled = ["*"]` disables every tool, `disabled = ["*"]` disables none), an `mcp__` literal missing the tool segment (`mcp__github`; use `mcp__github__*` for a whole server), and a name no registered or built-in tool has (matching is case-sensitive). ```toml [tools] @@ -441,8 +437,8 @@ Like the `tools` / `disallowedTools` fields of an agent file, this section shape | Field | Type | Default | Description | | --- | --- | --- | --- | -| `max_edge_px` | `integer` | `2000` | Longest-edge ceiling in pixels. Larger images are scaled down proportionally to fit; raising it preserves more detail at the cost of larger request bodies | -| `read_byte_budget` | `integer` | `262144` (256 KB) | Per-image byte budget for images the model reads for itself (`ReadMediaFile` default reads). It bounds the accumulated request-body size when the model keeps screenshotting and reading images; fine detail stays reachable through the `region` parameter, which reads a crop back at full fidelity (`region` and `full_resolution` are not subject to this budget) | +| `max_edge_px` | `integer` | `2000` | Longest-edge ceiling in pixels; larger images scale down proportionally. Raising it preserves more detail at the cost of larger request bodies | +| `read_byte_budget` | `integer` | `262144` (256 KB) | Per-image byte budget for images the model reads for itself (`ReadMediaFile` default reads); `region` and `full_resolution` read-backs are exempt | `max_edge_px` can be overridden by the `KIMI_IMAGE_MAX_EDGE_PX` environment variable and `read_byte_budget` by `KIMI_IMAGE_READ_BYTE_BUDGET`; both take higher priority than `config.toml`. @@ -481,7 +477,7 @@ api_key = "sk-xxx" ## `permission` -`permission` sets permission rules that are automatically loaded when a session starts, controlling whether the Agent needs user confirmation before calling a tool. Rules are written as a `[[permission.rules]]` array of tables, matched in order — the first matching rule takes effect. +`permission` sets permission rules that are automatically loaded when a session starts, controlling whether the Agent needs user confirmation before calling a tool. Rules are written as a `[[permission.rules]]` array of tables, matched in order; the first matching rule takes effect. You can also set `dangerous_command_guard = false` under `[permission]` to turn off the built-in dangerous-command policy entirely (no dangerous-command ask or auto-mode deny); the default is `true`. An environment variable `KIMI_CODE_DANGEROUS_COMMAND_GUARD=false` overrides the file setting and restores the behavior before the policy was introduced. Use this switch only for environments that already gate commands outside the agent. @@ -492,7 +488,7 @@ You can also set `dangerous_command_guard = false` under `[permission]` to turn | `pattern` | `string` | Yes | Match pattern in the form `ToolName` or `ToolName(arg-pattern)`, e.g. `Read` or `Bash(rm -rf*)` | | `reason` | `string` | No | Rule description for debugging and auditing | -Built-in tool names are listed in [Built-in tools](../reference/tools.md). Most built-in tools that accept rule arguments define their own matching subject, such as `Bash(command-pattern)` or `Read(path-pattern)`. `AgentSwarm`, MCP tools, and custom tools can only be matched by tool name — argument patterns are not supported for them. +Built-in tool names are listed in [Built-in tools](../reference/tools.md). Most built-in tools that accept rule arguments define their own matching subject, such as `Bash(command-pattern)` or `Read(path-pattern)`. `AgentSwarm`, MCP tools, and custom tools can only be matched by tool name; argument patterns are not supported for them. ```toml [[permission.rules]] @@ -518,20 +514,27 @@ MCP server declarations are configured in `~/.kimi-code/mcp.json` or the project ## `tui.toml` -Alongside `config.toml`, the CLI keeps terminal-UI and client preferences in a companion `tui.toml` in the same directory (`~/.kimi-code/tui.toml`, or `$KIMI_CODE_HOME/tui.toml` when overridden). It is created with defaults on first run, and the interactive commands `/config`, `/theme`, and `/editor` write to it for you — so you rarely need to edit it by hand. If the file is malformed, the CLI falls back to defaults and shows a notice instead of failing to start. +Alongside `config.toml`, the CLI keeps terminal-UI and client preferences in a companion `tui.toml` in the same directory (`~/.kimi-code/tui.toml`, or `$KIMI_CODE_HOME/tui.toml` when overridden). It is created with defaults on first run, and the interactive commands `/config`, `/theme`, and `/editor` write to it for you, so you rarely need to edit it by hand. If the file is malformed, the CLI falls back to defaults and shows a notice instead of failing to start. | Field | Type | Default | Description | | --- | --- | --- | --- | -| `theme` | `string` | `auto` | Color theme: `auto` (follow the terminal), `dark`, `light`, or the name of a [custom theme](../customization/themes.md) | -| `render_latex` | `boolean` | `true` | Render LaTeX math expressions (`$…$`, `$$…$$`) in Markdown messages as Unicode text; `false` keeps the raw source | +| `theme` | `string` | `auto` | Color theme: `auto`, `dark`, `light`, or the name of a [custom theme](../customization/themes.md) | +| `render_latex` | `boolean` | `true` | Render LaTeX math expressions in Markdown messages as Unicode text; `false` keeps the raw source | | `disable_paste_burst` | `boolean` | `false` | Disable the non-bracketed paste-burst fallback that keeps rapid multi-line pastes from submitting line by line | -| `cache_expiry_hint` | `boolean` | `true` | Show a dialog when resuming a long-idle session or submitting after a long idle stretch, warning that the context cache has likely expired and offering to compact or start a new session (v2 engine only) | +| `cache_expiry_hint` | `boolean` | `true` | On resume or when submitting after a long idle stretch, warn that the context cache may have expired and offer to compact or start a new session (v2 engine only) | | `[editor].command` | `string` | `""` | External editor command for composing long input; empty falls back to `$VISUAL` / `$EDITOR` | | `[notifications].enabled` | `boolean` | `true` | Whether desktop notifications are sent | | `[notifications].notification_condition` | `string` | `unfocused` | When to notify: `unfocused` (only when the terminal is not focused) or `always` | | `[upgrade].auto_install` | `boolean` | `true` | Whether new versions are installed automatically | -| `[status_line].items` | `string[]` | `[]` | Built-in slots to show on the first footer line and their order: `mode`, `goal`, `model`, `tasks`, `cwd`, `git`, `tips`. Unset keeps the default layout; unknown ids are skipped with a warning | -| `[status_line].command` | `string` | `""` | Custom status line command. Its first stdout line replaces the first footer line, with a JSON snapshot (model, cwd, git branch, permission mode, plan mode, context usage, session id, version) passed on stdin. Runs are capped at 300ms and throttled to once per second; failures fall back to the built-in layout | +| `[status_line].items` | `string[]` | `[]` | Built-in slots on the first footer line and their order: `mode`, `goal`, `model`, `tasks`, `cwd`, `git`, `tips`; unknown ids are skipped with a warning | +| `[status_line].command` | `string` | `""` | Custom status line command: its first stdout line replaces the footer, and a JSON snapshot is passed on stdin; capped at 300ms, throttled to once per second, failures fall back to the built-in layout | + +
+Fields in the stdin JSON snapshot + +Model, cwd, git branch, permission mode, plan mode, context usage, session id, version. + +
```toml # ~/.kimi-code/tui.toml @@ -569,7 +572,7 @@ The `[workspace]` table groups project-level workspace settings: | Field | Type | Required | Description | | --- | --- | --- | --- | -| `additional_dir` | `array` | No | Additional workspace directories, stored as absolute paths. Written automatically when you confirm "remember this directory" in `/add-dir`; read back on startup so the directories are available in every session of this project | +| `additional_dir` | `array` | No | Additional workspace directories (absolute paths); written automatically when you confirm "remember this directory" in `/add-dir`, and available in every session of this project | ```toml [workspace] diff --git a/docs/en/configuration/data-locations.md b/docs/en/configuration/data-locations.md index fa7bb446437..2d51482e06a 100644 --- a/docs/en/configuration/data-locations.md +++ b/docs/en/configuration/data-locations.md @@ -1,6 +1,6 @@ # Data locations -Kimi Code CLI stores all runtime data — the config file, session history, login credentials, and diagnostic logs — under `~/.kimi-code/`. This page helps you understand where each type of data lives, what it is for, and how to clean up or relocate it when needed. +Kimi Code CLI stores the config file, session history, login credentials, diagnostic logs, and other runtime data under `~/.kimi-code/`. This page helps you understand where each type of data lives, what it is for, and how to clean up or relocate it when needed. ## Data root directory @@ -16,7 +16,7 @@ If you need to move the data directory elsewhere (for example, to isolate config export KIMI_CODE_HOME="$HOME/.config/kimi-code" ``` -Once set, **all** Kimi Code data — config, sessions, logs, OAuth credentials, Kimi-specific user Skills, global `AGENTS.md`, and more — lands under the new path. For the full reference on `KIMI_CODE_HOME`, see [Environment variables](./env-vars.md). +Once set, **all** Kimi Code data lands under the new path: config, sessions, logs, OAuth credentials, Kimi-specific user Skills, global `AGENTS.md`, and more. For the full reference on `KIMI_CODE_HOME`, see [Environment variables](./env-vars.md). ::: tip Note @@ -80,7 +80,7 @@ Inside each session directory: - **`agents/main/plans/`**: plan files written in Plan mode, named by plan id (`.md`). - **`agents/agent-0/` etc.**: sub-Agent instance directories, each containing their own `wire.jsonl`. - **`logs/kimi-code.log`**: diagnostic log for this session; only present when a diagnostic event occurs. -- **`tasks/`**: background task persistence — `tasks/.json` stores status/pid/exit code; `tasks//output.log` stores output. +- **`tasks/`**: background task persistence. `tasks/.json` stores status/pid/exit code; `tasks//output.log` stores output. - **`cron/`**: scheduled task persistence; reloaded into the scheduler when the session is resumed with `kimi --session`. See [Scheduled tasks](../reference/tools.md#scheduled-tasks). ## Built-in tool cache diff --git a/docs/en/configuration/env-vars.md b/docs/en/configuration/env-vars.md index a3914764e4f..4ee6487890d 100644 --- a/docs/en/configuration/env-vars.md +++ b/docs/en/configuration/env-vars.md @@ -1,11 +1,11 @@ # Environment variables -Kimi Code CLI uses environment variables to control a small number of runtime behaviors — relocating the data directory, turning off telemetry, and temporarily switching models without touching the config file. +Kimi Code CLI uses environment variables to control a small number of runtime behaviors: relocating the data directory, turning off telemetry, and temporarily switching models without touching the config file. ::: warning Important: API keys are not configured here -Credential variables such as `KIMI_API_KEY`, `ANTHROPIC_API_KEY`, and `OPENAI_API_KEY` are **not** read automatically from shell environment variables. Running `export KIMI_API_KEY=xxx` in the terminal does not give any provider its key — they must be written in `config.toml` under `[providers.]` or the `[providers..env]` sub-table. +Credential variables such as `KIMI_API_KEY`, `ANTHROPIC_API_KEY`, and `OPENAI_API_KEY` are **not** read automatically from shell environment variables. Running `export KIMI_API_KEY=xxx` in the terminal does not give any provider its key. They must be written in `config.toml` under `[providers.]` or the `[providers..env]` sub-table. -The only exception is the `KIMI_MODEL_*` family, which is an explicit channel that *does* read credentials from the shell — see [Define a model from environment variables](#define-a-model-from-environment-variables-kimi-model). +The only exception is the `KIMI_MODEL_*` family, an explicit channel that *does* read credentials from the shell. See [Define a model from environment variables](#define-a-model-from-environment-variables-kimi_model_). For background, see [Config overrides: provider credentials](./overrides.md#provider-credentials). ::: @@ -34,11 +34,15 @@ export KIMI_DISABLE_TELEMETRY=1 ### `KIMI_MODEL_*` family -Switch models temporarily without modifying `config.toml` — when `KIMI_MODEL_NAME` is set, the CLI synthesizes a temporary provider in memory; the change does not persist after restart. See [Define a model from environment variables](#define-a-model-from-environment-variables-kimi-model). +Switch models temporarily without modifying `config.toml`: when `KIMI_MODEL_NAME` is set, the CLI synthesizes a temporary provider in memory, and the change does not persist after restart. See [Define a model from environment variables](#define-a-model-from-environment-variables-kimi_model_). ### `KIMI_CODE_CUSTOM_HEADERS` -Attaches custom HTTP headers to every outbound model request — both LLM chat requests (across all provider protocols) and `/models` listing requests. Useful when a gateway routes by header, for example to pin a specific cluster: +::: info Added +Added in 0.20.2. +::: + +Attaches custom HTTP headers to every outbound model request: both LLM chat requests (across all provider protocols) and `/models` listing requests carry them. Useful when a gateway routes by header, for example to pin a specific cluster: ```sh export KIMI_CODE_CUSTOM_HEADERS=$'X-Gateway-Cluster: my-cluster\nX-Custom-Tag: debug' @@ -46,15 +50,11 @@ export KIMI_CODE_CUSTOM_HEADERS=$'X-Gateway-Cluster: my-cluster\nX-Custom-Tag: d The format mirrors `ANTHROPIC_CUSTOM_HEADERS`: newline-separated `Name: Value` lines. Names and values are trimmed, and lines without a colon are ignored. -::: info Added -Added in 0.20.2. -::: - -> Precedence: the Kimi identity headers (`User-Agent`, `X-Msh-*`) and a provider's `custom_headers` in `config.toml` (see [Config files](./config-files.md#providers)) override same-named entries here. Authentication is protocol-dependent: on the `kimi`, `openai`, and `openai_responses` protocols an exact `Authorization` entry replaces the generated bearer token, while `/models` listing requests keep their own authentication. A case variant such as `authorization` is never treated as the same name — it is combined with the real header, which can break requests. Do not use this variable for authentication or other reserved headers. Use `custom_headers` when headers need to differ per provider. +> Precedence: the Kimi identity headers (`User-Agent`, `X-Msh-*`) and a provider's `custom_headers` in `config.toml` (see [Config files](./config-files.md#providers)) override same-named entries here. Authentication is protocol-dependent: on the `kimi`, `openai`, and `openai_responses` protocols an exact `Authorization` entry replaces the generated bearer token, while `/models` listing requests keep their own authentication. A case variant such as `authorization` is never treated as the same name. It merges with the real header, which can break requests. Do not use this variable for authentication or other reserved headers. Use `custom_headers` when headers need to differ per provider. ## Provider credential key names (written in config.toml) -The key names below are not read directly from the shell — they are key names written inside the `[providers..env]` sub-table of `config.toml`, serving as fallback values for `api_key` / `base_url`. The CLI reads only from the config file, not from `process.env`. +The key names below are not read directly from the shell. They are key names written inside the `[providers..env]` sub-table of `config.toml`, serving as fallback values for `api_key` / `base_url`. The CLI reads only from the config file, not from `process.env`. This design lets you keep familiar key name conventions while centralizing secret management in the config file: @@ -80,7 +80,7 @@ Key names per provider: | `GOOGLE_CLOUD_LOCATION` | Vertex AI | None | ::: warning -`GOOGLE_APPLICATION_CREDENTIALS` (path to a service account JSON file) is the only exception that goes through the system environment variable mechanism — it is read by the Google SDK directly via the standard ADC flow, and the CLI does not participate. All other key names must be placed in the `[providers..env]` sub-table to take effect. +`GOOGLE_APPLICATION_CREDENTIALS` (path to a service account JSON file) is the only exception that goes through the system environment variable mechanism. It is read by the Google SDK directly via the standard ADC flow; the CLI does not participate. All other key names must be placed in the `[providers..env]` sub-table to take effect. ::: For the full provider type and field reference, see [Providers and models](./providers.md). @@ -101,7 +101,7 @@ This group of variables redirects OAuth authentication and managed service endpo ## Define a model from environment variables (`KIMI_MODEL_*`) -Want to switch models for testing without touching `config.toml`? When `KIMI_MODEL_NAME` is set, the CLI synthesizes a temporary provider and model alias from the `KIMI_MODEL_*` variables in memory — nothing is written back to the config file. These variables take priority over `default_model` in `config.toml`, but the `-m ` option at startup still has the highest priority. +Want to switch models for testing without touching `config.toml`? When `KIMI_MODEL_NAME` is set, the CLI synthesizes a temporary provider and model alias from the `KIMI_MODEL_*` variables in memory; nothing is written back to the config file. These variables take priority over `default_model` in `config.toml`, but the `-m ` option at startup still has the highest priority. ```sh export KIMI_MODEL_NAME="kimi-for-coding" @@ -137,40 +137,40 @@ Switches that control the behavior of subsystems such as telemetry, background t | Variable | Purpose | Valid values | | --- | --- | --- | | `KIMI_DISABLE_TELEMETRY` | Disable anonymous telemetry reporting | `1`, `true`, `yes`, `y` (case-insensitive) | -| `KIMI_CODE_PASSWORD` | Set a parallel auth credential for the `kimi web` local server, valid alongside the bearer token; recommended when binding the server beyond loopback — see [Using Kimi Code in the browser: Security notes](../guides/web.md#security-notes) | Any non-empty string; when unset, only the token is valid | -| `KIMI_CODE_BACKGROUND_KEEP_ALIVE_ON_EXIT` | Whether to keep background tasks when the session closes; takes higher priority than `config.toml`. The default is to stop them on exit | Truthy: `1`/`true`/`yes`/`on`; falsy: `0`/`false`/`no`/`off` | -| `KIMI_CODE_BACKGROUND_MAX_RUNNING_TASKS` | Cap on concurrently running background tasks; takes higher priority than `[background] max_running_tasks` in `config.toml` (unset means no cap) | Positive integer; invalid values are ignored | -| `KIMI_IMAGE_MAX_EDGE_PX` | Longest-edge ceiling (px) for image compression; takes higher priority than `[image] max_edge_px` in `config.toml` (default `2000`) | Positive integer; invalid values are ignored | -| `KIMI_IMAGE_READ_BYTE_BUDGET` | Per-image byte budget for model-initiated image reads (`ReadMediaFile` default reads); takes higher priority than `[image] read_byte_budget` in `config.toml` (default `262144`, i.e. 256 KB) | Positive integer; invalid values are ignored | -| `KIMI_CODE_PLUGIN_MARKETPLACE_URL` | Override the plugin marketplace JSON loaded by `/plugins`; useful for dev loopback servers, staging CDN files, or alternate marketplace directories | `https://code.kimi.com/kimi-code/plugins/marketplace.json`; also accepts `http://`, `file://` URLs, and local paths | -| `KIMI_CODE_AGENT_SWARM_MAX_CONCURRENCY` | Cap how many AgentSwarm subagents run concurrently during the initial ramp; leave unset for no cap | Positive integer; invalid values fail fast | -| `KIMI_SUBAGENT_TIMEOUT_MS` | Maximum wall-clock time (ms) a single `Agent` subagent may run; takes higher priority than `[subagent] timeout_ms` in `config.toml` (default `7200000`, i.e. 2 hours) | Positive integer; invalid values fall back to the config or default | -| `KIMI_CODE_SWARM_TIMEOUT_MS` | Maximum wall-clock time (ms) a single `AgentSwarm` subagent may run; takes higher priority than `[swarm] timeout_ms` in `config.toml` (default `7200000`, i.e. 2 hours) | Positive integer; invalid values fall back to the config or default | -| `KIMI_CODE_IDENTITY_NAME` | Display name the agent calls itself in the system prompt; takes higher priority than `[identity] name` in `config.toml` and is never written back to it | Any non-empty string; blank values read as unset | -| `KIMI_CODE_IDENTITY_SLUG` | Protocol identifier for the `User-Agent` product token sent to third-party providers and the MCP client name; takes higher priority than `[identity] slug`. Derived from the name when unset | Any non-empty string; normalized to lowercase with non-alphanumeric runs folded to `-` | -| `KIMI_CODE_BUILTIN_PRODUCT_SKILLS` | Whether the built-in skills documenting Kimi Code itself are offered to the model; takes higher priority than `builtin_product_skills` in `config.toml` (default enabled) | Truthy: `1`/`true`/`yes`/`on`; falsy: `0`/`false`/`no`/`off` | -| `KIMI_CODE_TUI_FULL_SCREEN` | Enable the experimental fullscreen alternate-screen UI: scrollable transcript viewport, mouse text selection, clickable links, and Ctrl-Shift-F transcript search | `1` enables it; anything else keeps the regular inline UI | -| `KIMI_CODE_EXPERIMENTAL_SECONDARY_MODEL` | The [subagent model pool](./config-files.md#subagent-model-pool) is enabled by default in every launch mode, including the interactive TUI; set a falsy value to disable it; the master `KIMI_CODE_EXPERIMENTAL_FLAG=1` also enables it | Truthy: `1`/`true`/`yes`/`on`; falsy: `0`/`false`/`no`/`off` | -| `KIMI_CODE_EXPERIMENTAL_SUBAGENT_FORK` | Enable the experimental `fork` parameter on the `Agent` and `AgentSwarm` tools, letting the model start a subagent with a snapshot of the calling agent's conversation history instead of an empty context; the master `KIMI_CODE_EXPERIMENTAL_FLAG=1` also enables it | Truthy: `1`/`true`/`yes`/`on`; falsy: `0`/`false`/`no`/`off` | -| `KIMI_MCP_STARTUP_TIMEOUT_MS` | Global default connection timeout (ms) for all MCP servers; takes higher priority than `[mcp] startup_timeout_ms` in `config.toml`, but a per-server `startupTimeoutMs` in `mcp.json` still wins (default `30000`) | Integer from `1` to `2147483647`; invalid values are ignored | -| `KIMI_MCP_TOOL_TIMEOUT_MS` | Global default single tool-call timeout (ms) for all MCP servers; takes higher priority than `[mcp] tool_timeout_ms` in `config.toml`, but a per-server `toolTimeoutMs` in `mcp.json` still wins (default `60000`) | Integer from `1` to `2147483647`; invalid values are ignored | -| `KIMI_LOOP_MAX_STEPS_PER_TURN` | Maximum Agent steps per turn; takes higher priority than `[loop_control] max_steps_per_turn` in `config.toml` (unset or `0` means unlimited) | Non-negative integer; invalid values are ignored | -| `KIMI_LOOP_MAX_ATTEMPTS_PER_STEP` | Maximum total attempts for a failing step (including the initial attempt); takes higher priority than `[loop_control] max_attempts_per_step` in `config.toml` (default `10`). The deprecated `KIMI_LOOP_MAX_RETRIES_PER_STEP` is still honored with a warning when this variable is unset | Non-negative integer; invalid values are ignored | -| `KIMI_CODE_INFINITE_RETRY` | Retry every failed LLM request indefinitely — turn steps and background operations such as compaction alike — instead of failing the task; waits use exponential backoff (capped at 32 s) and honor the server's `Retry-After` header, and aborting still cancels immediately. Intended for long-running unattended evaluations against endpoints that may fail temporarily | Truthy: `1`/`true`/`yes`/`on`; falsy: `0`/`false`/`no`/`off` | -| `KIMI_TOKEN_COUNTING_STRATEGY` | Which context token count is reported externally (the context-size display); takes higher priority than `[token_counting] strategy` in `config.toml` (default `measured+estimated`) | `measured+estimated`, `measured`, `estimated` (case-insensitive); invalid values are ignored | -| `KIMI_WEB_SEARCH_BASE_URL` | API URL of the web search (`WebSearch`) service; takes higher priority than `[services.moonshot_search] base_url` in `config.toml`, and enables the service without that config section. Persisted credentials and custom headers are not forwarded to an env-selected endpoint | Non-blank string; blank values are ignored | -| `KIMI_WEB_SEARCH_API_KEY` | API key of the web search (`WebSearch`) service; replaces both the configured API key and OAuth credential when set | Non-blank string; blank values are ignored | -| `KIMI_WEB_FETCH_BASE_URL` | API URL of the web fetch (`FetchURL`) service; takes higher priority than `[services.moonshot_fetch] base_url`. Persisted credentials and custom headers are not forwarded to an env-selected endpoint. Without an env or config endpoint, signed-in users try the managed Kimi OAuth fetch service before direct local requests | Non-blank string; blank values are ignored | -| `KIMI_WEB_FETCH_API_KEY` | API key of the web fetch (`FetchURL`) service; replaces both the configured API key and OAuth credential when set | Non-blank string; blank values are ignored | -| `KIMI_CODE_EXPERIMENTAL_FLAG` | Enable all registered experimental features for this process; a per-feature `KIMI_CODE_EXPERIMENTAL_` variable or an explicit entry in the `[experimental]` section of `config.toml` takes precedence over it; it does not select the agent engine | `1`, `true`, `yes`, `on` | -| `KIMI_CODE_LEGACY_FLAG` | Use the legacy `agent-core` engine for `kimi`, `kimi -p`, `kimi doctor`, `kimi export`, and `kimi provider`; these commands use `agent-core-v2` by default | `1`, `true`, `yes`, `on` | +| `KIMI_CODE_PASSWORD` | Parallel auth credential for `kimi web`, recommended when binding beyond loopback (see [Security notes](../guides/web.md#security-notes)) | Any non-empty string; when unset, only the token is valid | +| `KIMI_CODE_BACKGROUND_KEEP_ALIVE_ON_EXIT` | Keep background tasks when the session closes; higher priority than `config.toml` (default: stop them on exit) | Truthy: `1`/`true`/`yes`/`on`; falsy: `0`/`false`/`no`/`off` | +| `KIMI_CODE_BACKGROUND_MAX_RUNNING_TASKS` | Cap on concurrently running background tasks; higher priority than `[background] max_running_tasks` (unset = no cap) | Positive integer; invalid values are ignored | +| `KIMI_IMAGE_MAX_EDGE_PX` | Longest-edge ceiling (px) for image compression; higher priority than `[image] max_edge_px` (default `2000`) | Positive integer; invalid values are ignored | +| `KIMI_IMAGE_READ_BYTE_BUDGET` | Per-image byte budget for model-initiated image reads; higher priority than `[image] read_byte_budget` (default `262144`) | Positive integer; invalid values are ignored | +| `KIMI_CODE_PLUGIN_MARKETPLACE_URL` | Override the marketplace JSON loaded by `/plugins`; default `https://code.kimi.com/kimi-code/plugins/marketplace.json` | Also accepts `http://`, `file://` URLs, and local paths | +| `KIMI_CODE_AGENT_SWARM_MAX_CONCURRENCY` | Cap on AgentSwarm subagents running concurrently during the initial ramp; unset = no cap | Positive integer; invalid values fail fast | +| `KIMI_SUBAGENT_TIMEOUT_MS` | Max wall-clock time (ms) a single `Agent` subagent may run; higher priority than `[subagent] timeout_ms` | Positive integer; invalid values fall back to the config or default | +| `KIMI_CODE_SWARM_TIMEOUT_MS` | Max wall-clock time (ms) an `AgentSwarm` subagent may run; higher priority than `[swarm] timeout_ms` | Positive integer; invalid values fall back to the config or default | +| `KIMI_CODE_IDENTITY_NAME` | Name the agent calls itself in the system prompt; higher priority than `[identity] name`, never written back | Any non-empty string; blank values read as unset | +| `KIMI_CODE_IDENTITY_SLUG` | `User-Agent` product token and MCP client name; higher priority than `[identity] slug`; derived from the name when unset | Any non-empty string; normalized to lowercase with non-alphanumeric runs folded to `-` | +| `KIMI_CODE_BUILTIN_PRODUCT_SKILLS` | Offer the built-in skills documenting Kimi Code itself to the model; higher priority than `builtin_product_skills` | Truthy: `1`/`true`/`yes`/`on`; falsy: `0`/`false`/`no`/`off` | +| `KIMI_CODE_TUI_FULL_SCREEN` | Experimental fullscreen UI: scrollable transcript, mouse selection, clickable links, Ctrl-Shift-F search | `1` enables it; anything else keeps the regular inline UI | +| `KIMI_CODE_EXPERIMENTAL_SECONDARY_MODEL` | The [subagent model pool](./config-files.md#subagent-model-pool) is enabled by default in all launch modes; set a falsy value to disable it; `KIMI_CODE_EXPERIMENTAL_FLAG=1` also enables it | Truthy: `1`/`true`/`yes`/`on`; falsy: `0`/`false`/`no`/`off` | +| `KIMI_CODE_EXPERIMENTAL_SUBAGENT_FORK` | Experimental `fork` parameter on `Agent`/`AgentSwarm`: start the subagent from a snapshot of the caller's history instead of an empty context; `KIMI_CODE_EXPERIMENTAL_FLAG=1` also enables it | Truthy: `1`/`true`/`yes`/`on`; falsy: `0`/`false`/`no`/`off` | +| `KIMI_MCP_STARTUP_TIMEOUT_MS` | Global default connection timeout (ms) for MCP servers; overrides the config file, but `mcp.json` `startupTimeoutMs` still wins | Integer from `1` to `2147483647`; invalid values are ignored | +| `KIMI_MCP_TOOL_TIMEOUT_MS` | Global default single tool-call timeout (ms) for MCP servers; overrides the config file, but `mcp.json` `toolTimeoutMs` still wins | Integer from `1` to `2147483647`; invalid values are ignored | +| `KIMI_LOOP_MAX_STEPS_PER_TURN` | Max Agent steps per turn; higher priority than `[loop_control] max_steps_per_turn` (`0` = unlimited) | Non-negative integer; invalid values are ignored | +| `KIMI_LOOP_MAX_ATTEMPTS_PER_STEP` | Max total attempts for a failing step (including the first); higher priority than `[loop_control] max_attempts_per_step` | Non-negative integer; invalid values are ignored | +| `KIMI_CODE_INFINITE_RETRY` | Retry failed LLM requests indefinitely; exponential backoff (32 s cap) honoring `Retry-After`; aborting still cancels immediately | Truthy: `1`/`true`/`yes`/`on`; falsy: `0`/`false`/`no`/`off` | +| `KIMI_TOKEN_COUNTING_STRATEGY` | Context token count reported externally; higher priority than `[token_counting] strategy` | `measured+estimated`, `measured`, `estimated` (case-insensitive); invalid values are ignored | +| `KIMI_WEB_SEARCH_BASE_URL` | Web search (`WebSearch`) service API URL; higher priority than the config file; credentials and custom headers not forwarded | Non-blank string; blank values are ignored | +| `KIMI_WEB_SEARCH_API_KEY` | Web search (`WebSearch`) service API key; replaces both the configured key and the OAuth credential | Non-blank string; blank values are ignored | +| `KIMI_WEB_FETCH_BASE_URL` | Web fetch (`FetchURL`) service API URL; higher priority than the config file; credentials not forwarded. Without an endpoint, signed-in users get the managed Kimi OAuth fetch service before direct local requests | Non-blank string; blank values are ignored | +| `KIMI_WEB_FETCH_API_KEY` | Web fetch (`FetchURL`) service API key; replaces both the configured key and the OAuth credential | Non-blank string; blank values are ignored | +| `KIMI_CODE_EXPERIMENTAL_FLAG` | Enable all registered experimental features for this process; does not select the agent engine | `1`, `true`, `yes`, `on` | +| `KIMI_CODE_LEGACY_FLAG` | Legacy `agent-core` engine for `kimi`, `kimi -p`, `kimi doctor`, `kimi export`, and `kimi provider` (default: `agent-core-v2`) | `1`, `true`, `yes`, `on` | | `KIMI_SHELL_PATH` | Override the Git Bash path on Windows (used when auto-detection fails) | Absolute path | | `KIMI_MODEL_MAX_COMPLETION_TOKENS` | Hard cap on `max_completion_tokens` per LLM step; applies to the `kimi` provider only | Positive integer; `0` or negative disables clamping | -| `KIMI_MODEL_TEMPERATURE` | Sampling temperature for every request; applies to the `kimi` provider only (global — independent of `KIMI_MODEL_NAME`) | Number, e.g. `0.3` | -| `KIMI_MODEL_TOP_P` | Nucleus-sampling `top_p` for every request; applies to the `kimi` provider only (global) | Number, e.g. `0.95` | -| `KIMI_MODEL_THINKING_EFFORT` | Force a specific thinking effort on the wire (`thinking.effort`), bypassing the model's declared `support_efforts`; applies to the `kimi` provider only, and only while Thinking is on | An effort value, e.g. `max` | -| `KIMI_MODEL_THINKING_KEEP` | Preserved-thinking passthrough; on `kimi` sent as `thinking.keep`, on `anthropic` (Claude and Kimi's Anthropic-compatible mode) sent as a `context_management` `clear_thinking_20251015` edit (enabling keep routes Anthropic requests to the beta Messages API); overrides `[thinking] keep` (which defaults to `"all"`); only injected while Thinking is on | A value the API accepts, e.g. `all`; an off-value (`false`/`0`/`no`/`off`/`none`/`null`) disables it | -| `KIMI_CODE_NO_AUTO_UPDATE` | Fully disable the update preflight — no check, background install, or prompt. Legacy alias `KIMI_CLI_NO_AUTO_UPDATE` is also honored | Truthy: `1`/`true`/`yes`/`on` | +| `KIMI_MODEL_TEMPERATURE` | Sampling temperature for every request; `kimi` provider only (global, independent of `KIMI_MODEL_NAME`) | Number, e.g. `0.3` | +| `KIMI_MODEL_TOP_P` | Nucleus-sampling `top_p` for every request; `kimi` provider only (global) | Number, e.g. `0.95` | +| `KIMI_MODEL_THINKING_EFFORT` | Force a thinking effort (`thinking.effort`), bypassing the model's declared `support_efforts`; `kimi` provider only | An effort value, e.g. `max` | +| `KIMI_MODEL_THINKING_KEEP` | Preserved-thinking passthrough: `thinking.keep` on `kimi`, a `clear_thinking_20251015` edit on `anthropic`; overrides `[thinking] keep` | A value the API accepts, e.g. `all`; an off-value (`false`/`0`/`no`/`off`/`none`/`null`) disables it | +| `KIMI_CODE_NO_AUTO_UPDATE` | Fully disable the update preflight: no check, background install, or prompt. Legacy alias `KIMI_CLI_NO_AUTO_UPDATE` also honored | Truthy: `1`/`true`/`yes`/`on` | | `KIMI_DISABLE_CRON` | Disable the scheduled-task tool (`CronCreate` rejects new schedules; existing tasks do not fire) | `1` to disable | The `KIMI_CODE_INFINITE_RETRY`, `KIMI_CODE_IDENTITY_*`, and `KIMI_CODE_BUILTIN_PRODUCT_SKILLS` variables are read by the default `agent-core-v2` engine. The legacy `kimi` / `kimi -p` path selected with `KIMI_CODE_LEGACY_FLAG=1` ignores them. @@ -203,16 +203,22 @@ The CLI also reads several standard system variables to detect the runtime envir ## HTTP proxy -Kimi Code honors the standard proxy environment variables for all outbound traffic — model API calls, MCP servers, web tools, telemetry, sign-in, and update checks: +Kimi Code honors the standard proxy environment variables for all outbound traffic: model API calls, MCP servers, web tools, telemetry, sign-in, and update checks: - `HTTP_PROXY` / `http_proxy`: proxy for `http://` requests - `HTTPS_PROXY` / `https_proxy`: proxy for `https://` requests - `ALL_PROXY` / `all_proxy`: fallback proxy used when the scheme-specific variable is unset; this is where a SOCKS proxy is usually set - `NO_PROXY` / `no_proxy`: comma-separated hosts that bypass the proxy -Both HTTP(S) and SOCKS proxies are supported. A SOCKS proxy is recognized by its scheme — `socks5://`, `socks5h://`, `socks4://`, or `socks://` (an alias for `socks5://`) — and is typically set via `ALL_PROXY` (the form used by tools like Clash and V2RayN). An HTTP(S) proxy takes precedence over `ALL_PROXY` for HTTP/HTTPS traffic. +### Proxy types and precedence + +Both HTTP(S) and SOCKS proxies are supported. A SOCKS proxy is recognized by its scheme: `socks5://`, `socks5h://`, `socks4://`, or `socks://` (an alias for `socks5://`). It is typically set via `ALL_PROXY` (the form used by tools like Clash and V2RayN). An HTTP(S) proxy takes precedence over `ALL_PROXY` for HTTP/HTTPS traffic. + +### Activation conditions and loopback addresses + +The proxy is applied only when one of these variables is set; otherwise connections are made directly. Loopback hosts (`localhost`, `127.0.0.1`, `::1`) always bypass the proxy, so a local server such as a localhost MCP server keeps working when a proxy is configured. Add your own internal hosts to `NO_PROXY` to exempt them too. -The proxy is applied only when one of these variables is set; otherwise connections are made directly. Loopback hosts (`localhost`, `127.0.0.1`, `::1`) always bypass the proxy, so a local server such as a localhost MCP server keeps working when a proxy is configured — add your own internal hosts to `NO_PROXY` to exempt them too. +### MCP child processes Stdio MCP servers that run as Node child processes honor `HTTP_PROXY` / `HTTPS_PROXY` / `NO_PROXY` automatically when the child's Node version supports `NODE_USE_ENV_PROXY` (Node ≥ 22.21 or ≥ 24.5); SOCKS proxying applies to Kimi Code's own traffic only. diff --git a/docs/en/configuration/overrides.md b/docs/en/configuration/overrides.md index 94e126c77fc..14eb6889105 100644 --- a/docs/en/configuration/overrides.md +++ b/docs/en/configuration/overrides.md @@ -1,10 +1,10 @@ # Config overrides -Kimi Code CLI has three places where runtime parameters can be influenced: the config file, command-line options, and environment variables. They are not a simple "whoever has higher priority wins" relationship — the three serve different scenarios and have non-overlapping scopes: +Kimi Code CLI has three places where runtime parameters can be influenced: the config file, command-line options, and environment variables. They are not a simple priority stack: the three serve different scenarios and have non-overlapping scopes: - **Config file** stores long-term preferences (model, keys, loop control, etc.); takes effect on every startup - **Command-line options** make one-off changes for the current startup; discarded after exit -- **Environment variables** primarily handle data directory location, OAuth endpoint switching, and a small number of runtime switches — **not a general fallback mechanism for config fields** +- **Environment variables** primarily handle data directory location, OAuth endpoint switching, and a small number of runtime switches. They are **not a general fallback mechanism for config fields**. This distinction matters: many users run `export KIMI_API_KEY=xxx` in the shell expecting the CLI to pick it up automatically, but it does not. See [Provider credentials](#provider-credentials) below for why. @@ -13,7 +13,7 @@ This distinction matters: many users run `export KIMI_API_KEY=xxx` in the shell Environment variables fall into three categories by function and cannot be collapsed into a single linear priority order: 1. **Locating the config file**: `KIMI_CODE_HOME` sets the data root directory, making the config file path `$KIMI_CODE_HOME/config.toml`. This step runs before all other resolution and is not a fallback for individual parameters. -2. **Runtime switches**: A small set of variables like `KIMI_DISABLE_TELEMETRY` directly shut down the corresponding subsystem — even if `config.toml` has `telemetry = true`, setting this variable to a truthy value disables telemetry. The semantics are "additionally disable", not "ordinary override". +2. **Runtime switches**: A small set of variables like `KIMI_DISABLE_TELEMETRY` directly shut down the corresponding subsystem. Even if `config.toml` has `telemetry = true`, a truthy value for this variable disables telemetry. The semantics are "additionally disable", not "ordinary override". 3. **Runtime endpoints and diagnostics**: Variables like `KIMI_CODE_OAUTH_HOST`, `KIMI_CODE_BASE_URL`, and `KIMI_LOG_LEVEL` are read when the OAuth or logging subsystems initialize. For the full list, see [Environment variables](./env-vars.md). ## Priority for ordinary runtime parameters @@ -23,13 +23,13 @@ For ordinary runtime parameters such as model alias, Plan mode, permission mode, 1. **Command-line options** (`-m`, `--plan`, `--yolo`, etc.): apply only to the current startup 2. **User config file** (`~/.kimi-code/config.toml`): stores long-term preferences -A small number of environment variables explicitly override specific config file fields — for example, `KIMI_CODE_BACKGROUND_KEEP_ALIVE_ON_EXIT` has higher priority than `[background].keep_alive_on_exit`. These exceptions are noted in [Environment variables](./env-vars.md) and in the relevant field descriptions in [Configuration files](./config-files.md). +A small number of environment variables explicitly override specific config file fields. For example, `KIMI_CODE_BACKGROUND_KEEP_ALIVE_ON_EXIT` has higher priority than `[background].keep_alive_on_exit`. These exceptions are noted in [Environment variables](./env-vars.md) and in the relevant field descriptions in [Configuration files](./config-files.md). ::: warning -**Ordinary runtime parameters do not fall back to shell environment variables.** Provider `api_key` / `base_url` are read only from `config.toml` (including the `[providers..env]` sub-table) and do not fall back to `export`-ed shell variables. The only exception is the explicit `KIMI_MODEL_*` channel — see [Define a model from environment variables](./env-vars.md#define-a-model-from-environment-variables-kimi-model). +**Ordinary runtime parameters do not fall back to shell environment variables.** Provider `api_key` / `base_url` are read only from `config.toml` (including the `[providers..env]` sub-table) and do not fall back to `export`-ed shell variables. The only exception is the explicit `KIMI_MODEL_*` channel; see [Define a model from environment variables](./env-vars.md#define-a-model-from-environment-variables-kimi_model_). ::: -The CLI currently reads a single user-level config file and has no project-level config file mechanism. To isolate config between different projects, point `KIMI_CODE_HOME` at different data directories — see [Common scenarios](#common-scenarios) below. +The CLI currently reads a single user-level config file and has no project-level config file mechanism. To isolate config between different projects, point `KIMI_CODE_HOME` at different data directories; see [Common scenarios](#common-scenarios) below. ## Provider credentials @@ -37,15 +37,15 @@ Provider credentials (`api_key`, `base_url`) follow their own resolution rules, For a single provider, credentials are resolved in this order: -1. `[providers.].api_key` — key written directly in the config file; highest priority -2. The matching key inside the `[providers..env]` sub-table (`KIMI_API_KEY`, `ANTHROPIC_API_KEY`, etc.) — consulted only when `api_key` is empty -3. If both are absent — startup fails with an error indicating the provider is missing credentials +1. `[providers.].api_key`: key written directly in the config file; highest priority +2. The matching key inside the `[providers..env]` sub-table (`KIMI_API_KEY`, `ANTHROPIC_API_KEY`, etc.): consulted only when `api_key` is empty +3. If both are absent, startup fails with an error indicating the provider is missing credentials `base_url` is resolved the same way: first `[providers.].base_url`, then the `*_BASE_URL` key in `[providers..env]`. -> The `[providers..env]` sub-table is just a TOML section in the config file — it does not write anything into the shell environment. It is only consulted when the corresponding direct field (`api_key` / `base_url`) is empty. +> The `[providers..env]` sub-table is just a TOML section in the config file and does not write anything into the shell environment. It is only consulted when the corresponding direct field (`api_key` / `base_url`) is empty. -For the full list of credential key names, see [Environment variables: provider credential key names](./env-vars.md#provider-credential-key-names-written-in-config-toml). +For the full list of credential key names, see [Environment variables: provider credential key names](./env-vars.md#provider-credential-key-names-written-in-configtoml). ## Command-line options @@ -76,13 +76,13 @@ Mutual exclusion rules (startup fails if violated): ## Common scenarios -**Isolated test environment** — use a separate data directory to avoid polluting the main config and sessions: +**Isolated test environment**: use a separate data directory to avoid polluting the main config and sessions: ```sh KIMI_CODE_HOME="$PWD/.kimi-sandbox" kimi ``` -**One-off test key** — since provider credentials are read only from the config file, write a test key into the `env` sub-table: +**One-off test key**: since provider credentials are read only from the config file, write a test key into the `env` sub-table: ```toml [providers.kimi.env] diff --git a/docs/en/configuration/providers.md b/docs/en/configuration/providers.md index 43aeabb4427..ba7324c349e 100644 --- a/docs/en/configuration/providers.md +++ b/docs/en/configuration/providers.md @@ -1,6 +1,6 @@ # Providers and models -Kimi Code CLI supports connecting to multiple LLM platforms simultaneously — one-click login via the Kimi Code managed service, connecting Claude with an Anthropic API key, or connecting third-party inference services via the OpenAI-compatible protocol. Each provider corresponds to a specific API protocol; models are declared on top of providers with their own name, context length, and capabilities. This page explains how to configure each type of provider in `config.toml`. +Kimi Code CLI supports connecting to multiple LLM platforms simultaneously: one-click login via the Kimi Code managed service, connecting Claude with an Anthropic API key, or connecting third-party inference services via the OpenAI-compatible protocol. Each provider corresponds to a specific API protocol; models are declared on top of providers with their own name, context length, and capabilities. This page explains how to configure each type of provider in `config.toml`. ## Supported provider types @@ -8,21 +8,23 @@ The `type` field in the `providers` table determines which protocol implementati | Type | Protocol | Typical use | | --- | --- | --- | -| `kimi` | OpenAI-compatible | Kimi Code managed service, Kimi Platform API key | -| `anthropic` | Anthropic Messages | Claude model family | -| `openai` | OpenAI Chat Completions | OpenAI and compatible services, DeepSeek, Qwen, etc. | -| `openai_responses` | OpenAI Responses API | OpenAI's newer Responses interface | -| `google-genai` | Google GenAI | Gemini API | -| `vertexai` | Google GenAI on Vertex | Google Cloud Vertex AI | +| [`kimi`](#kimi) | OpenAI-compatible | Kimi Code managed service, Kimi Platform API key | +| [`anthropic`](#anthropic) | Anthropic Messages | Claude model family | +| [`openai`](#openai) | OpenAI Chat Completions | OpenAI and compatible services, DeepSeek, Qwen, etc. | +| [`openai_responses`](#openai_responses) | OpenAI Responses API | OpenAI's newer Responses interface | +| [`google-genai`](#google-genai) | Google GenAI | Gemini API | +| [`vertexai`](#vertexai) | Google GenAI on Vertex | Google Cloud Vertex AI | -All providers communicate with models in streaming mode by default. Capabilities such as thinking, vision, and tool use are matched automatically by model name prefix — you typically do not need to declare them manually. +All providers communicate with models in streaming mode by default. Capabilities such as thinking, vision, and tool use are matched automatically by model name prefix, so you typically do not need to declare them manually. -**Credential priority**: `api_key` direct field > `[providers..env]` sub-table key > if both are absent, startup fails with an error. The CLI does not fall back to shell environment variables for credentials — see [Config overrides: provider credentials](./overrides.md#provider-credentials). +**Credential priority**: `api_key` direct field > `[providers..env]` sub-table key > if both are absent, startup fails with an error. The CLI does not fall back to shell environment variables for credentials. See [Config overrides: provider credentials](./overrides.md#provider-credentials). ## `/provider` — interactive provider management Prefer not to edit TOML by hand? Type `/provider` in the TUI to open the **provider manager**, where you can interactively add or remove providers. +![The /provider provider manager](../../media/provider-manager.jpg) + The manager displays providers as a list of entries grouped by source. Navigation: - ↑/↓ to move the cursor, ←/→ to page @@ -55,7 +57,7 @@ base_url = "https://api.moonshot.ai/v1" api_key = "sk-xxxxx" ``` -> When using the Kimi Code managed service, running `/login` automatically configures `base_url` and credentials — no manual setup needed. +> When using the Kimi Code managed service, running `/login` automatically configures `base_url` and credentials, so no manual setup is needed. ## `anthropic` @@ -134,7 +136,7 @@ base_url = "https://your-gateway.example" Shares the same implementation as `google-genai`; setting `type = "vertexai"` switches to the Vertex AI access path. -Authentication follows the standard Google Cloud ADC flow (`gcloud auth application-default login` or a `GOOGLE_APPLICATION_CREDENTIALS` service account JSON) — this part is unrelated to Kimi Code. **The project ID and region must be written in the `[providers.vertexai.env]` sub-table** — simply `export GOOGLE_CLOUD_PROJECT` in the shell will not be read by the CLI. +Authentication follows the standard Google Cloud ADC flow (`gcloud auth application-default login` or a `GOOGLE_APPLICATION_CREDENTIALS` service account JSON); this part is unrelated to Kimi Code. **The project ID and region must be written in the `[providers.vertexai.env]` sub-table**. Simply `export GOOGLE_CLOUD_PROJECT` in the shell will not be read by the CLI. ```toml [providers.vertexai] @@ -150,11 +152,11 @@ gcloud auth application-default login # one-time authentication kimi ``` -To route Vertex requests through a custom (e.g. proxied) endpoint, set `base_url` (or the `GOOGLE_VERTEX_BASE_URL` env var); when omitted, the SDK default regional `*-aiplatform.googleapis.com` host is used. As with `google-genai`, give the host root only — the SDK appends `/v1beta1/publishers/google/models/…` itself. +To route Vertex requests through a custom (e.g. proxied) endpoint, set `base_url` (or the `GOOGLE_VERTEX_BASE_URL` env var); when omitted, the SDK default regional `*-aiplatform.googleapis.com` host is used. As with `google-genai`, give the host root only. The SDK appends `/v1beta1/publishers/google/models/…` itself. ## OAuth and credential injection -The Kimi Code managed service uses OAuth rather than static API keys. After running `/login`, the built-in authentication toolchain automatically writes and refreshes credentials — no manual configuration is needed in `config.toml` for this. +The Kimi Code managed service uses OAuth rather than static API keys. After running `/login`, the built-in authentication toolchain automatically writes and refreshes credentials, so no manual configuration is needed in `config.toml` for this. ## Next steps diff --git a/docs/en/customization/agents.md b/docs/en/customization/agents.md index f3e0d3d1a6f..743ab92f8a8 100644 --- a/docs/en/customization/agents.md +++ b/docs/en/customization/agents.md @@ -1,6 +1,6 @@ # Agents and Sub-Agents -Every session in Kimi Code CLI is driven by a **main Agent**. The main Agent understands the user's intent, plans steps, calls tools, and when needed dispatches **sub-agents** to handle more focused sub-tasks — for example, exploring an unfamiliar codebase, reviewing multiple implementations in parallel, or planning a large refactor without touching the main context. +Every session in Kimi Code CLI is driven by a **main Agent**. The main Agent understands the user's intent, plans steps, calls tools, and when needed dispatches **sub-agents** to handle more focused sub-tasks, such as exploring an unfamiliar codebase, reviewing multiple implementations in parallel, or planning a large refactor without touching the main context. A sub-agent receives a task description from the main Agent, works in its own isolated context, and then returns its conclusions. It does not communicate with the user directly, and its intermediate reasoning and tool call records do not mix into the main Agent's history. @@ -8,15 +8,23 @@ A sub-agent receives a task description from the main Agent, works in its own is Kimi Code CLI includes three built-in sub-agents, ready to use out of the box, each aimed at a different task shape: -- **`coder`**: The default sub-agent — a general-purpose software engineering assistant that can read and write files, execute commands, search code, and land concrete changes. +- **`coder`**: The default sub-agent, a general-purpose software engineering assistant that can read and write files, execute commands, search code, and land concrete changes. - **`explore`**: Dedicated to codebase exploration; performs read-only operations only and does not modify any files. Ideal for quickly searching, reading, and summarizing a repository without touching files. - **`plan`**: Dedicated to implementation planning and architecture design; even shell commands are not available, keeping the focus on "figuring out how to do something" rather than "actually doing it." -A `coder` sub-agent shares most of the main Agent's tool set: it can run shell commands in the background, maintain todo lists, enter Plan mode, and invoke Agent Skills. Built-in sub-agents cannot dispatch further sub-agents. By default a custom agent inherits the built-in delegation allowlist (`coder`, `explore`, `plan`), whose members cannot dispatch further either, so delegation chains always terminate — unbounded recursive spawning is impossible without an explicit opt-in. A custom agent can opt into deeper chains by declaring an explicit [`subagents`](#agent-file-format) allowlist. If a sub-agent finishes its turn while background tasks are still running, its run only reports completion after those tasks settle, so the parent receives the result after the underlying work has actually finished. +Beyond the three types, three conventions govern how sub-agents work: tool boundaries, delegation depth, and completion timing. + +A `coder` sub-agent shares most of the main Agent's tool set: it can run shell commands in the background, maintain todo lists, enter Plan mode, and invoke Agent Skills. The three built-in sub-agents cannot dispatch further sub-agents. + +By default a custom agent inherits the built-in delegation allowlist (`coder`, `explore`, `plan`), whose members cannot dispatch further either, so delegation chains always terminate and unbounded recursive spawning is impossible without an explicit opt-in. A custom agent can opt into deeper chains by declaring an explicit [`subagents`](#agent-file-format) allowlist. + +If a sub-agent finishes its turn while background tasks are still running, its run only reports completion after those tasks settle, so the parent receives the result after the underlying work has actually finished. ## How to Invoke -Sub-agents are scheduled automatically by the main Agent — based on task complexity, context consumption, and sub-task independence, they are dispatched at the right moment without the user having to specify one. +The full pipeline has only three stages (dispatch, approval, and collection), and none of them require manual management. + +Sub-agents are scheduled automatically by the main Agent, based on task complexity, context consumption, and sub-task independence. They are dispatched at the right moment without the user having to specify one. Each dispatch is presented in the terminal as an approval request (unless it matches an allow rule or Ask When Needed mode is active), giving you a chance to review the task description. You can also instruct the main Agent directly in conversation to use a specific sub-agent, for example: "Use explore to map out the relevant files before making any changes." @@ -31,7 +39,7 @@ This isolation provides two benefits: - **The main Agent's context stays lean** and is not filled with large volumes of exploratory logs during long sessions. - **Multiple sub-agents can run in parallel** without interfering with each other. -Note that each sub-agent independently consumes model tokens. For simple tasks, there is no need to dispatch a sub-agent — the main Agent handles them more economically. +Note that each sub-agent independently consumes model tokens. For simple tasks, there is no need to dispatch a sub-agent; the main Agent handles them more economically. ## Permission Inheritance @@ -41,7 +49,7 @@ If you need a particular type of tool to be permanently unavailable inside sub-a ## Custom Agents -Beyond the three built-in sub-agents, you can define your own agents as Markdown files. Each file describes one agent: the frontmatter (YAML metadata at the top of the file) declares its name, description, and tool access, and the file body is its system prompt. Custom agents can be delegated to as sub-agents — the main Agent discovers them automatically alongside the built-in ones — or selected as the main Agent at startup. +Beyond the three built-in sub-agents, you can define your own agents as Markdown files. Each file describes one agent: the frontmatter (YAML metadata at the top of the file) declares its name, description, and tool access, and the file body is its system prompt. The main Agent discovers custom agents automatically alongside the built-in ones, so they can be delegated to as sub-agents. They can also be selected as the main Agent at startup. ### Agent Locations @@ -65,10 +73,12 @@ extra_agent_dirs = ["~/team-agents", ".agents/team-agents"] **Plugin level**: directories declared in an enabled plugin's manifest `agents` field (when omitted, the `agents/` directory under the plugin root is picked up automatically); see [Plugin Agents](./plugins.md#plugin-agents). Plugin agents outrank only the built-in agents. -**Built-in agents** are distributed with the CLI and have the lowest priority. A directory-discovered file does not override a same-name built-in Agent unless its frontmatter declares `override: true`. A file loaded through `--agent-file` is treated as explicit launch intent, may override a same-name built-in Agent, outranks every directory scope, and applies to the current launch only. Separately, `$KIMI_CODE_HOME/SYSTEM.md` permanently overrides the default main agent's system prompt (it is not part of agent-file discovery); its precedence interactions are covered in the SYSTEM.md section below. +**Built-in agents** are distributed with the CLI and have the lowest priority. A directory-discovered file does not override a same-name built-in Agent unless its frontmatter declares `override: true`. A file loaded through `--agent-file` is treated as explicit launch intent, may override a same-name built-in Agent, outranks every directory scope, and applies to the current launch only. + +Separately, `$KIMI_CODE_HOME/SYSTEM.md` permanently overrides the default main agent's system prompt; it is not part of agent-file discovery. Its precedence interactions are covered in the [SYSTEM.md section](#overriding-the-main-agents-system-prompt-with-systemmd). ::: warning Trust model -Agent files are prompt configuration, and project-level files come from the repository itself — including repositories you have just cloned and do not trust yet. A project-scoped file can take over a built-in agent entirely: naming it `agent.md` with `override: true` replaces the **default main agent's whole system prompt**, and `coder.md` with `override: true` replaces the default sub-agent type. Unlike `AGENTS.md` content — which is injected into the prompt as reference data — an override file *is* the system prompt, and a file without a `tools` list keeps every tool. Review `.kimi-code/agents/` and `.agents/agents/` in unfamiliar repositories with the same caution you would apply to scripts, before running Kimi Code inside them. +Agent files are prompt configuration, and project-level files come from the repository itself, including repositories you have just cloned and do not trust yet. A project-scoped file can take over a built-in agent entirely: naming it `agent.md` with `override: true` replaces the **default main agent's whole system prompt**, and `coder.md` with `override: true` replaces the default sub-agent type. Unlike `AGENTS.md` content, which is injected into the prompt as reference data, an override file *is* the system prompt, and a file without a `tools` list keeps every tool. Review `.kimi-code/agents/` and `.agents/agents/` in unfamiliar repositories with the same caution you would apply to scripts, before running Kimi Code inside them. ::: ### Agent File Format @@ -93,23 +103,29 @@ disallowedTools: You are a strict code reviewer. Read the diff, then report findings grouped by severity… ``` +Frontmatter fields: + | Field | Required | Description | | --- | --- | --- | -| `name` | no | Unique identifier in kebab-case. Defaults to the file name without its extension (`review.md` → `review`); a file whose resolved name is missing or not kebab-case is skipped with a warning | -| `description` | yes | What the agent does. Shown to the main Agent when it picks a sub-agent, so write it to guide delegation decisions | +| `name` | no | Unique kebab-case identifier; defaults to the file name without its extension. A file with a missing or non-kebab-case name is skipped with a warning | +| `description` | yes | What the agent does, shown to the main Agent when it picks a sub-agent. Write it to guide delegation decisions | | `whenToUse` | no | Extra hint describing when the agent should be used | -| `override` | no | Whether this file may replace a same-name built-in Agent. Defaults to `false`; `--agent-file` is already explicit and does not require this field | -| `tools` | no | Allowlist of tool names such as `Read` or `Bash`; MCP tools are matched with globs such as `mcp__github__*`. Accepts a YAML list or a comma-separated string (`tools: Read, Grep`). Omit to allow all tools; a lone `*` also allows all tools; an empty list (`tools: []`) disables all tools | +| `override` | no | Whether the file may replace a same-name built-in Agent; defaults to `false`. `--agent-file` does not need it | +| `tools` | no | Tool allowlist (`Read`, `Bash`); MCP tools match as globs (`mcp__github__*`). YAML list or comma-separated string; omit or use a lone `*` to allow all tools, `tools: []` disables all tools | | `disallowedTools` | no | Denylist with the same syntax and matching rules, applied after `tools` | -| `subagents` | no | Allowlist of sub-agent names this agent may delegate to, with the same syntax as `tools` (YAML list or comma-separated string). Omit to inherit the default agent's allowlist (built-in default: `coder`, `explore`, `plan`, whose members cannot delegate further, so inherited chains always terminate); a lone `*` allows every type. The main agent's effective allowlist additionally includes every discovered custom agent, so custom agents stay delegatable by default | +| `subagents` | no | Sub-agent allowlist, same syntax as `tools`. Omit to inherit the built-in default (`coder`, `explore`, `plan`); a lone `*` allows every type. The main agent's effective list also includes every discovered custom agent | + +Built-in and user tools match by exact, case-sensitive name; entries starting with `mcp__` match MCP tools as globs. Three entry shapes never match anything and are reported with a warning when the profile takes effect: -Built-in and user tools match by exact, case-sensitive name; entries starting with `mcp__` match MCP tools as globs. Three entry shapes never match anything and are reported with a warning when the profile takes effect: a wildcard outside an `mcp__` pattern (a bare `*` in `disallowedTools` disables nothing), an `mcp__` literal that is not a full `mcp____` name (`mcp__github` matches nothing — use `mcp__github__*` for the whole server), and a name no registered or built-in tool has (usually a typo, such as `read` instead of `Read`). +- A wildcard outside an `mcp__` pattern: a bare `*` in `disallowedTools` disables nothing. +- An incomplete `mcp__` literal: `mcp__github` matches nothing; use `mcp__github__*` for the whole server. +- A name no registered or built-in tool has, usually a typo such as `read` instead of `Read`. -The body is the agent's system prompt, and it is rendered as a template each time the prompt is built: `${var}` placeholders substitute live context values — unknown variables stay verbatim, a bare `$` is never special, and a variable with no context value renders as an empty string. `${base_prompt}` embeds the effective default system prompt (the built-in default, or your `SYSTEM.md` override when present), so a file can wrap the default behavior instead of replacing it. If the file replaces the default prompt but should still honor instructions contributed by enabled plugins, place `${plugin_sections}` where those instructions should appear. The available variables are listed in the SYSTEM.md section below. +The body is the agent's system prompt, and it is rendered as a template each time the prompt is built: `${var}` placeholders substitute live context values. Unknown variables stay verbatim, a bare `$` is never special, and a variable with no context value renders as an empty string. `${base_prompt}` embeds the effective default system prompt (the built-in default, or your `SYSTEM.md` override when present), so a file can wrap the default behavior instead of replacing it. If the file replaces the default prompt but should still honor instructions contributed by enabled plugins, place `${plugin_sections}` where those instructions should appear. The available variables are listed in the [SYSTEM.md section](#overriding-the-main-agents-system-prompt-with-systemmd). -Unknown fields are ignored, so newer files stay readable by older versions. Fields from other agent tools (such as Claude Code's `model` or OpenCode's `mode`) are ignored the same way, the comma-separated `tools` form keeps Claude Code-style agent files loadable, and a missing `name` falls back to the file name so OpenCode-style files load too — a minimal file with `description` and a body works across tools. +Unknown fields are ignored, so newer files stay readable by older versions. Fields from other agent tools (such as Claude Code's `model` or OpenCode's `mode`) are ignored the same way, the comma-separated `tools` form keeps Claude Code-style agent files loadable, and a missing `name` falls back to the file name so OpenCode-style files load too. A minimal file with `description` and a body works across tools. -A file with invalid content discovered in a directory is skipped with a warning and does not affect other files. A file passed explicitly via `--agent-file` must be valid — otherwise the CLI reports the error and exits. +A file with invalid content discovered in a directory is skipped with a warning and does not affect other files. A file passed explicitly via `--agent-file` must be valid, otherwise the CLI reports the error and exits. ::: warning Note `tools` and `disallowedTools` shape the tools shown to the model and are enforced again before execution. `subagents` works the same way: the `Agent` tool lists only the sub-agent types the caller may delegate to, and both `Agent` and `AgentSwarm` re-check the allowlist before dispatching; resuming an existing sub-agent is exempt. Permission rules remain a separate control for operations that require approval. @@ -124,7 +140,7 @@ Two CLI flags select which agent drives a new session, in both print mode (`kimi - **`--agent `**: Start the session with the named agent as the main Agent. The name can refer to a built-in agent or to any discovered file; an unknown name fails with an error listing the available agents. - **`--agent-file `**: Load one agent file at the highest priority for this launch and start with it. The flag accepts exactly one file: it cannot be repeated, and it cannot be combined with `--agent`. -Both flags only apply when starting a new session — neither can be combined with `--session`/`--continue`. The agent is bound at session creation, and resuming restores the bound agent automatically, so no flag is needed (or allowed) on resume. +Both flags only apply when starting a new session: neither can be combined with `--session`/`--continue`. The agent is bound at session creation, and resuming restores the bound agent automatically, so no flag is needed (or allowed) on resume. For example: @@ -139,11 +155,17 @@ For main-agent customization, reference `${base_prompt}` in the body so the envi ### Overriding the main agent's system prompt with SYSTEM.md -To override the main agent's system prompt permanently — without passing `--agent` or `--agent-file` on every launch — write a `$KIMI_CODE_HOME/SYSTEM.md` file (default: `~/.kimi-code/SYSTEM.md`; it moves with `KIMI_CODE_HOME`). While the file exists and is non-empty, it replaces the built-in default main agent's system prompt in full — and only the prompt: the description, tool set, and sub-agent delegation allowlist are inherited from the built-in defaults. SYSTEM.md takes effect in every launch mode, including interactive TUI sessions. +To override the main agent's system prompt permanently, without passing `--agent` or `--agent-file` on every launch, write a `$KIMI_CODE_HOME/SYSTEM.md` file (default: `~/.kimi-code/SYSTEM.md`; it moves with `KIMI_CODE_HOME`). While the file exists and is non-empty, it fully replaces the built-in default main agent's system prompt (and only the prompt: the description, tool set, and sub-agent delegation allowlist are inherited from the built-in defaults). SYSTEM.md takes effect in every launch mode, including interactive TUI sessions. + +SYSTEM.md is a plain Markdown body; no frontmatter is required or read. A missing or empty file has no effect, and a read failure falls back to the built-in prompt with a warning. + +Explicit intent still outranks it: -SYSTEM.md is a plain Markdown body — no frontmatter is required or read. A missing or empty file has no effect, and a read failure falls back to the built-in prompt with a warning. Explicit intent still outranks it: a project-scoped same-name agent file declaring `override: true` and any file passed via `--agent-file` take precedence, and selecting another agent with `--agent` bypasses it entirely. Within the user scope itself, SYSTEM.md wins over a same-name file discovered in the `agents/` directories. +- A project-scoped same-name agent file declaring `override: true`, and any file passed via `--agent-file`, rank ahead of SYSTEM.md. +- Selecting another agent with `--agent` bypasses SYSTEM.md entirely. +- Within the user scope itself, SYSTEM.md wins over a same-name file discovered in the `agents/` directories. -Like the body of a regular agent file, SYSTEM.md is rendered as a template each time the prompt is built — `${var}` placeholders in the body are substituted from the live context: +Like the body of a regular agent file, SYSTEM.md is rendered as a template each time the prompt is built, and `${var}` placeholders in the body are substituted from the live context: | Variable | Content | | --- | --- | @@ -153,11 +175,12 @@ Like the body of a regular agent file, SYSTEM.md is rendered as a template each | `${cwd_listing}` | Listing of the working directory | | `${os}` | Operating system kind | | `${shell}` | Shell name and path, for example `bash (\`/bin/bash\`)` | +| `${now}` | Current time (ISO format) | | `${additional_dirs_info}` | Additional directories added to the workspace; empty when there are none | -| `${base_prompt}` | The default system prompt. Inside `SYSTEM.md` itself this is the built-in default; inside an agent file it is the effective default — the built-in default, or your `SYSTEM.md` override when present | +| `${base_prompt}` | The default system prompt. Inside `SYSTEM.md` itself this is the built-in default; inside an agent file it is the effective default (the built-in default, or your `SYSTEM.md` override when present) | | `${plugin_sections}` | A complete Plugin Instructions block contributed by enabled plugins; empty when no enabled plugin contributes instructions | -Unknown variables stay verbatim, a bare `$` is never special, and a variable with no context value renders as an empty string. Four pre-composed blocks — `${windows_notes}`, `${additional_dirs_section}`, `${skills_section}`, and `${plugin_sections}` — render the matching built-in prompt section, or an empty string when it does not apply. The built-in default prompt already includes `${plugin_sections}`, so do not add it again when `${base_prompt}` already expands to that prompt. The variables are enough to rebuild the skeleton of the built-in prompt, for example: +Unknown variables stay verbatim, a bare `$` is never special, and a variable with no context value renders as an empty string. Four pre-composed blocks (`${windows_notes}`, `${additional_dirs_section}`, `${skills_section}`, and `${plugin_sections}`) render the matching built-in prompt section, or an empty string when it does not apply. The built-in default prompt already includes `${plugin_sections}`, so do not add it again when `${base_prompt}` already expands to that prompt. The variables are enough to rebuild the skeleton of the built-in prompt, for example: ```markdown You are Kimi, running at ${cwd} on ${os}. diff --git a/docs/en/customization/hooks.md b/docs/en/customization/hooks.md index 680b1b9817e..72ac0d77a7c 100644 --- a/docs/en/customization/hooks.md +++ b/docs/en/customization/hooks.md @@ -17,7 +17,7 @@ The script's response is determined by two things: - **Exit code**: `0` means allow, `2` means block, other non-zero values default to allow - **Standard output** (stdout): can include explanatory text -Even if the script errors or times out, the CLI **will not interrupt your work** as a result — this "allow on failure" design is called fail-open, preventing hook errors from becoming blockers. +Even if the script errors or times out, the CLI **will not interrupt your work** as a result. This "allow on failure" design is called fail-open, preventing hook errors from becoming blockers. ::: warning Note Precisely because of fail-open, Hooks are suitable for alerts and lightweight interception, but **should not be used as the sole security barrier**. For truly high-risk operations, rely on permission approvals and manual confirmation. @@ -43,7 +43,7 @@ All hook rules are written in the `[[hooks]]` array in `~/.kimi-code/config.toml | Field | Type | Required | Description | | --- | --- | --- | --- | -| `event` | `string` | Yes | Trigger event name; must be one of the entries in the "Event Reference" table below | +| `event` | `string` | Yes | Trigger event name; must be one of the events in the [event reference](#event-reference) | | `matcher` | `string` | No | A regular expression to filter event targets; if omitted, matches all | | `command` | `string` | Yes | The shell command to run when triggered | | `timeout` | `integer` | No | Timeout in seconds, range 1–600; defaults to 30 seconds | @@ -52,7 +52,14 @@ All hook rules are written in the `[[hooks]]` array in `~/.kimi-code/config.toml **When multiple rules match the same event**, all matching hooks run in parallel; multiple rules with identical `command` values run only once. -The working directory for hook commands is the current session's project directory. On non-Windows platforms, hook processes are placed in a separate process group; on timeout, a signal is sent first to give the process a chance to clean up, then it is forcibly terminated. +The working directory for hook commands is the current session's project directory. + +
+Process group and timeout handling + +On non-Windows platforms, hook processes run in a separate process group; on timeout, the CLI first sends a signal to give the script a chance to clean up, then forcibly terminates it. + +
### Event Data Format @@ -68,7 +75,7 @@ Each time a hook triggers, the CLI passes the following base information to the } ``` -Specific events will also include additional fields (such as tool name and command content); see the event reference below. All field names use snake_case. +Specific events will also include additional fields (such as tool name and command content); see the [event reference](#event-reference). All field names use snake_case. ## Return Values @@ -93,33 +100,33 @@ You can also return a JSON object via stdout to block: ``` ::: info Which events support blocking? -Only **blockable events** (`PreToolUse`, `Stop`, `UserPromptSubmit`) have return values that affect the main flow. All other events are **observation-only events** — they fire and forget; the main flow is unaffected regardless of what the script returns. +Only **blockable events** (`PreToolUse`, `Stop`, `UserPromptSubmit`) have return values that affect the main flow. All other events are **observation-only events**: they fire and forget, and the main flow is unaffected regardless of what the script returns. ::: ## Event Reference | Event | Matcher matches | Supports blocking? | Description | | --- | --- | --- | --- | -| `UserPromptSubmit` | The text submitted by the user | ✓ | Triggered when the user sends a message; returned text is appended to context; if blocked, the model is not called for this turn | -| `UserPromptQueued` | The queued prompt text | — | Triggered when a message is queued while a turn is still running; the payload includes `prompt_id`, `prompt`, and `queue_length` (observation only) | +| `UserPromptSubmit` | The text submitted by the user | ✓ | Triggered when the user sends a message; returned text is appended to context; blocking skips the model call this turn | +| `UserPromptQueued` | The queued prompt text | — | Triggered when a message is queued while a turn is still running; payload includes `prompt_id`, `prompt`, `queue_length` | | `PreToolUse` | Tool name | ✓ | Triggered before a tool call (before permission checks); the tool will not execute if blocked | -| `Stop` | Empty string | ✓ | Triggered when the model is about to end the current turn; if blocked, a message can be appended to let the model continue | -| `TurnStarted` | Turn origin kind (e.g. `user`, `task`, `system_trigger`) | — | Triggered when a new turn begins; the payload includes `turn_id`, `origin_kind`, `origin_name`, and `prompt` (observation only) | -| `PostToolUse` | Tool name | — | Triggered after a tool executes successfully (observation only) | -| `PostToolUseFailure` | Tool name | — | Triggered after a tool fails or is blocked (observation only) | -| `PermissionRequest` | Tool name | — | Triggered just before waiting for user approval (observation only) | -| `PermissionResult` | Tool name | — | Triggered after approval completes (observation only) | -| `SessionStart` | `startup` or `resume` | — | Triggered after a new session starts or a previous session resumes; the payload includes `source`, `model`, and `profile` | +| `Stop` | Empty string | ✓ | Triggered when the model is about to end the turn; if blocked, a message can be appended to let the model continue | +| `TurnStarted` | Turn origin kind (e.g. `user`, `task`, `system_trigger`) | — | Triggered when a new turn begins; payload includes `turn_id`, `origin_kind`, `origin_name`, `prompt` | +| `PostToolUse` | Tool name | — | Triggered after a tool executes successfully | +| `PostToolUseFailure` | Tool name | — | Triggered after a tool fails or is blocked | +| `PermissionRequest` | Tool name | — | Triggered just before waiting for user approval | +| `PermissionResult` | Tool name | — | Triggered after approval completes | +| `SessionStart` | `startup` or `resume` | — | Triggered after a session starts or resumes; payload includes `source`, `model`, `profile` | | `SessionEnd` | `exit` or `archive` | — | Triggered after a session closes; `archive` means the session was archived rather than exited | -| `SessionHeartbeat` | Empty string | — | Triggered every 60 seconds while the session is alive; the timer only runs when this event is configured. The payload includes `uptime_ms` (observation only) | +| `SessionHeartbeat` | Empty string | — | Triggered every 60 seconds while the session is alive; the timer runs only when this event is configured; payload includes `uptime_ms` | | `SubagentStart` | Sub-agent name | — | Triggered before a sub-agent starts running | -| `SubagentStop` | Sub-agent name | — | Triggered after a sub-agent completes successfully (observation only) | -| `TaskStarted` | Task kind (`agent`, `process`, or `question`) | — | Triggered when a background task starts; the payload includes `task_id`, `description`, and `detached` (observation only) | -| `StopFailure` | Error type | — | Triggered after the current turn fails due to an error (observation only) | -| `Interrupt` | Empty string | — | Triggered when the user interrupts the current turn (e.g. pressing Esc); not fired for timeouts or other programmatic aborts. `Stop` does not fire on interrupts, so this event fires instead. The payload includes a `reason` field (observation only) | +| `SubagentStop` | Sub-agent name | — | Triggered after a sub-agent completes successfully | +| `TaskStarted` | Task kind (`agent`, `process`, or `question`) | — | Triggered when a background task starts; payload includes `task_id`, `description`, `detached` | +| `StopFailure` | Error type | — | Triggered after the current turn fails due to an error | +| `Interrupt` | Empty string | — | Triggered when the user interrupts the turn (e.g. pressing Esc); not fired for timeouts or programmatic aborts; fires in place of `Stop`; payload includes `reason` | | `PreCompact` | `manual` or `auto` | — | Triggered before context compaction begins; return values are completely ignored | -| `PostCompact` | `manual` or `auto` | — | Triggered after context compaction completes (observation only) | -| `Notification` | Notification type (e.g. `task.completed`) | — | Triggered when a background task status changes (observation only) | +| `PostCompact` | `manual` or `auto` | — | Triggered after context compaction completes | +| `Notification` | Notification type (e.g. `task.completed`) | — | Triggered when a background task status changes | ## Example: Blocking Dangerous Shell Commands @@ -154,7 +161,7 @@ process.stdin.on('end', () => { After blocking, Kimi Code CLI writes the blocking reason back into the context, and the model can use this to choose a safer alternative. ::: warning Note -This example only demonstrates the blocking mechanism — it is not a production-grade security parser. Real scenarios are better served by whitelists, or a dedicated shell parser to handle quoting, variable expansion, and multi-command sequences. +This example only demonstrates the blocking mechanism and is not a production-grade security parser. Real scenarios are better served by whitelists, or a dedicated shell parser to handle quoting, variable expansion, and multi-command sequences. ::: ## Next steps diff --git a/docs/en/customization/mcp.md b/docs/en/customization/mcp.md index be65fd48b49..1ef81c5cdd8 100644 --- a/docs/en/customization/mcp.md +++ b/docs/en/customization/mcp.md @@ -1,6 +1,6 @@ # Model Context Protocol -[Model Context Protocol (MCP)](https://modelcontextprotocol.io/) is an open protocol that lets models safely call tools exposed by external processes or services — for example, reading GitHub issues, querying databases, or operating the local file system. Kimi Code CLI acts as an MCP client to connect these external tools and exposes them to the Agent alongside built-in tools (`Read`, `Bash`, `Grep`, etc.) with no behavioral difference. +[Model Context Protocol (MCP)](https://modelcontextprotocol.io/) is an open protocol that lets models safely call tools exposed by external processes or services: reading GitHub issues, querying databases, or operating the local file system. Kimi Code CLI acts as an MCP client to connect these external tools and exposes them to the Agent alongside built-in tools (`Read`, `Bash`, `Grep`, etc.) with no behavioral difference. ## Connection Methods @@ -21,7 +21,7 @@ Entries with the same name: the project-level entry takes precedence and overrid Run `/mcp-config` in the TUI to interactively add, edit, or delete servers without manually editing the JSON file. Run `/mcp` to view the connection status of all current servers. -Deleting a server from the configuration does not interrupt open sessions: the server stays listed in `/mcp` as `removed`, its tools remain visible there, and calls to them fail with a removal notice, while new sessions do not register the tools at all. Conversely, a server added mid-session — by editing `mcp.json` or installing a plugin — is not registered in already-open sessions; it only joins sessions created later. +Deleting a server from the configuration does not interrupt open sessions: the server stays listed in `/mcp` as `removed`, its tools remain visible there, and calls to them fail with a removal notice, while new sessions do not register the tools at all. Conversely, a server added mid-session by editing `mcp.json` or installing a plugin is not registered in already-open sessions; it only joins sessions created later. When Kimi Code finds project-level MCP servers in an untrusted folder, it shows each server's transport and launch target in the workspace trust prompt. The prompt defaults to `Trust this folder`; review the listed command and arguments or remote URL before confirming. Trusting the folder enables the project-level MCP servers for that workspace. @@ -65,7 +65,7 @@ You do not have to set the connection timeout or the single tool-call timeout pe HTTP and SSE servers support providing static credentials via `headers` or `bearerTokenEnvVar`. When OAuth is needed, run `/mcp-config login ` to complete browser-based authorization. -Plugins can also declare MCP servers in their manifest. Servers declared by a plugin are enabled by default and can be disabled or re-enabled in `/plugins`: disabling or removing stops the tools in open sessions — calls fail with a removal notice — and adding or enabling a server connects it in open sessions right away. See [Plugins](./plugins.md#mcp-servers-in-plugins) for details. +Plugins can also declare MCP servers in their manifest. Servers declared by a plugin are enabled by default and can be disabled or re-enabled in `/plugins`: disabling or removing one makes calls from open sessions fail with a removal notice, and adding or enabling a server connects it in open sessions right away. See [Plugins](./plugins.md#mcp-servers-in-plugins) for details. ::: warning Note stdio entries in a project-level `.kimi-code/mcp.json` execute local commands when a session starts. Only enable these in repositories you trust. @@ -100,7 +100,7 @@ When connecting to external MCP servers, be aware of: - Keep manual approval for high-risk tools (file writes, command execution, etc.); avoid using `mcp__*` wildcards to allow all tools at once ::: warning Note -In Ask When Needed mode, MCP tool calls are automatically approved. Only use this mode when you fully trust the MCP servers you have connected. +In [Ask When Needed mode](../guides/interaction.md#the-three-permission-modes), MCP tool calls are automatically approved. Only use this mode when you fully trust the MCP servers you have connected. ::: ## Next steps diff --git a/docs/en/customization/plugins.md b/docs/en/customization/plugins.md index 760e0155aa5..c3e8018298e 100644 --- a/docs/en/customization/plugins.md +++ b/docs/en/customization/plugins.md @@ -1,6 +1,6 @@ # Plugins -Plugins package reusable Kimi Code CLI capabilities into installable units — they can add [Agent Skills](./skills.md), custom [agents](./agents.md), automatically load a specified Skill at session start, contribute system-prompt instructions, and declare MCP servers to provide real tool capabilities. They are ideal for sharing workflows with a team, connecting to external services, or installing extensions from the [official plugins](#official-plugins). +Plugins package reusable Kimi Code CLI capabilities into installable units: they can add [Agent Skills](./skills.md), custom [agents](./agents.md), automatically load a specified Skill at session start, contribute system-prompt instructions, and declare MCP servers to provide real tool capabilities. They are ideal for sharing workflows with a team, connecting to external services, or installing extensions from the [official plugins](#official-plugins). ## Installation and Management @@ -20,7 +20,7 @@ Common keys: | `D` | Remove the selected installed plugin (Installed tab) | | `M` | Manage MCP servers for the selected plugin (Installed tab) | | `R` | Reload `installed.json` and all manifests (Installed tab) | -| `Enter` | Installed tab: install the available update, or view details if up to date · Official/Curated tab: install or update · Custom tab: install | +| `Enter` | Installed: update if available, or view details · Official/Curated: install or update · Custom: install | | `I` | View plugin details (Installed tab) | | `Esc` | Go back or cancel | @@ -95,13 +95,13 @@ All official plugins share the same installation and upgrade flow: Kimi WebBridge installs in two parts: after the steps above, you also need to [install the browser extension](#install-the-browser-extension) before it works. ::: -Official plugins do not update automatically — when an update is available, you'll be prompted the next time you use the old version. To upgrade, repeat the installation steps above. +Official plugins do not update automatically. When an update is available, you'll be prompted the next time you use the old version. To upgrade, repeat the installation steps above. ### Kimi Datasource -Kimi Datasource is the official Kimi Code data plugin, letting you query financial market data, financial news, macroeconomic indicators, corporate registration records, academic literature, Chinese laws and regulations, and official data from intergovernmental organizations in natural language — no manual API calls or data accounts required. +Kimi Datasource is the official Kimi Code data plugin, letting you query financial market data, financial news, macroeconomic indicators, corporate registration records, academic literature, Chinese laws and regulations, and official data from intergovernmental organizations in natural language. No manual API calls or data accounts required. -Sources include authoritative institutions and leading databases such as the World Bank, IMF, OECD, FRED, WHO, FAO, the National Bureau of Statistics of China, Wind, S&P Capital IQ, SEC EDGAR, Caixin, Xinhua Finance, and Hundsun Juyuan — all traceable to their original publishers. +Sources include authoritative institutions and leading databases such as the World Bank, IMF, OECD, FRED, WHO, FAO, the National Bureau of Statistics of China, Wind, S&P Capital IQ, SEC EDGAR, Caixin, Xinhua Finance, and Hundsun Juyuan, all traceable to their original publishers. You must first complete OAuth login with a Kimi Code account via `/login`; data queries consume your Kimi Code plan quota. @@ -137,7 +137,7 @@ Pull the annual report, standardized financial metrics, top-50 holders, and cons ::: ::: details **Financial news and industry data** — Tracking market hotspots or policy moves? -Query Caixin's market news, bond/fund/futures data, and listed-company supply-chain relationships, plus news, policies, announcements, and market flashes from the Xinhua Finance national financial information platform — authoritative and traceable sources. +Query Caixin's market news, bond/fund/futures data, and listed-company supply-chain relationships, plus news, policies, announcements, and market flashes from the Xinhua Finance national financial information platform. All sources are authoritative and traceable. ::: ::: details **Standards lookup** — Need to check compliance against Chinese standards? @@ -148,14 +148,14 @@ Look up national (GB), industry, local, and association standards by number or t | Category | Scope | |---|---| -| Stocks & financial markets | Well-known databases such as Wind, S&P Capital IQ, and SEC EDGAR, covering prices, technical indicators, financials and valuation, and consensus estimates across A-shares, HK, US, and other major markets, plus official filings for 8,000+ US-listed companies | -| Financial news & industry data | Well-known data platforms such as Caixin and Xinhua Finance, covering market news and flashes, listed-company announcements, regulatory policies, bond/fund/futures data, corporate credit violation records, and listed-company supply-chain relationships | -| Macroeconomics | Well-known databases such as the World Bank, IMF, OECD, FRED, and China's National Bureau of Statistics, plus official statistics from IGOs such as WHO and FAO, covering 50+ years of time series for 189 countries and China indicators at national/provincial/municipal levels: GDP, trade, population, exchange rates, CPI, balance of payments, GDP forecasts, and more | -| China standards | National (GB), industry, local, and association standards — numbers, titles, status, and details, with official full-text entry points for some national and public association standards | -| Corporate data | Business registration, equity chain, legal risk, and related-entity graph for mainland Chinese companies | -| Academic literature | Millions of papers across physics, mathematics, CS, quantitative finance, economics — including preprints | -| Legal | Yuandian Legal and other leading legal databases, covering Chinese laws, regulations, and judicial cases — statute search and detail lookup across all authority levels, plus ordinary and authoritative case search | -| Smart screening | Well-known databases such as Gildata, covering natural-language screening for stocks, funds, and fund managers, plus macro-industry data, research reports, announcements, and news | +| Stocks & financial markets | Wind, S&P Capital IQ, SEC EDGAR; A-share/HK/US quotes, indicators, financials, valuation, estimates; 8,000+ US-listed filings | +| Financial news & industry data | Caixin, Xinhua Finance; market news and flashes, company announcements, regulatory policy, bond/fund/futures data, credit-violation records, supply-chain ties | +| Macroeconomics | World Bank, IMF, OECD, FRED, China's NBS, WHO, FAO; 50+ years, 189 countries; national/provincial/municipal China indicators (GDP, trade, population, exchange rates, CPI, balance of payments) | +| China standards | National (GB), industry, local, and association standards: IDs, titles, status, details; official full text for some GB and public association standards | +| Corporate data | Registration, equity chain, legal risk, and related-entity graph for mainland Chinese companies | +| Academic literature | Millions of papers in physics, mathematics, CS, quantitative finance, economics, including preprints | +| Legal | Yuandian Legal and other leading legal databases: Chinese laws, regulations, judicial cases; statute search across authority levels; ordinary and authoritative case search | +| Smart screening | Gildata and other well-known databases: natural-language screening of stocks, funds, and fund managers; macro-industry data, research reports, announcements, news | #### Billing and limitations @@ -166,7 +166,7 @@ Look up national (GB), industry, local, and association standards by number or t ### Kimi WebBridge -Kimi WebBridge lets AI drive your browser directly — not an emulator, not a crawler, but the browser you use every day, with your login sessions and cookies. AI can open pages, read content, click buttons, fill in forms, and take screenshots just like you do, taking repetitive web operations off your hands. See the [Kimi WebBridge site](https://www.kimi.com/features/webbridge) for a product overview. +Kimi WebBridge lets AI drive your browser directly: not an emulator, not a crawler, but the browser you use every day, with your login sessions and cookies. AI can open pages, read content, click buttons, fill in forms, and take screenshots just like you do, taking repetitive web operations off your hands. See the [Kimi WebBridge site](https://www.kimi.com/features/webbridge) for a product overview. #### Install the browser extension @@ -195,7 +195,7 @@ Use this when you can't reach the stores: #### What you can do -- **Web automation**: Just say what you need — AI clicks through pages, fills in forms, reads content, and takes screenshots for you +- **Web automation**: Just say what you need, and AI clicks through pages, fills in forms, reads content, and takes screenshots for you - **Social trending research**: Automatically browse trending topics on X (Twitter), Weibo, and Xiaohongshu, open the top-liked posts one by one to screenshot and extract key viewpoints, then organize everything into a research library with topic suggestions - **Job listing collection**: Filter positions on recruiting sites by keyword, city, and job type, and organize titles, links, companies, salaries, and application methods into a table - **Competitive analysis**: Batch-question multiple AI products and collect their answers to build side-by-side comparison reports @@ -207,9 +207,9 @@ Kimi Computer Use lets AI operate your desktop apps directly, clicking, dragging #### Authorization (macOS) -The first time you use Kimi Computer Use after installation, it shows an authorization window — just follow the prompts: +The first time you use Kimi Computer Use after installation, it shows an authorization window. Just follow the prompts: -1. Click **Authorize** next to **Accessibility** and **Screen Recording**, and enable both permissions in System Settings — the former lets it perform clicks, typing, and scrolling; the latter lets it read screen content and locate UI elements +1. Click **Authorize** next to **Accessibility** and **Screen Recording**, and enable both permissions in System Settings: the former lets it perform clicks, typing, and scrolling; the latter lets it read screen content and locate UI elements 2. Turn on the **Kimi Code** switch under "Connect local agents", then restart Kimi Code for it to take effect
@@ -275,21 +275,25 @@ Supported fields: | --- | --- | | `name` | Required; serves as the plugin id. Must match `[a-z0-9][a-z0-9_-]{0,63}` | | `version`, `description`, `keywords`, `author`, `homepage`, `license` | Display metadata | -| `interface` | Fields shown in `/plugins`: `displayName`, `shortDescription`, `longDescription`, `developerName`, `websiteURL` | -| `skills` | One or more `./` paths; must be within the plugin root directory. When omitted, the `SKILL.md` in the root directory is treated as a single Skill root | -| `agents` | One or more `./` paths; must be within the plugin root directory and point to directories containing [agent files](./agents.md#custom-agents). When omitted, the `agents/` directory under the plugin root (if present) is picked up automatically | +| `interface` | Shown in `/plugins`: `displayName`, `shortDescription`, `longDescription`, `developerName`, `websiteURL` | +| `skills` | One or more `./` paths within the plugin root; if omitted, root `SKILL.md` is the single Skill root | +| `agents` | One or more `./` paths within the plugin root, pointing to [agent files](./agents.md#custom-agents); if omitted, `agents/` is auto-discovered | | `sessionStart.skill` | Loads the specified plugin Skill into the main Agent when a new or resumed session starts | | `skillInstructions` | Additional instructions appended whenever a Skill from this plugin is loaded | | `systemPrompt` | Inline instructions contributed to the agent's system prompt while the plugin is enabled | -| `systemPromptPath` | A `./` path to a UTF-8 text file containing system-prompt instructions; combined after `systemPrompt` when both are present | +| `systemPromptPath` | A `./` path to a UTF-8 text file; content is appended after `systemPrompt` when both are present | | `mcpServers` | MCP server declarations; enabled by default, can be disabled from `/plugins` | -| `hooks` | Hook rules run on lifecycle events while the plugin is enabled; see [Hooks in Plugins](#hooks-in-plugins) | -| `commands` | One or more `./` paths pointing to a directory or `.md` file; registers the Markdown files within as slash commands. See [Plugin Slash Commands](#plugin-slash-commands) | +| `hooks` | Hook rules run on lifecycle events while enabled; see [Hooks in Plugins](#hooks-in-plugins) | +| `commands` | One or more `./` paths to a directory or `.md` file; registers the Markdown files inside as slash commands. See [Plugin Slash Commands](#plugin-slash-commands) | Unsupported runtime fields such as `tools`, `apps`, `inject`, and `configFile` appear as diagnostics and are ignored. ### System-prompt instructions +Plugins inject instructions into the agent's system prompt through the `systemPrompt` and `systemPromptPath` fields. This section covers three parts: writing format and read timing, size limits, and the differences between the two engines. + +### Writing format and read timing + Use `systemPrompt` for a short inline instruction, or `systemPromptPath` to keep longer instructions in a file inside the plugin root. If both fields are present, the inline text appears first, followed by the file content. The file content is read when the plugin is installed or reloaded, so edits take effect only after `/plugins reload`. For example: ```json @@ -299,13 +303,24 @@ Use `systemPrompt` for a short inline instruction, or `systemPromptPath` to keep } ``` +The built-in agent prompt includes instructions from enabled plugins automatically. A custom `SYSTEM.md` or agent file owns its template, so include `${plugin_sections}` where plugin-contributed instructions should appear. If the custom template includes `${base_prompt}` and that effective default already contains the plugin block, do not add `${plugin_sections}` again. See [Custom agents and SYSTEM.md](./agents.md#overriding-the-main-agents-system-prompt-with-systemmd) for the complete variable table. + +### Size limits + +Each field (the inline `systemPrompt` and the `systemPromptPath` file) is limited to 32 KB (UTF-8 bytes): oversized content is ignored and reported in the plugin diagnostics. Across all enabled plugins, one prompt build injects at most 64 KB of instructions; contributions beyond the budget are skipped with a warning, including a single plugin whose inline text and file together exceed that budget. + +### Differences between the two engines + System-prompt contributions take effect on both agent engines. The interactive TUI, `kimi -p`, and `kimi web` use the v2 engine by default; setting `KIMI_CODE_LEGACY_FLAG=1` routes the local CLI surfaces to the legacy engine. -Each field — the inline `systemPrompt` and the `systemPromptPath` file — is limited to 32 KB (UTF-8 bytes): oversized content is ignored and reported in the plugin diagnostics. Across all enabled plugins, one prompt build injects at most 64 KB of instructions; contributions beyond the budget are skipped with a warning, including a single plugin whose inline text and file together exceed that budget. +
+Instruction refresh behavior under the two engines + +New sessions and newly created agents read the contributions from the plugins currently enabled. An in-flight request keeps its existing system prompt. `/plugins reload` refreshes the plugin skill list and requests prompt rebuilds for live agents; use it when you need the change to converge deliberately before the next turn. -New sessions and newly created agents read the contributions from the plugins currently enabled. An in-flight request keeps its existing system prompt. `/plugins reload` refreshes the plugin skill list and requests prompt rebuilds for live agents; use it when you need the change to converge deliberately before the next turn. On the v2 engine, installing, enabling, disabling, or removing a plugin updates the catalog immediately and a later prompt rebuild — for example after compaction or a tool-policy change — may pick up the new sections. The legacy engine keeps each live session's plugin snapshot until `/plugins reload` or a new session. A resumed session starts from its persisted prompt, and later rebuilds follow the engine-specific behavior above. Toggling a plugin's MCP server does not change system-prompt sections. +On the v2 engine, installing, enabling, disabling, or removing a plugin updates the catalog immediately, and a later prompt rebuild (for example after compaction or a tool-policy change) may pick up the new sections. The legacy engine keeps each live session's plugin snapshot until `/plugins reload` or a new session. A resumed session starts from its persisted prompt, and later rebuilds follow the engine-specific behavior above. Toggling a plugin's MCP server does not change system-prompt sections. -The built-in agent prompt includes instructions from enabled plugins automatically. A custom `SYSTEM.md` or agent file owns its template, so include `${plugin_sections}` where plugin-contributed instructions should appear. If the custom template includes `${base_prompt}` and that effective default already contains the plugin block, do not add `${plugin_sections}` again. See [Custom agents and SYSTEM.md](./agents.md#overriding-the-main-agent-s-system-prompt-with-system-md) for the complete variable table. +
## Plugin Slash Commands @@ -365,9 +380,9 @@ A command file has two parts: an optional **frontmatter** (the metadata between ### Running Commands and Passing Arguments -Commands are prefixed with the plugin id (their namespace) and registered as `:`, so the command above is actually `/kimi-finance:report` — this keeps same-named commands from different plugins from colliding. +Commands are prefixed with the plugin id (their namespace) and registered as `:`, so the command above is actually `/kimi-finance:report`. This keeps same-named commands from different plugins from colliding. -Whatever you type after the command replaces `$ARGUMENTS` in the body (above, `TSLA` replaces `$ARGUMENTS`). If the body has no `$ARGUMENTS` but you pass arguments anyway, they are not dropped — they are appended to the end of the body as `ARGUMENTS: `. +Whatever you type after the command replaces `$ARGUMENTS` in the body (above, `TSLA` replaces `$ARGUMENTS`). If the body has no `$ARGUMENTS` but you pass arguments anyway, they are not dropped; they are appended to the end of the body as `ARGUMENTS: `. ## Skills and Session Start @@ -458,13 +473,13 @@ A plugin can declare hook rules in its manifest that run on lifecycle events whi } ``` -Plugin hooks reuse the same mechanism as global hooks — see [Hooks](./hooks.md) for the event list, the stdin JSON payload, and how exit codes and return values affect the main flow. The differences are: +Plugin hooks reuse the same mechanism as global hooks. See [Hooks](./hooks.md) for the event list, the stdin JSON payload, and how exit codes and return values affect the main flow. The differences are: - A plugin's hooks are active only while the plugin is **enabled**; disabling the plugin stops its hooks. - Each hook runs with its working directory set to the plugin root, so `command` can use `./` paths inside the plugin. - The hook process receives two extra environment variables: `KIMI_CODE_HOME` and `KIMI_PLUGIN_ROOT` (the plugin root directory). -Installing a plugin never runs its hooks by itself — they only fire when their matching event occurs while the plugin is enabled. +Installing a plugin never runs its hooks by itself. They only fire when their matching event occurs while the plugin is enabled. ## Security Model @@ -474,3 +489,10 @@ Plugins have a limited loading scope. The following operations do not occur duri - All paths must remain within the plugin root directory after symbolic link resolution - MCP servers of enabled plugins start after `/reload` or in new sessions and can be disabled at any time from `/plugins` - Broken manifests or unsafe paths appear in `/plugins info ` diagnostics and do not affect other sessions + +## Next steps + +- [Agent Skills](./skills.md) — Learn the `SKILL.md` format and write Skills that ship with your plugins +- [Custom agents](./agents.md) — Agent file format and directory-scope precedence +- [MCP](./mcp.md) — The schema that MCP server declarations in plugins reuse +- [Hooks](./hooks.md) — The global hook mechanism that plugin hooks reuse diff --git a/docs/en/customization/skills.md b/docs/en/customization/skills.md index b905e98180b..2cf84553f3b 100644 --- a/docs/en/customization/skills.md +++ b/docs/en/customization/skills.md @@ -1,6 +1,6 @@ # Agent Skills -Agent Skills are a lightweight mechanism for extending model capabilities in Kimi Code CLI. A Skill is a Markdown document with YAML frontmatter that describes a specialized area of knowledge or a workflow — for example, a project's code style guidelines, a PR review process, or a commit message format. +Agent Skills are a lightweight mechanism for extending model capabilities in Kimi Code CLI. A Skill is a Markdown document with YAML frontmatter that describes a specialized area of knowledge or a workflow: a project's code style guidelines, a PR review process, or a commit message format. Compared to pasting the same instructions into a prompt every time, Skills offer the advantage of keeping content in a file, enabling reuse across projects and teams, allowing instant loading via a slash command, and letting the model invoke them automatically when needed. @@ -39,12 +39,12 @@ Please handle code according to the following guidelines: | Field | Description | | --- | --- | -| `name` | Skill name. Required in a directory-form `SKILL.md`; when omitted in a flat `.md` file, the filename is used. Names are case-insensitive | -| `description` | A one-line summary; the model uses this to decide when to use the Skill. Required in a directory-form `SKILL.md`; when omitted in a flat `.md` file, falls back to the first non-empty line of the body (up to 240 characters) | -| `type` | Skill type: `prompt` (default), `inline` (same semantics as `prompt`), `flow` (manual invocation only; not available for automatic model invocation). Other values are skipped | +| `name` | Skill name (case-insensitive). Required in directory-form `SKILL.md`; flat `.md` uses the filename | +| `description` | One-line summary the model uses to decide when to invoke. Required in directory-form `SKILL.md`; flat `.md` falls back to the first non-empty body line (up to 240 characters) | +| `type` | Skill type: `prompt` (default), `inline` (same as `prompt`), `flow` (manual invocation only). Other values are skipped | | `whenToUse` | Description of when the Skill should be triggered. Also accepts `when-to-use` and `when_to_use` | -| `disableModelInvocation` | When set to `true`, prevents the model from invoking this Skill automatically. Also accepts `disable-model-invocation` and `disable_model_invocation` | -| `arguments` | List of named parameters; can be written as a string array or a whitespace-separated string (e.g., `arguments: target mode`). Once declared, parameters can be read in the body with `$` | +| `disableModelInvocation` | If `true`, blocks automatic model invocation. Also accepts `disable-model-invocation`, `disable_model_invocation` | +| `arguments` | Named parameters; a string array or whitespace-separated string (e.g., `arguments: target mode`). Once declared, readable in the body as `$` | ::: warning Note In a directory-form `SKILL.md`, both `name` and `description` **must** be explicitly provided. Omitting either one will cause parsing to fail. @@ -81,7 +81,7 @@ The Kimi-specific user Skill directory moves with `KIMI_CODE_HOME`, so isolated extra_skill_dirs = ["~/team-skills", ".agents/team-skills"] ``` -**Built-in Skills** are distributed with the CLI and have the lowest priority. They provide out-of-the-box workflows for common tasks — for example, configuring MCP servers, customizing the TUI theme, and editing config files. See [Built-in skill commands](../reference/slash-commands.md#built-in-skill-commands) for the full list. Those describing Kimi Code itself can be turned off with the top-level [`builtin_product_skills`](../configuration/config-files.md#top-level-fields) field. +**Built-in Skills** are distributed with the CLI and have the lowest priority. They provide out-of-the-box workflows for common tasks: configuring MCP servers, customizing the TUI theme, and editing config files. See [Built-in skill commands](../reference/slash-commands.md#built-in-skill-commands) for the full list. Those describing Kimi Code itself can be turned off with the top-level [`builtin_product_skills`](../configuration/config-files.md#top-level-fields) field. ## Invoking a Skill diff --git a/docs/en/customization/themes.md b/docs/en/customization/themes.md index ffa5399d359..c91203ba678 100644 --- a/docs/en/customization/themes.md +++ b/docs/en/customization/themes.md @@ -8,12 +8,12 @@ Custom themes can override the tokens below. The `dark` and `light` columns show | Token | `dark` | `light` | What it controls | | --- | --- | --- | --- | -| `primary` | `#4FA8FF` | `#1565C0` | The most-used color. Links, inline code, the selected item in nearly every dialog, the focused editor border, Plan/"running" badges, spinners | -| `accent` | `#5BC0BE` | `#00838F` | Secondary highlight. Approval `▶` prefix, device-code box, image placeholder, BTW / queue panes, registry import | -| `text` | `#E0E0E0` | `#1A1A1A` | Body text. Dialog bodies, todo titles, footer model label, Markdown headings, assistant/tool message bullets, list bullets | +| `primary` | `#4FA8FF` | `#1565C0` | The most-used color. Links, inline code, selected items in dialogs, focus borders, badges, spinners | +| `accent` | `#5BC0BE` | `#00838F` | Secondary highlight. Approval `▶` prefix, device-code box, image placeholder, panes, registry import | +| `text` | `#E0E0E0` | `#1A1A1A` | Body text. Dialog bodies, todo titles, footer model label, Markdown headings, list bullets | | `textStrong` | `#F5F5F5` | `#1A1A1A` | Emphasized / bold text. Input dialogs, status messages | -| `textDim` | `#888888` | `#454545` | Secondary, dimmed text. Thinking, hints, descriptions, completed todos, Markdown quotes, footer status bar | -| `textMuted` | `#6B6B6B` | `#5F5F5F` | Faintest text. Counters, scroll info, descriptions, Markdown link URLs, code-block borders | +| `textDim` | `#888888` | `#454545` | Secondary, dimmed text. Thinking, hints, completed todos, Markdown quotes, footer status bar | +| `textMuted` | `#6B6B6B` | `#5F5F5F` | Faintest text. Counters, scroll info, Markdown link URLs, code-block borders | | `border` | `#5A5A5A` | `#737373` | Pane and editor borders, Markdown horizontal rule | | `borderFocus` | `#E8A838` | `#92660A` | Focus / attention border, currently only the approval panel | | `success` | `#4EC87E` | `#0E7A38` | Success state. `✓`, "enabled", completed | @@ -65,7 +65,7 @@ Fields: - `name` (required): the theme identifier. - `displayName` (optional): a human-readable name. -- `base` (optional): the built-in palette that unspecified tokens inherit — `"dark"` (default) or `"light"`. Set `"base": "light"` when you are building a **light** theme so the tokens you leave out stay readable on a light background (otherwise they fall back to the dark palette). +- `base` (optional): the built-in palette that unspecified tokens inherit, `"dark"` (default) or `"light"`. Set `"base": "light"` when you are building a **light** theme so the tokens you leave out stay readable on a light background (otherwise they fall back to the dark palette). - `colors` (optional): the color tokens to override, each a 6-digit hex value (e.g. `#FE8019`). Use the token names from [Built-in color tokens](#built-in-color-tokens). Any token you omit falls back to the selected base palette, so partial themes are fine: @@ -85,7 +85,7 @@ Use the token names from [Built-in color tokens](#built-in-color-tokens). Any to Two ways: 1. **The `/theme` command** (recommended): opens the theme picker, where custom themes appear as `Custom: `. The picker **re-scans the themes directory every time it opens**, so a theme file you just added shows up **without a restart**. -2. **`tui.toml`**: set `theme` to your theme name: +2. **[`tui.toml`](../configuration/config-files.md#tuitoml)**: set `theme` to your theme name: ```toml # ~/.kimi-code/tui.toml @@ -104,9 +104,13 @@ Custom themes are designed to never get in your way: If you edit the theme file that is **currently active**, the change is not reloaded automatically. To apply the new colors: -- run `/reload-tui` — it reloads `tui.toml` and re-applies the current theme (including re-reading the theme file); or +- run `/reload-tui`, which reloads `tui.toml` and re-applies the current theme (including re-reading the theme file); or - switch to another theme in `/theme` and back. ::: warning Note Re-selecting the **same** theme in `/theme` does not reload it (you get a "Theme unchanged" message). To reload changes to the active theme, use one of the two methods above. ::: + +## Next steps + +- [Configuration files](../configuration/config-files.md#tuitoml) — Full field reference for `tui.toml`, including the `theme` option diff --git a/docs/media/provider-manager.jpg b/docs/media/provider-manager.jpg new file mode 100644 index 00000000000..bb5edf80837 Binary files /dev/null and b/docs/media/provider-manager.jpg differ diff --git a/docs/zh/configuration/config-files.md b/docs/zh/configuration/config-files.md index 4db54576935..bc880e61120 100644 --- a/docs/zh/configuration/config-files.md +++ b/docs/zh/configuration/config-files.md @@ -1,12 +1,10 @@ # 配置文件 -Kimi Code CLI 把所有长期偏好写进 `~/.kimi-code/` 下的 TOML（一种结构清晰的纯文本配置格式）文件——比如使用哪个模型、填哪个 API 密钥、Agent 每轮最多跑几步。改一次，每次启动都生效。Agent 与运行时设置放在 `config.toml`，终端界面与客户端偏好（主题、编辑器、通知、自动更新）放在配套的 `tui.toml`。 - -默认位置：`~/.kimi-code/config.toml`，首次运行时自动创建。 +Kimi Code CLI 的长期偏好都写在 `~/.kimi-code/` 下的 TOML 文件里：运行时设置放 `config.toml`，终端界面偏好放配套的 `tui.toml`。 ## 配置文件位置 -CLI 从 `~/.kimi-code/config.toml` 读取配置。如需把数据目录迁移到别处，可用 `KIMI_CODE_HOME` 环境变量覆盖： +CLI 从 `~/.kimi-code/config.toml` 读取配置，首次运行时自动创建。如需把数据目录迁移到别处，可用 `KIMI_CODE_HOME` 环境变量覆盖： ```sh export KIMI_CODE_HOME=/path/to/kimi-home @@ -15,7 +13,7 @@ export KIMI_CODE_HOME=/path/to/kimi-home 此时配置文件路径变为 `$KIMI_CODE_HOME/config.toml`。无论目录在哪里，文件名固定是 `config.toml`。 ::: tip -TOML 字段名一律用下划线（snake_case），如 `default_model`、`max_context_size`。字段名里若含 `.`，需用引号包住，例如 `[models."gpt-4.1"]`——否则 TOML 会把 `.` 解释为嵌套表分隔符。 +TOML 字段名一律用下划线（snake_case），如 `default_model`、`max_context_size`。字段名里若含 `.`，需用引号包住，例如 `[models."gpt-4.1"]`；否则 TOML 会把 `.` 解释为嵌套表分隔符。 ::: ## 完整示例 @@ -98,30 +96,28 @@ timeout = 5 | 字段 | 类型 | 默认值 | 说明 | | --- | --- | --- | --- | | `default_model` | `string` | — | 默认模型别名，必须在 `models` 中定义 | -| `default_permission_mode` | `string` | `manual` | 新会话的默认权限模式，可选 `manual`（"Always Ask"：仅自动读取，其余操作逐一向你确认）、`yolo`（"Ask When Needed"：自动完成常规修改和命令；高危操作、提问和计划仍会问你）、`auto`（"Never Ask"：完全不打断，所有操作和判断自动完成，但危险命令仍会被拒绝） | -| `default_plan_mode` | `boolean` | `false` | 新会话是否默认以 Plan 模式（先出计划再执行）启动 | +| `default_permission_mode` | `string` | `manual` | 新会话的默认权限模式，可选 `yolo` / `auto`，见 [交互与权限](../guides/interaction.md#三种权限模式) | +| `default_plan_mode` | `boolean` | `false` | 新会话是否默认以 [Plan 模式](../guides/interaction.md#plan-模式)启动 | | `merge_all_available_skills` | `boolean` | `true` | 是否合并所有目录中的 Agent Skills | | `extra_skill_dirs` | `array` | — | 额外 Skill 搜索目录，叠加到默认目录之上 | | `extra_agent_dirs` | `array` | — | 额外自定义 Agent 搜索目录，叠加到默认目录之上 | -| `builtin_product_skills` | `boolean` | `true` | 是否向模型提供介绍 Kimi Code 自身的内置 Skills：`update-config`、`custom-theme`、`mcp-config`、`check-kimi-code-docs`、`import-from-cc-codex`。关闭后它们的名称和描述不再进入系统提示词，代价是失去这些任务的引导流程。默认的 `agent-core-v2` 引擎会读取本字段；设置 `KIMI_CODE_LEGACY_FLAG=1` 选择旧版引擎时会忽略 | +| `builtin_product_skills` | `boolean` | `true` | 是否向模型提供介绍 Kimi Code 自身的内置 Skills | | `telemetry` | `boolean` | `true` | 是否启用匿名遥测；显式设为 `false` 时关闭 | -| `providers` | `table` | `{}` | API 供应商表 → [`providers`](#providers) | -| `models` | `table` | — | 模型别名表 → [`models`](#models) | -| `thinking` | `table` | — | Thinking 模式默认参数 → [`thinking`](#thinking) | -| `loop_control` | `table` | — | Agent 循环控制参数 → [`loop_control`](#loop-control) | -| `background` | `table` | — | 后台任务运行参数 → [`background`](#background) | -| `tools` | `table` | — | 全局工具开关 → [`tools`](#tools) | -| `image` | `table` | — | 图片压缩参数 → [`image`](#image) | -| `services` | `table` | — | 内置外部服务配置 → [`services`](#services) | -| `permission` | `table` | — | 初始权限规则 → [`permission`](#permission) | -| `hooks` | `array
` | — | 生命周期 hook，详见 [Hooks](../customization/hooks.md) | -| `identity` | `table` | — | 自定义 Agent 身份 → [`identity`](#identity) | - -以下各节对 `providers`、`models`、`thinking`、`loop_control`、`background`、`image`、`services`、`permission` 等嵌套表逐一展开。 +| [`providers`](#providers) | `table` | `{}` | API 供应商表 | +| [`models`](#models) | `table` | — | 模型别名表 | +| [`thinking`](#thinking) | `table` | — | Thinking 模式默认参数 | +| [`loop_control`](#loop_control) | `table` | — | Agent 循环控制参数 | +| [`background`](#background) | `table` | — | 后台任务运行参数 | +| [`tools`](#tools) | `table` | — | 全局工具开关 | +| [`image`](#image) | `table` | — | 图片压缩参数 | +| [`services`](#services) | `table` | — | 内置外部服务配置 | +| [`permission`](#permission) | `table` | — | 初始权限规则 | +| [`hooks`](../customization/hooks.md) | `array
` | — | 生命周期 hook | +| [`identity`](#identity) | `table` | — | 自定义 Agent 身份 | ## `providers` -`providers` 表的每一项定义一个 API 供应商，以唯一名称为 key。CLI 只从这里读取凭证，**不会**从 shell 环境变量自动取后备值——在终端里 `export KIMI_API_KEY` 不会让供应商自动获得密钥，必须显式写在配置文件里（详见[配置覆盖](./overrides.md#供应商凭证)）。 +`providers` 表的每一项定义一个 API 供应商，以唯一名称为 key。CLI 只从这里读取凭证，**不会**从 shell 环境变量自动取后备值。在终端里 `export KIMI_API_KEY` 不会让供应商自动获得密钥，必须显式写在配置文件里（详见[配置覆盖](./overrides.md#供应商凭证)）。 | 字段 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | @@ -129,7 +125,7 @@ timeout = 5 | `api_key` | `string` | 否 | API 密钥，明文写在配置文件里 | | `base_url` | `string` | 否 | API 基础 URL | | `oauth` | `table` | 否 | OAuth 凭据引用（`storage`、`key` 两个字段），由登录流程自动注入，通常无需手写 | -| `env` | `table` | 否 | 供应商凭证的备用来源，详见下文 | +| `env` | `table` | 否 | 供应商凭证的备用来源，见 `env` 子表 | | `custom_headers` | `table` | 否 | 每次请求附加的自定义 HTTP 头 | **`env` 子表**：可以把供应商惯用的键名（如 `KIMI_API_KEY`）写在 `[providers..env]` 里，作为 `api_key` / `base_url` 的备用来源。这个子表**只在配置文件里读取**，不会修改 shell 环境： @@ -151,16 +147,16 @@ KIMI_BASE_URL = "https://api.moonshot.ai/v1" | `provider` | `string` | 是 | 使用的供应商名称，必须在 `providers` 中定义 | | `model` | `string` | 是 | 调用 API 时实际传给服务端的模型 ID | | `max_context_size` | `integer` | 是 | 最大上下文长度（token 数），必须 ≥ 1 | -| `max_input_size` | `integer` | 否 | 模型声明的单次请求输入上限（当低于总窗口时，如 gpt-5 的 400k 窗口 / 272k 输入）。压缩、上下文溢出检查和用量比率优先使用它；补全预算仍使用总窗口。解析时会被钳制到不超过 `max_context_size` | -| `max_output_size` | `integer` | 否 | 单次请求的输出 token 上限（对应 `max_tokens`）。目前仅 `anthropic` 供应商读取。为 Claude 模型设置后，这个显式值会覆盖内置的服务端最大值 | -| `capabilities` | `array` | 否 | 显式追加的能力标签：`thinking`、`always_thinking`、`image_in`、`video_in`、`audio_in`、`tool_use`。与供应商自动识别的能力取并集，只能追加不能移除 | -| `support_efforts` | `array` | 否 | 模型接受的 Thinking 档位。对 `kimi` 而言，在运行时选择列表外的值会报错；模型解析时若配置值或之前的值不受目标模型支持，会回落到目标模型的 `default_effort`，并将该有效值同步给 UI。支持 Thinking 但没有此字段的 Kimi 模型使用布尔 `on` / `off`。其他 provider 在协议提供原生 effort 字段时会原样传递具体值；协议仅提供等级或 token budget 时，只做必要的格式转换。managed 和 open-platform 刷新可能会改写该字段；如需手动固定，请改用 `[models."".overrides] support_efforts` | -| `default_effort` | `string` | 否 | 模型的默认 Thinking 档位。managed 和 open-platform 刷新可能会改写该字段；如需手动固定，请改用 `[models."".overrides] default_effort` | -| `off_effort` | `string` | 否 | 关闭 Thinking 时在线上传输的 effort 编码（如 xai grok 的 `none`）。仅对声明了该编码的模型（catalog 会导入）有意义：设置后选择 Off 会发送这个值而不是省略 effort 字段——对默认就会推理的模型，这是真正关闭推理的唯一方式 | -| `base_url` | `string` | 否 | 模型级端点覆盖（catalog 导入网关模型时写入，这些模型与供应商默认端点不同）。解析时优先于供应商的 `base_url`；仅在与 `protocol` 配合时生效 | +| `max_input_size` | `integer` | 否 | 模型声明的单次请求输入上限；压缩、溢出检查与用量比率优先使用它，补全预算仍用总窗口 | +| `max_output_size` | `integer` | 否 | 单次请求的输出 token 上限（对应 `max_tokens`），目前仅 `anthropic` 供应商读取 | +| `capabilities` | `array` | 否 | 显式追加的能力标签：`thinking`、`always_thinking`、`image_in`、`video_in`、`audio_in`、`tool_use`，只能追加不能移除 | +| `support_efforts` | `array` | 否 | 模型接受的 Thinking 档位；解析时配置值不受支持会回落到模型的 `default_effort` 并同步给 UI；选列表外的值会报错，managed 刷新会改写（固定请用 overrides） | +| `default_effort` | `string` | 否 | 模型的默认 Thinking 档位；managed/open-platform 刷新可能改写，固定请用 [模型覆盖项](#模型覆盖项) | +| `off_effort` | `string` | 否 | 关闭 Thinking 时在线上传输的 effort 编码（如 xai grok 的 `none`）；对默认就会推理的模型，这是真正关闭推理的唯一方式 | +| `base_url` | `string` | 否 | 模型级端点覆盖（catalog 导入网关模型时写入）；解析时优先于供应商的 `base_url`，仅与 `protocol` 配合时生效 | | `display_name` | `string` | 否 | UI 中显示的名称，未设时回退到 `model` | -| `reasoning_key` | `string` | 否 | 仅 `openai` 供应商。当网关用非标准字段名返回推理内容时才需要设置；默认自动识别 `reasoning_content` / `reasoning_details` / `reasoning` | -| `adaptive_thinking` | `boolean` | 否 | 仅 `anthropic` 供应商。强制开启或关闭 adaptive thinking，覆盖按模型名推断的逻辑。省略时自动推断（Claude ≥ 4.6 使用 adaptive） | +| `reasoning_key` | `string` | 否 | 仅 `openai` 供应商；网关用非标准字段名返回推理内容时才需要设置，默认自动识别 `reasoning_content` 等 | +| `adaptive_thinking` | `boolean` | 否 | 仅 `anthropic` 供应商；强制开关 adaptive thinking，省略时按模型名自动推断（Claude ≥ 4.6 用 adaptive） | 别名中含 `.` 时需要加引号： @@ -188,19 +184,17 @@ display_name = "Kimi for Coding (custom)" `[models."".overrides]` 接受普通模型字段，例如 `max_context_size`、`max_input_size`、`max_output_size`、`capabilities`、`display_name`、`reasoning_key`、`adaptive_thinking`、`support_efforts`、`default_effort` 和 `off_effort`。不接受身份 / 路由字段：`provider`、`model`、`protocol`、`beta_api` 和 `base_url`。 -无需修改配置文件也可以临时切换模型——通过 `KIMI_MODEL_*` 环境变量在内存里合成一个临时供应商，详见[用环境变量定义模型](./env-vars.md#用环境变量定义模型-kimi-model)。 +无需修改配置文件也可以临时切换模型：通过 `KIMI_MODEL_*` 环境变量在内存里合成一个临时供应商，详见[用环境变量定义模型](./env-vars.md#用环境变量定义模型kimi_model_)。 ## `secondary_model` -subagent 默认继承 main agent 正在运行的模型。`[secondary_model]` 节把这件事变成可配置的：为 subagent 准备一批候选模型（模型池）并指定默认绑定——典型用法是给不需要主模型能力的子任务换一个更便宜的模型。 +subagent 默认继承 main agent 正在运行的模型。`[secondary_model]` 节把这件事变成可配置的：为 subagent 准备一批候选模型（模型池）并指定默认绑定。典型用法是给不需要主模型能力的子任务换一个更便宜的模型。 ### subagent 模型池 -配置后在包括交互式 TUI 在内的所有启动方式下生效。 - -模型池默认启用，在包括交互式 TUI 在内的所有启动方式下生效。如需禁用，设置 `KIMI_CODE_EXPERIMENTAL_SECONDARY_MODEL=0`（或在 `config.toml` 的 `[experimental]` 下配置 `secondary-model = false`）；禁用期间模型池配置不生效：subagent 继承调用方模型，会话启动也会跳过池校验。 +该功能默认开启，无需配置即可使用。设置 `KIMI_CODE_EXPERIMENTAL_SECONDARY_MODEL=0` 可关闭：关闭后模型池配置不生效，subagent 继承调用方模型，会话启动也会跳过池校验。 -最小配置只有一行——单独写下的 `default_model` 就是只含一个条目的模型池： +最小配置只有一行：单独写下的 `default_model` 就是只含一个条目的模型池： ```toml [secondary_model] @@ -210,15 +204,15 @@ default_model = "kimi-code/kimi-for-coding-highspeed" | 字段 | 类型 | 默认值 | 说明 | | --- | --- | --- | --- | | `default_model` | `string` | — | subagent 的默认模型 | -| `models` | `table` | — | subagent 模型池。key 是 [`[models]`](#models) 条目的别名，value 是给 main agent 的挑选提示 | +| `models` | `table` | — | subagent 模型池；key 为 [`[models]`](#models) 条目别名，value 为挑选提示 | | `force` | `boolean` | `false` | 把所有 subagent 固定到 `default_model`，收回 main agent 的选择权 | -| `default_effort` | `string` | — | 每次派生的 subagent 绑定的 Thinking 档位，优先于所绑定模型条目自己的 `default_effort` | +| `default_effort` | `string` | — | 每次派生的 subagent 绑定的 Thinking 档位，优先于所绑定模型自带的 `default_effort` | 字段之间的约束： - `default_model`：配置 `models` 表时必填，且必须是其中的 key。 - `models`：value 中英文均可；空字符串表示只列出别名、不给提示。 -- `force`：必须搭配 `default_model`，且不能与 `models` 表同用——表的意义在于提供选择，而 force 取消了选择。 +- `force`：必须搭配 `default_model`，且不能与 `models` 表同用：表的意义在于提供选择，而 force 取消了选择。 - `default_effort` 是节级设置：无论派生绑定到池中哪个条目（或 force 固定的模型）都生效。想按条目区分档位时不要设置它，改用下文的模型「变体」。 - `primary` 是保留字（含义见下文），不能作为池中 key。 @@ -226,7 +220,7 @@ default_model = "kimi-code/kimi-for-coding-highspeed" 在交互式 TUI 中，也可以用 [`/secondary-model`](../reference/slash-commands.md) 命令（别名 `/subagent-model`）打开模型选择器：选择后写入 `default_model`（已有 models 表而所选别名不在其中时，会一并补一条空描述条目），之后派生的 subagent 立即按新默认值绑定，无需重启会话。 -配置了模型池（显式的 `models` 表或隐式的单条目池）即启用模型选择：`Agent` / `AgentSwarm` 工具会获得 `model` 参数，工具描述中列出模型池（默认模型标注 `[default]`），main agent 可按次派生选择模型。池 key 只能引用已配置的 [`[models]`](#models) 条目——下面的 `kimi-code/*` 别名由 `/login` 自动提供： +配置了模型池（显式的 `models` 表或隐式的单条目池）即启用模型选择：`Agent` / `AgentSwarm` 工具会获得 `model` 参数，工具描述中列出模型池（默认模型标注 `[default]`），main agent 可按次派生选择模型。池 key 只能引用已配置的 [`[models]`](#models) 条目。下面的 `kimi-code/*` 别名由 `/login` 自动提供： ```toml [secondary_model] @@ -244,7 +238,7 @@ default_model = "kimi-code/kimi-for-coding-highspeed" `model` 参数的取值规则： -- 接受池中任意别名，或 `"primary"`——调用方自己正在运行的模型，始终合法，即使不在池中。 +- 接受池中任意别名，或 `"primary"`，即调用方自己正在运行的模型，始终合法，即使不在池中。 - `default_model` 与 `models` 都未配置时该参数不存在，subagent 继承调用方模型。 - 绑定池中别名时不继承调用方的 Thinking 档位。本节设置了 `default_effort` 时以它为准；否则，`[thinking].enabled = false` 会保持关闭 Thinking；开启 Thinking 时，再依次使用所绑定模型条目的 `default_effort`、全局 `[thinking].effort`、所绑定模型 `support_efforts` 的中间项。 - `"primary"` 则连模型带档位一起继承调用方。 @@ -289,7 +283,7 @@ k3-max = "同一模型的 max Thinking 档位。适合最难的子任务。" 两个前提： - 底层模型必须声明了 `support_efforts`（`managed:kimi-code` 下目前只有 k3 系列声明了档位）。 -- 变体是独立条目，不会继承被指向条目的字段——`capabilities`、`support_efforts` 等元数据要完整照抄，否则 `default_effort` 不生效（它必须是 `support_efforts` 列表中的值）。 +- 变体是独立条目，不会继承被指向条目的字段：`capabilities`、`support_efforts` 等元数据要完整照抄，否则 `default_effort` 不生效（它必须是 `support_efforts` 列表中的值）。 另外注意 main agent 与 subagent 的不对称：对 main agent，全局 `[thinking].effort` 一旦设置就压过变体的 `default_effort`；对绑定池内别名的 subagent，变体的 `default_effort` 优先于全局值，只有 `[secondary_model].default_effort` 的优先级更高。取值与回落规则同 [`[models]` 条目的 `default_effort`](#models)。 @@ -307,17 +301,19 @@ k3-max = "同一模型的 max Thinking 档位。适合最难的子任务。" | 字段 | 类型 | 默认值 | 说明 | | --- | --- | --- | --- | | `enabled` | `boolean` | `true` | 新会话是否默认开启 Thinking，设为 `false` 可强制关闭 | -| `effort` | `string` | — | Thinking 强度（例如 `low`、`medium`、`high`、`xhigh`、`max`）。非 Kimi provider 在上游协议接受具体 effort 值时不会改写该值；如果上游拒绝，请改成该模型支持的档位。协议仅提供等级或 token budget 时，仍需做格式转换。对于带 `support_efforts` 的 Kimi 模型，若该配置值不在列表中，会回落到模型默认档位；没有该列表的 Kimi 模型会把任意开启值视为布尔 `on` | -| `keep` | `string` | `"all"` | 保留思考透传。在 `kimi` 上以 `thinking.keep` 发送；在 `anthropic`（Claude 以及 Kimi 的 Anthropic 兼容模式）上以 `context_management` 的 `clear_thinking_20251015` 编辑发送（开启 keep 会让 Anthropic 请求走 beta Messages API；关值可禁用 keep 并回到标准端点）。`"all"` 会保留历史轮次的思考内容（`reasoning_content` / Anthropic thinking blocks）；传入关值（`false`/`0`/`no`/`off`/`none`/`null`）可禁用。可被 `KIMI_MODEL_THINKING_KEEP` 覆盖；仅在 Thinking 开启时注入 | +| `effort` | `string` | — | Thinking 强度：`low`/`medium`/`high`/`xhigh`/`max`；不在模型支持列表时回落默认档 | +| `keep` | `string` | `"all"` | 保留思考透传；`kimi` 以 `thinking.keep` 发送，`anthropic` 以 `clear_thinking_20251015` 编辑发送（走 beta API）；关值可禁用；Thinking 开启时注入，可被同名环境变量覆盖 | -### 已废弃字段 +
已废弃字段 | 字段 | 废弃版本 | 描述 | | --- | --- | --- | -| `default_thinking` | 0.21.0 | 顶层布尔值，由 `[thinking] enabled` 取代。将 `default_thinking = true` 迁移为 `enabled = true`，`default_thinking = false` 迁移为 `enabled = false`。 | -| `thinking.mode` | 0.21.0 | 可选值 `auto` / `on` / `off`，由 `[thinking] enabled` 取代。`mode = "off"` 改为 `enabled = false`；`mode = "on"` 和 `mode = "auto"` 等价于 `enabled = true`（默认值），可删除该行。 | -| `loop_control.max_retries_per_step` | 0.32.0 | 由 `loop_control.max_attempts_per_step` 取代（该值本来就是含首次尝试的总尝试次数上限）。旧 key 不再生效，启动时会给出警告，请在 `config.toml` 中手动改名。 | -| `loop_control.max_steps_per_run` | 0.32.0 | 由 `loop_control.max_steps_per_turn` 取代。旧 key 不再生效，启动时会给出警告，请在 `config.toml` 中手动改名。 | +| `default_thinking` | 0.21.0 | 顶层布尔值，由 `[thinking] enabled` 取代，值不变 | +| `thinking.mode` | 0.21.0 | 可选值 `auto`/`on`/`off`，由 `[thinking] enabled` 取代；`off` 改 `enabled = false`，其余可删 | +| `loop_control.max_retries_per_step` | 0.32.0 | 由 `loop_control.max_attempts_per_step` 取代（本就是含首次尝试的总次数）；旧 key 不生效并警告 | +| `loop_control.max_steps_per_run` | 0.32.0 | 由 `loop_control.max_steps_per_turn` 取代；旧 key 不生效，启动警告，请手动改名 | + +
## `loop_control` @@ -331,15 +327,15 @@ k3-max = "同一模型的 max Thinking 档位。适合最难的子任务。" `max_steps_per_turn` 可被环境变量 `KIMI_LOOP_MAX_STEPS_PER_TURN` 覆盖，`max_attempts_per_step` 可被 `KIMI_LOOP_MAX_ATTEMPTS_PER_STEP` 覆盖，优先级均高于配置文件。旧的 `KIMI_LOOP_MAX_RETRIES_PER_STEP` 已废弃，但在新变量未设置时仍生效（启动时会给出警告）。 -重试仅针对瞬时故障——连接错误、超时、HTTP 429 限流和 5xx 服务端错误。账户额度耗尽或余额不足导致的 429 不会重试，会立即失败：在充值之前重试不可能成功。 +重试仅针对瞬时故障：连接错误、超时、HTTP 429 限流和 5xx 服务端错误。账户额度耗尽或余额不足导致的 429 不会重试，会立即失败：在充值之前重试不可能成功。 ## `token_counting` -`token_counting` 决定对外上报的上下文 token 计数——即上下文大小显示所基于的值。内部逻辑（自动压缩触发、预算、超限退避）始终同时使用供应商实测与估算，不受本配置影响。 +`token_counting` 决定对外上报的上下文 token 计数，即上下文大小显示所基于的值。内部逻辑（自动压缩触发、预算、超限退避）始终同时使用供应商实测与估算，不受本配置影响。 | 字段 | 类型 | 默认值 | 说明 | | --- | --- | --- | --- | -| `strategy` | `"measured+estimated" \| "measured" \| "estimated"` | `"measured+estimated"` | `measured+estimated` 上报实时大小——每次请求的供应商实测用量加上未实测尾部的估算——并以最近一次实测总量兜底；`measured` 只上报供应商实测，显示仅在每次请求完成后变化；`estimated` 忽略供应商实测、上报纯估算——适用于不上报用量或用量不可信的供应商 | +| `strategy` | `"measured+estimated" \| "measured" \| "estimated"` | `"measured+estimated"` | 上下文 token 计数策略：`measured+estimated` 为实测加估算兜底，`measured` 仅实测（请求完成后更新），`estimated` 纯估算（供应商不上报用量时用） | `strategy` 可被环境变量 `KIMI_TOKEN_COUNTING_STRATEGY` 覆盖，优先级高于 `config.toml`。 @@ -350,13 +346,13 @@ k3-max = "同一模型的 max Thinking 档位。适合最难的子任务。" | 字段 | 类型 | 默认值 | 说明 | | --- | --- | --- | --- | | `max_running_tasks` | `integer` | — | 同时运行的最大后台任务数 | -| `keep_alive_on_exit` | `boolean` | `false` | 会话关闭时是否保留仍在运行的后台任务。默认情况下，Kimi Code 会在进程退出前请求停止所有后台任务；只有希望任务在会话结束后继续运行时才设为 `true`。在 print 模式（`kimi -p`）下，本字段仅作为 `print_background_mode` 未设置时的兼容回退：`true` 等价于 `print_background_mode = "drain"` | -| `kill_grace_period_ms` | `integer` | `5000` | 会话关闭、手动停止或任务超时请求正常终止后，等待任务自行结束的宽限时间（毫秒）。超过该时间仍在运行时，Kimi Code 会尝试强制停止该任务 | -| `bash_auto_background_on_timeout` | `boolean` | `true` | 前台 `Bash` 命令触及超时时间时，将其转为后台任务而不是直接终止：命令完成时 agent 会收到通知，转入后台的命令受 `bash_task_timeout_s` 默认后台超时约束。设为 `false` 则恢复超时即终止的行为 | -| `bash_task_timeout_s` | `integer` | `600` | 后台 `Bash` 任务在调用未传 `timeout` 时的默认超时（秒）；前台命令超时转后台后也按此值重新计时。`0` 表示无超时——任务一直运行到自行结束或被模型手动停止。显式传入的 `timeout` 不受影响。在 print 模式（`kimi -p`）下未显式设置时默认为 `0` | -| `print_background_mode` | `"exit" \| "drain" \| "steer"` | `"steer"` | 仅 print 模式（`kimi -p`）生效，决定 main agent 的 turn 结束后如何处理未返回的后台任务：`"exit"` 立即退出；`"drain"` 退出前等待所有后台任务进入终态（结果不回馈给 main agent）；`"steer"` 不退出，让后台任务完成时像后台 subagent 一样以合成 user 消息 steer main agent 进入新 turn，直到某 turn 结束时无未决后台任务或触及上限。设置后优先级高于 `keep_alive_on_exit` 的 print 回退 | -| `print_wait_ceiling_s` | `integer` | `2147483` | print 模式（`kimi -p`）下，`print_background_mode` 为 `"drain"` 或 `"steer"` 时，等待/steer 循环的墙钟上限（秒；默认约 24.8 天，近似不设限）。在非 print 模式或 `"exit"` 时无效 | -| `print_max_turns` | `integer` | `100000` | print 模式（`kimi -p`）且 `print_background_mode = "steer"` 时，允许由后台任务完成触发的新 turn 的最大数量，防止 steer 循环失控（默认值近似不设限） | +| `keep_alive_on_exit` | `boolean` | `false` | 会话关闭时是否保留仍在运行的后台任务；print 模式下仅作 `print_background_mode` 的回退：`true` 等价于 `drain` | +| `kill_grace_period_ms` | `integer` | `5000` | 任务被请求正常终止后，等待自行结束的宽限时间（毫秒），超时后强制停止 | +| `bash_auto_background_on_timeout` | `boolean` | `true` | 前台 `Bash` 命令超时后转为后台任务而非终止；设为 `false` 恢复超时即终止 | +| `bash_task_timeout_s` | `integer` | `600` | 后台 `Bash` 任务默认超时（秒）；`0` 表示无超时，任务运行到自行结束或被手动停止；显式传入的 timeout 不受影响，print 模式默认 0 | +| `print_background_mode` | `"exit" \| "drain" \| "steer"` | `"steer"` | 仅 print 模式生效；`"exit"` 立即退出、`"drain"` 等待终态（结果不回馈）、`"steer"` 由后台任务合成消息继续 turn（合成消息续跑至无未决任务） | +| `print_wait_ceiling_s` | `integer` | `2147483` | 等待/steer 循环的墙钟上限（秒），非 print 模式或 `"exit"` 时无效 | +| `print_max_turns` | `integer` | `100000` | steer 模式下后台任务触发新 turn 的数量上限，防止 steer 循环失控 | `keep_alive_on_exit` 可被环境变量 `KIMI_CODE_BACKGROUND_KEEP_ALIVE_ON_EXIT` 覆盖，`max_running_tasks` 可被 `KIMI_CODE_BACKGROUND_MAX_RUNNING_TASKS` 覆盖，优先级均高于配置文件。 @@ -368,7 +364,7 @@ k3-max = "同一模型的 max Thinking 档位。适合最难的子任务。" | 字段 | 类型 | 默认值 | 说明 | | --- | --- | --- | --- | -| `timeout_ms` | `integer` | `7200000`（2 小时） | 单个 `Agent` subagent 允许运行的最长时间（毫秒）。超时后 subagent 以 `timed_out` 收尾。`0` 表示无超时——subagent 一直运行到自行结束或被模型手动停止。该值是后台任务管理器对每个 subagent 任务的 per-task timeout，因此对前台与后台 subagent 同时生效。在 print 模式（`kimi -p`）下未显式设置时默认为 `0`。注意：超过 `2147483647`（约 24.8 天）的值会被运行时钳到约 24.8 天 | +| `timeout_ms` | `integer` | `7200000`（2 小时） | 单个 `Agent` subagent 允许运行的最长时间（毫秒）；超时以 `timed_out` 收尾，`0` 表示无超时 | `timeout_ms` 可被环境变量 `KIMI_SUBAGENT_TIMEOUT_MS` 覆盖，优先级高于配置文件。 @@ -378,7 +374,7 @@ k3-max = "同一模型的 max Thinking 档位。适合最难的子任务。" | 字段 | 类型 | 默认值 | 说明 | | --- | --- | --- | --- | -| `timeout_ms` | `integer` | `7200000`（2 小时） | `AgentSwarm` 启动的单个 subagent 允许运行的最长时间（毫秒）。超时后该 subagent 被中止，聚合报告中标记为失败（`Subagent timed out.`），其余 subagent 不受影响。`0` 表示无超时——subagent 一直运行到自行结束或被模型手动停止。在 print 模式（`kimi -p`）下未显式设置时默认为 `0`。注意：超过 `2147483647`（约 24.8 天）的值会被运行时钳到约 24.8 天 | +| `timeout_ms` | `integer` | `7200000`（2 小时） | `AgentSwarm` 单个 subagent 允许运行的最长时间（毫秒）；超时后中止，聚合报告标记 `Subagent timed out.`；0 为无超时 | `timeout_ms` 可被环境变量 `KIMI_CODE_SWARM_TIMEOUT_MS` 覆盖，优先级高于配置文件。 @@ -386,8 +382,8 @@ k3-max = "同一模型的 max Thinking 档位。适合最难的子任务。" | 字段 | 类型 | 默认值 | 说明 | | --- | --- | --- | --- | -| `startup_timeout_ms` | `integer` | `30000`（30 秒） | 所有 MCP server 的全局默认连接（启动 + 工具发现）超时（毫秒），取值范围为 `1`–`2147483647`。`mcp.json` 中单个 server 的 `startupTimeoutMs` 始终优先于本节与环境变量；都未设置时使用默认值 | -| `tool_timeout_ms` | `integer` | `60000`（60 秒） | 所有 MCP server 的全局默认单次工具调用超时（毫秒），取值范围为 `1`–`2147483647`。`mcp.json` 中单个 server 的 `toolTimeoutMs` 始终优先于本节与环境变量；都未设置时使用客户端内置默认值 | +| `startup_timeout_ms` | `integer` | `30000`（30 秒） | 所有 MCP server 的全局默认连接（启动 + 工具发现）超时（毫秒）；`mcp.json` 的 `startupTimeoutMs` 优先于本节 | +| `tool_timeout_ms` | `integer` | `60000`（60 秒） | 所有 MCP server 的全局默认单次工具调用超时（毫秒）；`mcp.json` 的 `toolTimeoutMs` 优先于本节 | `startup_timeout_ms` 和 `tool_timeout_ms` 可分别被环境变量 `KIMI_MCP_STARTUP_TIMEOUT_MS` 和 `KIMI_MCP_TOOL_TIMEOUT_MS` 覆盖，优先级高于配置文件。MCP server 的完整配置方式见 [MCP](../customization/mcp.md)。 @@ -398,7 +394,7 @@ k3-max = "同一模型的 max Thinking 档位。适合最难的子任务。" | 字段 | 类型 | 默认值 | 说明 | | --- | --- | --- | --- | | `name` | `string` | — | Agent 在系统提示词中的自称（填充 `${product_name}` 变量，你自己的 `SYSTEM.md` 和 agent 文件同样适用） | -| `slug` | `string` | 由 `name` 派生 | 协议字段中使用的机器标识：发给第三方 provider 的 `User-Agent` 产品名，以及连接 MCP 服务器时声明的客户端名。省略时由 `name` 派生：转小写，连续的非字母数字字符折叠为 `-` | +| `slug` | `string` | 由 `name` 派生 | 协议字段中的机器标识：`User-Agent` 产品名与 MCP 客户端名；省略时由 `name` 派生（转小写，非字母数字折叠为 `-`） | ```toml [identity] @@ -406,11 +402,11 @@ name = "Acme Dev Agent" slug = "acme-dev" # 可选 ``` -两个字段都可以通过 `KIMI_CODE_IDENTITY_NAME` 和 `KIMI_CODE_IDENTITY_SLUG` 环境变量设置，优先级高于 `config.toml`，且不会被写回配置文件——适合不便写配置文件的容器和 CI 场景。 +两个字段都可以通过 `KIMI_CODE_IDENTITY_NAME` 和 `KIMI_CODE_IDENTITY_SLUG` 环境变量设置，优先级高于 `config.toml`，且不会被写回配置文件，适合不便写配置文件的容器和 CI 场景。 如果名称中不含任何 ASCII 字母或数字（例如纯中文名称），就无法派生出 slug，此时回退为 `agent`；需要特定协议标识请显式填写 `slug`。 -身份在启动时解析一次，进程生命周期内保持不变——建立连接时它已宣告给 MCP 服务器和 provider，中途无法更换。修改本节配置在下次启动时对新会话生效；resume 的会话保留录制时的系统提示词，因为其历史轮次本就以原身份自称。同理，已完成的 MCP OAuth 授权保留其授予时的客户端注册；重置该服务器的认证即可在新身份下重新注册。 +身份在启动时解析一次，进程生命周期内保持不变：建立连接时它已宣告给 MCP 服务器和 provider，中途无法更换。修改本节配置在下次启动时对新会话生效；resume 的会话保留录制时的系统提示词，因为其历史轮次本就以原身份自称。同理，已完成的 MCP OAuth 授权保留其授予时的客户端注册；重置该服务器的认证即可在新身份下重新注册。 本节由默认的 `agent-core-v2` 引擎读取。设置 `KIMI_CODE_LEGACY_FLAG=1` 后，旧版 `kimi` / `kimi -p` 路径会忽略此配置；`kimi web` 始终使用 `agent-core-v2`。 @@ -423,7 +419,7 @@ slug = "acme-dev" # 可选 | `enabled` | `array` | — | 全局允许列表：非空时仅列出的工具可用；省略或设为空数组均表示不约束 | | `disabled` | `array` | — | 全局禁止列表，在 `enabled` 之后应用 | -工具名匹配规则与 Agent 文件中的同名字段一致：内置工具按名称精确匹配（如 `Read`），MCP 工具用 glob 匹配（如 `mcp__github__*`）。有三种写法永远匹配不到任何工具，出现时会给出警告：`mcp__` 模式之外使用通配符（`enabled = ["*"]` 会禁用所有工具，而 `disabled = ["*"]` 什么也禁不掉）；缺少工具段的 `mcp__` 字面量（`mcp__github` —— 匹配整个服务器要用 `mcp__github__*`）；以及任何已注册或内置工具都没有的名字（匹配区分大小写）。 +工具名匹配规则与 Agent 文件中的同名字段一致：内置工具按名称精确匹配（如 `Read`），MCP 工具用 glob 匹配（如 `mcp__github__*`）。有三种写法永远匹配不到任何工具，出现时会给出警告：`mcp__` 模式之外使用通配符（`enabled = ["*"]` 会禁用所有工具，而 `disabled = ["*"]` 什么也禁不掉）；缺少工具段的 `mcp__` 字面量（`mcp__github`，匹配整个服务器要用 `mcp__github__*`）；以及任何已注册或内置工具都没有的名字（匹配区分大小写）。 ```toml [tools] @@ -441,7 +437,7 @@ disabled = ["EnterPlanMode", "ExitPlanMode", "mcp__github__*"] | 字段 | 类型 | 默认值 | 说明 | | --- | --- | --- | --- | | `max_edge_px` | `integer` | `2000` | 图片最长边上限（像素）。超过时按比例缩小到该值以内；调大可保留更多细节，代价是更大的请求体积 | -| `read_byte_budget` | `integer` | `262144`（256 KB） | 模型自行读取的图片（`ReadMediaFile` 默认读取）的单图字节预算。会话中模型反复截图、读图时，累计请求体大小由它控制；细节可通过 `region` 参数按原图坐标全保真回读（`region` 与 `full_resolution` 不受此预算限制） | +| `read_byte_budget` | `integer` | `262144`（256 KB） | 模型自行读取图片的单图字节预算（`ReadMediaFile` 默认读取）；`region` 与 `full_resolution` 回读不受此限制 | `max_edge_px` 可被环境变量 `KIMI_IMAGE_MAX_EDGE_PX` 覆盖，`read_byte_budget` 可被 `KIMI_IMAGE_READ_BYTE_BUDGET` 覆盖，优先级均高于配置文件。 @@ -487,7 +483,7 @@ api_key = "sk-xxx" | 字段 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `decision` | `string` | 是 | 匹配后的处置：`allow`（直接放行）、`deny`（直接拒绝）、`ask`（每次询问） | -| `scope` | `string` | 否 | 规则有效范围：`turn-override`、`session-runtime`、`project`、`user`；默认 `user` | +| `scope` | `string` | 否 | 规则有效范围：`turn-override`、`session-runtime`、`project`、`user`，默认 `user` | | `pattern` | `string` | 是 | 匹配模式，格式为 `工具名` 或 `工具名(参数模式)`，如 `Read`、`Bash(rm -rf*)` | | `reason` | `string` | 否 | 规则说明，仅用于调试和审计 | @@ -521,16 +517,23 @@ MCP server 的声明配置写在 `~/.kimi-code/mcp.json` 或项目内 `.kimi-cod | 字段 | 类型 | 默认值 | 说明 | | --- | --- | --- | --- | -| `theme` | `string` | `auto` | 配色主题：`auto`（跟随终端）、`dark`、`light`，或[自定义主题](../customization/themes.md)的名字 | -| `render_latex` | `boolean` | `true` | 将 Markdown 消息中的 LaTeX 公式（`$…$`、`$$…$$`）渲染为 Unicode 文本；`false` 则保留原始源码 | +| `theme` | `string` | `auto` | 配色主题：`auto`、`dark`、`light` 或[自定义主题](../customization/themes.md)名 | +| `render_latex` | `boolean` | `true` | 将 Markdown 中的 LaTeX 公式渲染为 Unicode 文本；`false` 保留原始源码 | | `disable_paste_burst` | `boolean` | `false` | 禁用非 bracketed paste 的粘贴突发兜底；默认开启，避免快速多行粘贴被逐行提交 | -| `cache_expiry_hint` | `boolean` | `true` | resume 长时间未活动的会话、或长时间空闲后发送消息时，若上下文缓存可能已过期则弹出提醒，可选择先压缩或新建会话（仅 v2 引擎） | +| `cache_expiry_hint` | `boolean` | `true` | resume 或长时间空闲后发消息时，若上下文缓存可能过期则提醒，可先压缩或新建会话（仅 v2 引擎） | | `[editor].command` | `string` | `""` | 编写长输入用的外部编辑器命令；留空则回退到 `$VISUAL` / `$EDITOR` | | `[notifications].enabled` | `boolean` | `true` | 是否发送桌面通知 | | `[notifications].notification_condition` | `string` | `unfocused` | 何时通知：`unfocused`（仅终端失去焦点时）或 `always`（总是） | | `[upgrade].auto_install` | `boolean` | `true` | 是否自动安装新版本 | -| `[status_line].items` | `string[]` | `[]` | 底部状态栏第一行展示哪些内置槽位及其顺序：`mode`、`goal`、`model`、`tasks`、`cwd`、`git`、`tips`。缺省保持默认布局；未知 id 跳过并告警 | -| `[status_line].command` | `string` | `""` | 自定义状态栏命令。其 stdout 第一行替换状态栏第一行，stdin 会收到 JSON 快照（model、cwd、git 分支、permission 模式、plan 模式、上下文用量、session id、版本）。运行上限 300ms、每秒最多一次；失败时回退内置布局 | +| `[status_line].items` | `string[]` | `[]` | 底部状态栏第一行的内置槽位及顺序：`mode`、`goal`、`model`、`tasks`、`cwd`、`git`、`tips`，未知 id 跳过并告警 | +| `[status_line].command` | `string` | `""` | 自定义状态栏命令：stdout 首行替换状态栏，stdin 收 JSON 快照；上限 300ms、每秒一次，失败回退内置布局 | + +
+command 的 stdin 输入 + +model、cwd、git 分支、permission 模式、plan 模式、上下文用量、session id、版本。 + +
```toml # ~/.kimi-code/tui.toml @@ -568,7 +571,7 @@ auto_install = true | 字段 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | -| `additional_dir` | `array` | 否 | 额外工作目录列表，以绝对路径存储。在 `/add-dir` 中确认"记住此目录"时自动写入；启动时读回，使这些目录在该项目的每个会话中都可用 | +| `additional_dir` | `array` | 否 | 额外工作目录列表（绝对路径）；在 `/add-dir` 确认"记住此目录"时自动写入，该项目每个会话可用 | ```toml [workspace] diff --git a/docs/zh/configuration/data-locations.md b/docs/zh/configuration/data-locations.md index 302198278f8..e1a87c0b869 100644 --- a/docs/zh/configuration/data-locations.md +++ b/docs/zh/configuration/data-locations.md @@ -1,6 +1,6 @@ # 数据路径 -Kimi Code CLI 把所有运行时数据——配置文件、会话历史、登录凭据、诊断日志——集中存放在 `~/.kimi-code/` 下。本页帮你搞清楚每类数据在哪里、用来做什么，以及需要时怎么清理或搬迁。 +Kimi Code CLI 把配置文件、会话历史、登录凭据、诊断日志等运行时数据集中存放在 `~/.kimi-code/` 下。本页帮你搞清楚每类数据在哪里、用来做什么，以及需要时怎么清理或搬迁。 ## 数据根目录 @@ -61,7 +61,7 @@ $KIMI_CODE_HOME （默认 ~/.kimi-code） 数据根下的顶层文件各有用途，大部分由 CLI 自动管理： - **`config.toml`**：主运行时配置，存放供应商、模型、循环控制等用户级设置。详见[配置文件](./config-files.md)。 -- **`tui.toml`**：终端界面客户端偏好，包括 `[upgrade].auto_install`（自动更新，默认开启）。可在 `/settings` 关闭，或手动设为 `auto_install = false`。 +- **`tui.toml`**：终端界面客户端偏好，包括自动更新开关 `[upgrade].auto_install`（默认开启）。可在 `/settings` 关闭，或手动设为 `auto_install = false`。 - **`AGENTS.md`**：全局 Kimi 专属 Agent 指令。该文件会随 `KIMI_CODE_HOME` 移动；跨工具通用指令仍可放在 `~/.agents/AGENTS.md`。 - **`mcp.json`**：用户级 MCP server 声明，启动时与项目内的 `.kimi-code/mcp.json` 合并加载。详见 [MCP](../customization/mcp.md)。 - **`skills/`**：Kimi 专属用户级 Skills。该目录会随 `KIMI_CODE_HOME` 移动；跨工具通用 Skills 仍可放在 `~/.agents/skills/`。详见 [Agent Skills](../customization/skills.md)。 @@ -80,7 +80,7 @@ $KIMI_CODE_HOME （默认 ~/.kimi-code） - **`agents/main/plans/`**：Plan 模式下写入的计划文件，按计划 id 命名（`.md`）。 - **`agents/agent-0/` 等**：subagent 实例目录，各自含 `wire.jsonl`。 - **`logs/kimi-code.log`**：该会话的诊断日志，只有发生诊断事件时才存在。 -- **`tasks/`**：后台任务持久化——`tasks/.json` 保存状态/pid/退出码，`tasks//output.log` 保存输出。 +- **`tasks/`**：后台任务持久化。`tasks/.json` 保存状态/pid/退出码，`tasks//output.log` 保存输出。 - **`cron/`**：定时任务持久化，用 `kimi --session` 恢复会话时重新加载到调度器。详见[定时任务](../reference/tools.md#定时任务)。 ## 内置工具缓存 diff --git a/docs/zh/configuration/env-vars.md b/docs/zh/configuration/env-vars.md index b7c3411cb7e..3bae4e7754d 100644 --- a/docs/zh/configuration/env-vars.md +++ b/docs/zh/configuration/env-vars.md @@ -1,11 +1,11 @@ # 环境变量 -Kimi Code CLI 通过环境变量控制少数运行时行为——迁移数据目录、关闭遥测、不改配置文件临时切换模型。 +Kimi Code CLI 通过环境变量控制少数运行时行为：迁移数据目录、关闭遥测、不改配置文件临时切换模型。 ::: warning 重要：API 密钥不在这里配置 -`KIMI_API_KEY`、`ANTHROPIC_API_KEY`、`OPENAI_API_KEY` 等密钥变量**不会**从 shell 环境变量自动读取。在终端里 `export KIMI_API_KEY=xxx` 不会让任何供应商获得密钥——必须写在 `config.toml` 的 `[providers.]` 段或 `[providers..env]` 子表里。 +`KIMI_API_KEY`、`ANTHROPIC_API_KEY`、`OPENAI_API_KEY` 等密钥变量**不会**从 shell 环境变量自动读取。在终端里 `export KIMI_API_KEY=xxx` 不会让任何供应商获得密钥。密钥必须写在 `config.toml` 的 `[providers.]` 段或 `[providers..env]` 子表里。 -唯一的例外是 `KIMI_MODEL_*` 系列，它是一个显式通道，*确实*会从 shell 读取凭证——详见[用环境变量定义模型](#用环境变量定义模型-kimi-model)。 +唯一的例外是 `KIMI_MODEL_*` 系列，它是一个显式通道，*确实*会从 shell 读取凭证。详见[用环境变量定义模型](#用环境变量定义模型kimi_model_)。 背景说明见[配置覆盖：供应商凭证](./overrides.md#供应商凭证)。 ::: @@ -34,11 +34,15 @@ export KIMI_DISABLE_TELEMETRY=1 ### `KIMI_MODEL_*` 系列 -不修改 `config.toml` 临时切换模型——设置 `KIMI_MODEL_NAME` 后，CLI 在内存里合成一个临时供应商，重启后失效。详见[用环境变量定义模型](#用环境变量定义模型-kimi-model)。 +不修改 `config.toml` 临时切换模型：设置 `KIMI_MODEL_NAME` 后，CLI 在内存里合成一个临时供应商，重启后失效。详见[用环境变量定义模型](#用环境变量定义模型kimi_model_)。 ### `KIMI_CODE_CUSTOM_HEADERS` -为所有出站的模型请求附加自定义 HTTP 请求头——LLM 聊天请求（所有供应商协议）和 `/models` 模型列表请求都会携带。适合网关按请求头路由的场景，例如指定集群： +::: info 新增 +新增于 0.20.2。 +::: + +为所有出站的模型请求附加自定义 HTTP 请求头：LLM 聊天请求（所有供应商协议）和 `/models` 模型列表请求都会携带。适合网关按请求头路由的场景，例如指定集群： ```sh export KIMI_CODE_CUSTOM_HEADERS=$'X-Gateway-Cluster: my-cluster\nX-Custom-Tag: debug' @@ -46,15 +50,11 @@ export KIMI_CODE_CUSTOM_HEADERS=$'X-Gateway-Cluster: my-cluster\nX-Custom-Tag: d 格式与 `ANTHROPIC_CUSTOM_HEADERS` 一致：由换行分隔的 `Name: Value` 行，键名和值两端的空白会被去除，不含冒号的行会被忽略。 -::: info 新增 -新增于 0.20.2。 -::: - -> 优先级：Kimi 身份头（`User-Agent`、`X-Msh-*`）和 `config.toml` 里供应商的 `custom_headers`（见 [配置文件](./config-files.md#providers)）会覆盖这里的同名条目。认证头的行为因协议而异：在 `kimi`、`openai`、`openai_responses` 协议上，`Authorization` 条目会替换生成的 bearer token；`/models` 列表请求始终使用自己的认证头。`authorization` 这类大小写变体不会被当作同名头——它会与真正的头合并，可能导致请求失败。不要用它设置认证等保留头。需要按供应商区分请求头时，请改用 `custom_headers`。 +> 优先级：Kimi 身份头（`User-Agent`、`X-Msh-*`）和 `config.toml` 里供应商的 `custom_headers`（见 [配置文件](./config-files.md#providers)）会覆盖这里的同名条目。认证头的行为因协议而异：在 `kimi`、`openai`、`openai_responses` 协议上，`Authorization` 条目会替换生成的 bearer token；`/models` 列表请求始终使用自己的认证头。`authorization` 这类大小写变体不会被当作同名头。它会与真正的头合并，可能导致请求失败。不要用它设置认证等保留头。需要按供应商区分请求头时，请改用 `custom_headers`。 ## 供应商凭证键（写在 config.toml 里） -下面这些键名不是直接从 shell 读取的——它们是写在 `config.toml` 的 `[providers..env]` 子表里、作为 `api_key` / `base_url` 备用来源的键名。CLI 只从配置文件读取，不从 `process.env` 读取。 +下面这些键名不是直接从 shell 读取的。它们是写在 `config.toml` 的 `[providers..env]` 子表里、作为 `api_key` / `base_url` 备用来源的键名。CLI 只从配置文件读取，不从 `process.env` 读取。 这样设计是为了让你保留熟悉的键名写法，同时把密钥放在配置文件里统一管理： @@ -80,7 +80,7 @@ KIMI_BASE_URL = "https://api.moonshot.ai/v1" | `GOOGLE_CLOUD_LOCATION` | Vertex AI | 无 | ::: warning -`GOOGLE_APPLICATION_CREDENTIALS`（服务账号 JSON 路径）是唯一走系统环境变量的例外——它由 Google SDK 自身通过 ADC 流程读取，CLI 不参与。其他所有键名都必须写在 `[providers..env]` 子表里。 +`GOOGLE_APPLICATION_CREDENTIALS`（服务账号 JSON 路径）是唯一走系统环境变量的例外。它由 Google SDK 自身通过 ADC 流程读取，CLI 不参与。其他所有键名都必须写在 `[providers..env]` 子表里。 ::: 供应商类型与字段的完整说明见[平台与模型](./providers.md)。 @@ -137,40 +137,40 @@ kimi | 环境变量 | 用途 | 合法值 | | --- | --- | --- | | `KIMI_DISABLE_TELEMETRY` | 关闭匿名遥测上报 | `1`、`true`、`yes`、`y`（不区分大小写） | -| `KIMI_CODE_PASSWORD` | 为 `kimi web` 本地服务设置并列鉴权密码，与 bearer token 同时有效；把服务绑定到非本机地址时建议设置，见 [在网页中使用：安全注意](../guides/web.md#安全注意) | 任意非空字符串；未设置时仅 token 有效 | +| `KIMI_CODE_PASSWORD` | 为 `kimi web` 本地服务设置并列鉴权密码；绑到非本机地址时建议设置，见 [安全注意](../guides/web.md#安全注意) | 任意非空字符串；未设置时仅 token 有效 | | `KIMI_CODE_BACKGROUND_KEEP_ALIVE_ON_EXIT` | 会话关闭时是否保留后台任务，优先级高于 `config.toml`。默认会在退出时停止后台任务 | 真值：`1`/`true`/`yes`/`on`；假值：`0`/`false`/`no`/`off` | -| `KIMI_CODE_BACKGROUND_MAX_RUNNING_TASKS` | 同时运行的后台任务数上限，优先级高于 `config.toml` 的 `[background] max_running_tasks`（不设置表示无上限） | 正整数；非法值被忽略 | +| `KIMI_CODE_BACKGROUND_MAX_RUNNING_TASKS` | 同时运行的后台任务数上限，优先级高于 `config.toml` 的 `[background] max_running_tasks`；不设置表示无上限 | 正整数；非法值被忽略 | | `KIMI_IMAGE_MAX_EDGE_PX` | 图片压缩的最长边上限（像素），优先级高于 `config.toml` 的 `[image] max_edge_px`（默认 `2000`） | 正整数；非法值被忽略 | -| `KIMI_IMAGE_READ_BYTE_BUDGET` | 模型自行读图（`ReadMediaFile` 默认读取）的单图字节预算，优先级高于 `config.toml` 的 `[image] read_byte_budget`（默认 `262144`，即 256 KB） | 正整数；非法值被忽略 | -| `KIMI_CODE_PLUGIN_MARKETPLACE_URL` | 覆盖 `/plugins` 加载的 plugin marketplace JSON，适合 dev loopback server、测试 CDN 文件或替换 marketplace 目录 | `https://code.kimi.com/kimi-code/plugins/marketplace.json`；也接受 `http://`、`file://` URL 和本地路径 | +| `KIMI_IMAGE_READ_BYTE_BUDGET` | 模型自行读图的单图字节预算，优先级高于 `config.toml` 的 `[image] read_byte_budget`（默认 `262144`） | 正整数；非法值被忽略 | +| `KIMI_CODE_PLUGIN_MARKETPLACE_URL` | 覆盖 `/plugins` 加载的 marketplace JSON；默认 `https://code.kimi.com/kimi-code/plugins/marketplace.json` | 也接受 `http://`、`file://` URL 和本地路径 | | `KIMI_CODE_AGENT_SWARM_MAX_CONCURRENCY` | 限制 AgentSwarm 初始提升并发阶段可同时运行的 subagent 数量；不设置表示不限制 | 正整数；非法值会立即失败 | -| `KIMI_SUBAGENT_TIMEOUT_MS` | 单个 `Agent` subagent 可运行的最长时间（毫秒）；优先级高于 `config.toml` 的 `[subagent] timeout_ms`（默认 `7200000`，即 2 小时） | 正整数；非法值回退到配置或默认值 | -| `KIMI_CODE_SWARM_TIMEOUT_MS` | 单个 `AgentSwarm` subagent 可运行的最长时间（毫秒）；优先级高于 `config.toml` 的 `[swarm] timeout_ms`（默认 `7200000`，即 2 小时） | 正整数；非法值回退到配置或默认值 | -| `KIMI_CODE_IDENTITY_NAME` | Agent 在系统提示词中的自称，优先级高于 `config.toml` 的 `[identity] name`，且不会被写回配置文件 | 任意非空字符串；空值视为未设置 | -| `KIMI_CODE_IDENTITY_SLUG` | 协议标识，用于发给第三方 provider 的 `User-Agent` 产品名和 MCP 客户端名，优先级高于 `[identity] slug`。未设置时由名称派生 | 任意非空字符串；会转小写并将连续非字母数字字符折叠为 `-` | -| `KIMI_CODE_BUILTIN_PRODUCT_SKILLS` | 是否向模型提供介绍 Kimi Code 自身的内置 Skills，优先级高于 `config.toml` 的 `builtin_product_skills`（默认开启） | 真值：`1`/`true`/`yes`/`on`；假值：`0`/`false`/`no`/`off` | -| `KIMI_CODE_TUI_FULL_SCREEN` | 启用实验性的 fullscreen alternate-screen 界面：可滚动的 transcript 视口、鼠标选择文本、可点击链接、Ctrl-Shift-F 搜索 | `1` 开启；其他值保持常规内联界面 | -| `KIMI_CODE_EXPERIMENTAL_SECONDARY_MODEL` | [subagent 模型池](./config-files.md#subagent-模型池) 默认启用，在包括交互式 TUI 在内的所有启动方式下生效；设为假值可禁用；master `KIMI_CODE_EXPERIMENTAL_FLAG=1` 也会启用本功能 | 真值：`1`/`true`/`yes`/`on`；假值：`0`/`false`/`no`/`off` | -| `KIMI_CODE_EXPERIMENTAL_SUBAGENT_FORK` | 在 `Agent` 和 `AgentSwarm` 工具上启用实验性的 `fork` 参数，让模型可以以调用方 Agent 对话历史的快照而不是空上下文启动 subagent；master `KIMI_CODE_EXPERIMENTAL_FLAG=1` 也会启用本功能 | 真值：`1`/`true`/`yes`/`on`；假值：`0`/`false`/`no`/`off` | -| `KIMI_MCP_STARTUP_TIMEOUT_MS` | 所有 MCP server 的全局默认连接超时（毫秒）；优先级高于 `config.toml` 的 `[mcp] startup_timeout_ms`，但低于 `mcp.json` 中单个 server 的 `startupTimeoutMs`（默认 `30000`） | `1` 到 `2147483647` 的整数；非法值被忽略 | -| `KIMI_MCP_TOOL_TIMEOUT_MS` | 所有 MCP server 的全局默认单次工具调用超时（毫秒）；优先级高于 `config.toml` 的 `[mcp] tool_timeout_ms`，但低于 `mcp.json` 中单个 server 的 `toolTimeoutMs`（默认 `60000`） | `1` 到 `2147483647` 的整数；非法值被忽略 | -| `KIMI_LOOP_MAX_STEPS_PER_TURN` | Agent 单轮最大步数；优先级高于 `config.toml` 的 `[loop_control] max_steps_per_turn`（不设或 `0` 表示无上限） | 非负整数；非法值被忽略 | -| `KIMI_LOOP_MAX_ATTEMPTS_PER_STEP` | 单步失败后的最大总尝试次数（含首次尝试）；优先级高于 `config.toml` 的 `[loop_control] max_attempts_per_step`（默认 `10`）。旧的 `KIMI_LOOP_MAX_RETRIES_PER_STEP` 已废弃，但在本变量未设置时仍生效并给出警告 | 非负整数；非法值被忽略 | -| `KIMI_CODE_INFINITE_RETRY` | 让所有失败的 LLM 请求无限重试（包括轮次内步骤和 compaction 等后台操作）而不是终止任务；重试等待按指数退避（32 秒封顶）并尊重服务端 `Retry-After` 头，等待期间中断仍立即生效。适用于端点可能短暂故障的长时间无人值守评测 | 真值：`1`/`true`/`yes`/`on`；假值：`0`/`false`/`no`/`off` | -| `KIMI_TOKEN_COUNTING_STRATEGY` | 对外上报的上下文 token 计数（上下文大小显示）；优先级高于 `config.toml` 的 `[token_counting] strategy`（默认 `measured+estimated`） | `measured+estimated`、`measured`、`estimated`（不区分大小写）；非法值被忽略 | -| `KIMI_WEB_SEARCH_BASE_URL` | 网页搜索（`WebSearch`）服务的 API URL；优先级高于 `config.toml` 的 `[services.moonshot_search] base_url`，未写配置段时也可启用服务。文件中持久化的凭据和自定义 header 不会发送到环境变量指定的端点 | 非空字符串；空白值被忽略 | +| `KIMI_SUBAGENT_TIMEOUT_MS` | 单个 `Agent` subagent 可运行的最长时间（毫秒），优先级高于 `config.toml` 的 `[subagent] timeout_ms` | 正整数；非法值回退到配置或默认值 | +| `KIMI_CODE_SWARM_TIMEOUT_MS` | `AgentSwarm` subagent 可运行的最长时间（毫秒），优先级高于 `config.toml` 的 `[swarm] timeout_ms` | 正整数；非法值回退到配置或默认值 | +| `KIMI_CODE_IDENTITY_NAME` | Agent 在系统提示词中的自称，优先级高于 `config.toml` 的 `[identity] name`，不写回配置文件 | 任意非空字符串；空值视为未设置 | +| `KIMI_CODE_IDENTITY_SLUG` | 协议标识（`User-Agent` 产品名、MCP 客户端名），优先级高于 `[identity] slug`；未设置时由名称派生 | 任意非空字符串；会转小写并将连续非字母数字字符折叠为 `-` | +| `KIMI_CODE_BUILTIN_PRODUCT_SKILLS` | 是否向模型提供介绍 Kimi Code 自身的内置 Skills，优先级高于 `config.toml` 的 `builtin_product_skills` | 真值：`1`/`true`/`yes`/`on`；假值：`0`/`false`/`no`/`off` | +| `KIMI_CODE_TUI_FULL_SCREEN` | 启用实验性的 fullscreen 界面：可滚动 transcript、鼠标选择、可点击链接、Ctrl-Shift-F 搜索 | `1` 开启；其他值保持常规内联界面 | +| `KIMI_CODE_EXPERIMENTAL_SECONDARY_MODEL` | 启用实验性的 [subagent 模型池](./config-files.md#subagent-模型池)，所有启动方式生效 | 真值：`1`/`true`/`yes`/`on`；假值：`0`/`false`/`no`/`off` | +| `KIMI_CODE_EXPERIMENTAL_SUBAGENT_FORK` | 在 `Agent`/`AgentSwarm` 上启用实验性 `fork` 参数：以调用方对话历史快照而非空上下文启动 subagent | 真值：`1`/`true`/`yes`/`on`；假值：`0`/`false`/`no`/`off` | +| `KIMI_MCP_STARTUP_TIMEOUT_MS` | MCP server 全局默认连接超时（毫秒）；优先级高于配置文件，低于 `mcp.json` 的 `startupTimeoutMs` | `1` 到 `2147483647` 的整数；非法值被忽略 | +| `KIMI_MCP_TOOL_TIMEOUT_MS` | MCP server 全局默认单次工具调用超时（毫秒）；优先级高于配置文件，低于 `mcp.json` 的 `toolTimeoutMs` | `1` 到 `2147483647` 的整数；非法值被忽略 | +| `KIMI_LOOP_MAX_STEPS_PER_TURN` | Agent 单轮最大步数，优先级高于 `config.toml` 的 `[loop_control] max_steps_per_turn`；`0` 表示无上限 | 非负整数；非法值被忽略 | +| `KIMI_LOOP_MAX_ATTEMPTS_PER_STEP` | 单步失败后的最大总尝试次数（含首次尝试），优先级高于 `config.toml` 的 `[loop_control] max_attempts_per_step` | 非负整数；非法值被忽略 | +| `KIMI_CODE_INFINITE_RETRY` | 让所有失败的 LLM 请求无限重试而不是终止任务；指数退避（32 秒封顶）并尊重 `Retry-After`，等待期间中断仍生效 | 真值：`1`/`true`/`yes`/`on`；假值：`0`/`false`/`no`/`off` | +| `KIMI_TOKEN_COUNTING_STRATEGY` | 对外上报的上下文 token 计数，优先级高于 `config.toml` 的 `[token_counting] strategy` | `measured+estimated`、`measured`、`estimated`（不区分大小写）；非法值被忽略 | +| `KIMI_WEB_SEARCH_BASE_URL` | 网页搜索（`WebSearch`）服务的 API URL，优先级高于配置文件；凭据与自定义 header 不发往该端点 | 非空字符串；空白值被忽略 | | `KIMI_WEB_SEARCH_API_KEY` | 网页搜索（`WebSearch`）服务的 API 密钥；设置后同时替换配置中的 API 密钥和 OAuth 凭据 | 非空字符串；空白值被忽略 | -| `KIMI_WEB_FETCH_BASE_URL` | 网页抓取（`FetchURL`）服务的 API URL；优先级高于 `[services.moonshot_fetch] base_url`。文件中持久化的凭据和自定义 header 不会发送到环境变量指定的端点。环境变量和配置都没有指定端点时，已登录用户会先尝试 Kimi OAuth 托管抓取服务，再回退到本地直接请求 | 非空字符串；空白值被忽略 | +| `KIMI_WEB_FETCH_BASE_URL` | 网页抓取（`FetchURL`）服务的 API URL，优先级高于配置文件；未指定端点时已登录用户走 Kimi OAuth 托管抓取，再回退本地直连；凭据不发往该端点 | 非空字符串；空白值被忽略 | | `KIMI_WEB_FETCH_API_KEY` | 网页抓取（`FetchURL`）服务的 API 密钥；设置后同时替换配置中的 API 密钥和 OAuth 凭据 | 非空字符串；空白值被忽略 | -| `KIMI_CODE_EXPERIMENTAL_FLAG` | 在当前进程启用所有已注册的实验功能；单个功能的 `KIMI_CODE_EXPERIMENTAL_` 变量或 `config.toml` 的 `[experimental]` 节中的显式配置优先于它；不用于选择 Agent 引擎 | `1`、`true`、`yes`、`on` | -| `KIMI_CODE_LEGACY_FLAG` | 让 `kimi`、`kimi -p`、`kimi doctor`、`kimi export` 和 `kimi provider` 使用旧版 `agent-core` 引擎；这些命令默认使用 `agent-core-v2` | `1`、`true`、`yes`、`on` | +| `KIMI_CODE_EXPERIMENTAL_FLAG` | 在当前进程启用所有已注册的实验功能；不用于选择 Agent 引擎 | `1`、`true`、`yes`、`on` | +| `KIMI_CODE_LEGACY_FLAG` | 让 `kimi` 系列命令使用旧版 `agent-core` 引擎（默认 `agent-core-v2`） | `1`、`true`、`yes`、`on` | | `KIMI_SHELL_PATH` | Windows 上覆盖 Git Bash 路径（自动探测失败时使用） | 绝对路径 | | `KIMI_MODEL_MAX_COMPLETION_TOKENS` | 单步 LLM 请求的 `max_completion_tokens` 硬上限，仅对 `kimi` 供应商生效 | 正整数；`0` 或负数禁用 clamp | | `KIMI_MODEL_TEMPERATURE` | 每次请求的采样温度，仅对 `kimi` 供应商生效（全局生效，不依赖 `KIMI_MODEL_NAME`） | 数字，如 `0.3` | | `KIMI_MODEL_TOP_P` | 每次请求的核采样 `top_p`，仅对 `kimi` 供应商生效（全局生效） | 数字，如 `0.95` | -| `KIMI_MODEL_THINKING_EFFORT` | 在线上强制使用指定的思考强度（`thinking.effort`），绕过模型声明的 `support_efforts`；仅对 `kimi` 供应商生效，且仅在 Thinking 开启时注入 | 思考强度值，如 `max` | -| `KIMI_MODEL_THINKING_KEEP` | 保留思考透传；在 `kimi` 上以 `thinking.keep` 发送，在 `anthropic`（Claude 以及 Kimi 的 Anthropic 兼容模式）上以 `context_management` 的 `clear_thinking_20251015` 编辑发送（开启 keep 会让 Anthropic 请求走 beta Messages API）；覆盖 `[thinking] keep`（其默认值为 `"all"`）；仅在 Thinking 开启时注入 | API 接受的值，如 `all`；传入关值（`false`/`0`/`no`/`off`/`none`/`null`）可禁用 | -| `KIMI_CODE_NO_AUTO_UPDATE` | 完全禁用更新预检——不检查、不后台安装、不提示。同时兼容旧名 `KIMI_CLI_NO_AUTO_UPDATE` | 真值：`1`/`true`/`yes`/`on` | +| `KIMI_MODEL_THINKING_EFFORT` | 在线上强制使用指定的思考强度，绕过模型声明的 `support_efforts`；仅 `kimi` 供应商生效 | 思考强度值，如 `max` | +| `KIMI_MODEL_THINKING_KEEP` | 保留思考透传；`kimi` 以 `thinking.keep` 发送，`anthropic` 以 `clear_thinking_20251015` 编辑发送；覆盖 `[thinking] keep` | API 接受的值，如 `all`；传入关值（`false`/`0`/`no`/`off`/`none`/`null`）可禁用 | +| `KIMI_CODE_NO_AUTO_UPDATE` | 完全禁用更新预检：不检查、不后台安装、不提示。同时兼容旧名 `KIMI_CLI_NO_AUTO_UPDATE` | 真值：`1`/`true`/`yes`/`on` | | `KIMI_DISABLE_CRON` | 禁用定时任务工具（`CronCreate` 拒绝新计划，已有任务不触发） | `1` 表示禁用 | `KIMI_CODE_INFINITE_RETRY`、`KIMI_CODE_IDENTITY_*` 和 `KIMI_CODE_BUILTIN_PRODUCT_SKILLS` 这几个变量由默认的 `agent-core-v2` 引擎读取。设置 `KIMI_CODE_LEGACY_FLAG=1` 后，旧版 `kimi` / `kimi -p` 路径会忽略它们。 @@ -203,16 +203,22 @@ CLI 还会读取一些标准系统变量来检测运行环境，不会修改它 ## HTTP 代理 -Kimi Code 会遵循标准代理环境变量，让所有出网流量——模型 API 调用、MCP 服务、网络工具、遥测、登录、更新检查——都走代理： +Kimi Code 会遵循标准代理环境变量，让所有出网流量（模型 API 调用、MCP 服务、网络工具、遥测、登录、更新检查）都走代理： - `HTTP_PROXY` / `http_proxy`：用于 `http://` 请求的代理 - `HTTPS_PROXY` / `https_proxy`：用于 `https://` 请求的代理 -- `ALL_PROXY` / `all_proxy`：当对应 scheme 的变量未设置时使用的兜底代理；SOCKS 代理通常设在这里 +- `ALL_PROXY` / `all_proxy`：当对应 scheme 的变量未设置时使用的兜底代理 - `NO_PROXY` / `no_proxy`：以逗号分隔的、绕过代理的主机列表 -同时支持 HTTP(S) 代理和 SOCKS 代理。SOCKS 代理通过 scheme 识别——`socks5://`、`socks5h://`、`socks4://` 或 `socks://`（`socks5://` 的别名）——通常设在 `ALL_PROXY`（Clash、V2RayN 等工具使用的形式）。对 HTTP/HTTPS 流量，HTTP(S) 代理优先于 `ALL_PROXY`。 +### 代理类型与优先级 + +同时支持 HTTP(S) 代理和 SOCKS 代理。SOCKS 代理通过 scheme 识别：`socks5://`、`socks5h://`、`socks4://` 或 `socks://`（`socks5://` 的别名），通常设在 `ALL_PROXY`。对 HTTP/HTTPS 流量，HTTP(S) 代理优先于 `ALL_PROXY`。 + +### 启用条件与回环地址 + +仅当设置了其中任一变量时才启用代理，否则直连。回环地址（`localhost`、`127.0.0.1`、`::1`）始终绕过代理，因此配置了代理后，本地服务（例如 localhost 上的 MCP 服务）仍能正常工作。你也可以把自己的内网主机加入 `NO_PROXY` 一并放行。 -仅当设置了其中任一变量时才启用代理，否则直连。回环地址（`localhost`、`127.0.0.1`、`::1`）始终绕过代理，因此配置了代理后，本地服务（例如 localhost 上的 MCP 服务）仍能正常工作——你也可以把自己的内网主机加入 `NO_PROXY` 一并放行。 +### MCP 子进程 以 Node 子进程运行的 stdio MCP 服务，在其 Node 版本支持 `NODE_USE_ENV_PROXY` 时（Node ≥ 22.21 或 ≥ 24.5）会自动遵循 `HTTP_PROXY` / `HTTPS_PROXY` / `NO_PROXY`；SOCKS 代理仅作用于 Kimi Code 自身的流量。 diff --git a/docs/zh/configuration/overrides.md b/docs/zh/configuration/overrides.md index 402c097a597..cdc792c62af 100644 --- a/docs/zh/configuration/overrides.md +++ b/docs/zh/configuration/overrides.md @@ -1,24 +1,24 @@ # 配置覆盖 -Kimi Code CLI 有三个地方可以影响运行参数：配置文件、命令行选项、环境变量。它们不是简单的"谁优先级高谁赢"——三者面向不同场景，作用范围互不相同： +Kimi Code CLI 有三个地方可以影响运行参数：配置文件、命令行选项、环境变量。三者并非简单的优先级叠加，而是面向不同场景、作用范围互不相同： - **配置文件** 保存长期偏好（模型、密钥、循环控制等），每次启动都生效 - **命令行选项** 做本次启动的临时切换，退出后失效 -- **环境变量** 主要负责数据目录定位、OAuth 端点切换，以及少数运行时开关——**不是配置字段的通用后备来源** +- **环境变量** 主要负责数据目录定位、OAuth 端点切换，以及少数运行时开关。它**不是配置字段的通用后备来源** -这个区别很关键：很多人会在 shell 里 `export KIMI_API_KEY=xxx`，以为 CLI 会自动取到，但实际上不会。原因见下文[供应商凭证](#供应商凭证)。 +凭证解析不读取 shell 环境变量：在终端 `export KIMI_API_KEY=xxx` 不会生效。原因见下文[供应商凭证](#供应商凭证)。 ## 环境变量的三类作用 环境变量按作用分三类，不能合并成一条线性优先级： 1. **定位配置文件**：`KIMI_CODE_HOME` 决定数据根目录，配置文件路径因此变为 `$KIMI_CODE_HOME/config.toml`。这一步先于其他所有解析，不是普通参数的后备来源。 -2. **运行时开关**：`KIMI_DISABLE_TELEMETRY` 等少量变量直接关闭对应子系统——即使 `config.toml` 里 `telemetry = true`，只要这个变量是真值，遥测就会被禁用。语义是"额外禁用"，不是"普通覆盖"。 +2. **运行时开关**：`KIMI_DISABLE_TELEMETRY` 等少量变量直接关闭对应子系统。即使 `config.toml` 里 `telemetry = true`，只要这个变量是真值，遥测就会被禁用。语义是"额外禁用"，不是"普通覆盖"。 3. **运行端点与诊断**：`KIMI_CODE_OAUTH_HOST`、`KIMI_CODE_BASE_URL`、`KIMI_LOG_LEVEL` 等在 OAuth 或日志子系统初始化时读取。完整列表见[环境变量](./env-vars.md)。 ## 普通运行参数的优先级 -对模型别名、Plan 模式、权限模式、Skills 目录等普通运行参数，优先级从高到低： +对模型别名、[Plan 模式](../guides/interaction.md#plan-模式)、[yolo 模式](../guides/interaction.md#三种权限模式)、Skills 目录等普通运行参数，优先级从高到低： 1. **命令行选项**（`-m`、`--plan`、`--yolo` 等）：仅对本次启动生效 2. **用户配置文件**（`~/.kimi-code/config.toml`）：保存长期偏好 @@ -26,10 +26,10 @@ 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..env]` 子表）读取，不会回退到 shell 里 `export` 的变量。唯一的例外是显式的 `KIMI_MODEL_*` 通道——详见[用环境变量定义模型](./env-vars.md#用环境变量定义模型-kimi-model)。 +**普通运行参数不会从 shell 环境变量取后备值。** 供应商的 `api_key` / `base_url` 只从 `config.toml`（包括 `[providers..env]` 子表）读取，不会回退到 shell 里 `export` 的变量。唯一的例外是显式的 `KIMI_MODEL_*` 通道，详见[用环境变量定义模型](./env-vars.md#用环境变量定义模型kimi_model_)。 ::: -目前 CLI 只读取一份用户级配置文件，没有项目级配置文件机制。需要在不同项目间隔离配置时，用 `KIMI_CODE_HOME` 指向不同的数据目录——见下文[典型场景](#典型场景)。 +目前 CLI 只读取一份用户级配置文件，没有项目级配置文件机制。需要在不同项目间隔离配置时，用 `KIMI_CODE_HOME` 指向不同的数据目录，见下文[典型场景](#典型场景)。 ## 供应商凭证 @@ -37,15 +37,15 @@ Kimi Code CLI 有三个地方可以影响运行参数：配置文件、命令行 对单个供应商，凭证按以下顺序解析： -1. `[providers.].api_key` — 配置文件里直接写的密钥，优先级最高 -2. `[providers..env]` 子表里的对应键（`KIMI_API_KEY`、`ANTHROPIC_API_KEY` 等）— `api_key` 为空时才读这里 +1. `[providers.].api_key`：配置文件里直接写的密钥，优先级最高 +2. `[providers..env]` 子表里的对应键（`KIMI_API_KEY`、`ANTHROPIC_API_KEY` 等）：`api_key` 为空时才读这里 3. 两者都缺 → 启动报错，提示该供应商缺少凭证 `base_url` 的解析方式相同：先读 `[providers.].base_url`，再读 `[providers..env]` 里的 `*_BASE_URL` 键。 -> `[providers..env]` 子表只是配置文件里的一段 TOML，不会真正写入 shell 环境变量。仅当对应的直接字段（`api_key` / `base_url`）为空时，CLI 才会查这里。 +> `[providers..env]` 子表只是配置文件里的一段 TOML，不会真正写入 shell 环境变量。仅当对应的直接字段（`api_key` / `base_url`）为空时，CLI 才会读取该子表。 -完整的凭证键名列表见[环境变量：供应商凭证键](./env-vars.md#供应商凭证键-写在-config-toml-里)。 +完整的凭证键名列表见[环境变量：供应商凭证键](./env-vars.md#供应商凭证键写在-configtoml-里)。 ## 命令行选项 @@ -55,8 +55,8 @@ Kimi Code CLI 有三个地方可以影响运行参数：配置文件、命令行 | --- | --- | | `-S, --session [id]` | 恢复指定会话；不带 id 时进入交互式选择 | | `-c, --continue` | 续上当前目录的上一次会话 | -| `-y, --yolo` | "Ask When Needed" 模式：常规修改和命令自动完成，Agent 仍可能提问 | -| `--auto` | "Never Ask" 模式：完全不打断，Agent 不会向用户提问 | +| `-y, --yolo` | 自动批准普通工具调用，Agent 仍可能提问 | +| `--auto` | 以 auto 权限模式启动：完全自主，Agent 不会向用户提问 | | `--plan` | 以 Plan 模式启动 | | `-m, --model ` | 指定本次使用的模型别名 | | `-p, --prompt ` | 非交互模式：执行单条提示词后退出 | @@ -76,13 +76,13 @@ Kimi Code CLI 有三个地方可以影响运行参数：配置文件、命令行 ## 典型场景 -**隔离测试环境**——用单独的数据目录，避免污染主配置和会话： +**隔离测试环境**：用单独的数据目录，避免污染主配置和会话： ```sh KIMI_CODE_HOME="$PWD/.kimi-sandbox" kimi ``` -**一次性使用测试密钥**——由于供应商凭证只从配置文件读，把测试密钥写进 `env` 子表： +**一次性使用测试密钥**：由于供应商凭证只从配置文件读，把测试密钥写进 `env` 子表： ```toml [providers.kimi.env] diff --git a/docs/zh/configuration/providers.md b/docs/zh/configuration/providers.md index f97df28030b..87755927a3c 100644 --- a/docs/zh/configuration/providers.md +++ b/docs/zh/configuration/providers.md @@ -1,6 +1,6 @@ # 平台与模型 -Kimi Code CLI 支持同时接入多家 LLM 平台——用 Kimi Code 托管服务一键登录、用 Anthropic API key 接 Claude、用 OpenAI 兼容协议连接第三方推理服务。每个供应商对应一种 API 协议，模型在供应商之上声明自己的名称、上下文长度和能力。本页介绍如何在 `config.toml` 里配置各种供应商。 +Kimi Code CLI 支持同时接入多家模型供应商服务，模型在供应商之上声明自己的名称、上下文长度和能力。本页介绍如何在 `config.toml` 里配置各种供应商。 ## 支持的供应商类型 @@ -8,21 +8,23 @@ Kimi Code CLI 支持同时接入多家 LLM 平台——用 Kimi Code 托管服 | 类型 | 协议 | 典型用途 | | --- | --- | --- | -| `kimi` | OpenAI 兼容 | Kimi Code 托管服务、Kimi Platform API 密钥 | -| `anthropic` | Anthropic Messages | Claude 系列模型 | -| `openai` | OpenAI Chat Completions | OpenAI 及兼容服务、DeepSeek、Qwen 等 | -| `openai_responses` | OpenAI Responses API | OpenAI 较新的 Responses 接口 | -| `google-genai` | Google GenAI | Gemini API | -| `vertexai` | Google GenAI on Vertex | Google Cloud Vertex AI | +| [`kimi`](#kimi) | OpenAI 兼容 | Kimi Code 托管服务、Kimi Platform API 密钥 | +| [`anthropic`](#anthropic) | Anthropic Messages | Claude 系列模型 | +| [`openai`](#openai) | OpenAI Chat Completions | OpenAI 及兼容服务、DeepSeek、Qwen 等 | +| [`openai_responses`](#openai_responses) | OpenAI Responses API | OpenAI 较新的 Responses 接口 | +| [`google-genai`](#google-genai) | Google GenAI | Gemini API | +| [`vertexai`](#vertexai) | Google GenAI on Vertex | Google Cloud Vertex AI | 所有供应商默认以流式方式与模型交互。thinking、视觉、工具调用等能力按模型名前缀自动匹配，通常不需要手动声明。 -**凭证优先级**：`api_key` 直接字段 > `[providers..env]` 子表键 > 两者都缺时启动报错。CLI 不会从 shell 环境变量自动取凭证——详见[配置覆盖：供应商凭证](./overrides.md#供应商凭证)。 +**凭证优先级**：`api_key` 直接字段 > `[providers..env]` 子表键 > 两者都缺时启动报错。CLI 不会从 shell 环境变量自动取凭证，详见[配置覆盖：供应商凭证](./overrides.md#供应商凭证)。 ## `/provider` — 交互式供应商管理 不想手动编辑 TOML？在 TUI 里输入 `/provider` 打开**供应商管理器**，可以以交互方式添加或删除供应商。 +![/provider 供应商管理器](../../media/provider-manager.jpg) + 管理器按来源把供应商显示为一行行条目。操作方式： - ↑/↓ 移动光标，←/→ 翻页 @@ -134,7 +136,7 @@ base_url = "https://your-gateway.example" 与 `google-genai` 共用实现，`type = "vertexai"` 时切换到 Vertex AI 访问路径。 -认证走 Google Cloud 标准 ADC 流程（`gcloud auth application-default login` 或 `GOOGLE_APPLICATION_CREDENTIALS` 服务账号 JSON），这部分与 Kimi Code 无关。**项目 ID 和区域必须写在 `[providers.vertexai.env]` 子表里**——直接在 shell 里 `export GOOGLE_CLOUD_PROJECT` 不会被 CLI 读取。 +认证走 Google Cloud 标准 ADC 流程（`gcloud auth application-default login` 或 `GOOGLE_APPLICATION_CREDENTIALS` 服务账号 JSON），这部分与 Kimi Code 无关。**项目 ID 和区域必须写在 `[providers.vertexai.env]` 子表里**。直接在 shell 里 `export GOOGLE_CLOUD_PROJECT` 不会被 CLI 读取。 ```toml [providers.vertexai] @@ -150,11 +152,8 @@ gcloud auth application-default login # 一次性完成认证 kimi ``` -如需让 Vertex 请求走自定义（如代理）端点，可设置 `base_url`（或 `GOOGLE_VERTEX_BASE_URL` 环境变量）；不填时使用 SDK 默认的区域化 `*-aiplatform.googleapis.com` 地址。与 `google-genai` 一样，只填主机根地址——SDK 会自行追加 `/v1beta1/publishers/google/models/…`。 - -## OAuth 与凭证注入 +如需让 Vertex 请求走自定义（如代理）端点，可设置 `base_url`（或 `GOOGLE_VERTEX_BASE_URL` 环境变量）；不填时使用 SDK 默认的区域化 `*-aiplatform.googleapis.com` 地址。与 `google-genai` 一样，只填主机根地址。SDK 会自行追加 `/v1beta1/publishers/google/models/…`。 -Kimi Code 托管服务使用 OAuth 而非静态 API 密钥。运行 `/login` 后，内置的认证工具链会自动写入并刷新凭证，`config.toml` 里无需手动配置这部分内容。 ## 下一步 diff --git a/docs/zh/customization/agents.md b/docs/zh/customization/agents.md index 7d8d119aba6..cb849ff923b 100644 --- a/docs/zh/customization/agents.md +++ b/docs/zh/customization/agents.md @@ -1,6 +1,6 @@ # Agent 与 subagent -Kimi Code CLI 中的每次会话都由一个**main agent** 驱动。main agent 理解用户意图、规划步骤、调用工具，并在需要时向外派发**subagent** 处理更聚焦的子任务——例如探索一个陌生代码库、并行审阅多处实现、或在不触碰主上下文的情况下规划一次大型重构。 +Kimi Code CLI 中的每次会话都由一个 **main agent** 驱动。main agent 理解用户意图、规划步骤、调用工具，并在需要时向外派发 **subagent** 处理更聚焦的子任务：探索一个陌生代码库、并行审阅多处实现、或在不触碰主上下文的情况下规划一次大型重构。 subagent 接受 main agent 给出的任务描述，在自己的独立上下文里工作，最后把结论返回。它不会与用户直接对话，中间的思考和工具调用记录也不会混入 main agent 的历史。 @@ -12,13 +12,21 @@ Kimi Code CLI 内置三种 subagent，开箱即用，分别面向不同任务形 - **`explore`**：代码库探索专用，只做只读操作，不修改任何文件。适合在不改动文件的前提下快速搜索、阅读和总结仓库。 - **`plan`**：实现规划与架构设计专用，连 Shell 命令都不提供，专注于"想清楚怎么做"而不是"动手做"。 -`coder` subagent 与 main agent 共享大部分工具集：可以在后台执行 Shell 命令、维护待办列表、进入 Plan 模式、调用 Agent Skills。内置 subagent 都不能继续派发新的 subagent。自定义 Agent 缺省时继承内置委派列表（`coder`、`explore`、`plan`），而这些内置类型自身同样不能再派发，因此委派链默认必然终止——不存在不受限的递归派发。自定义 Agent 可以通过显式声明 [`subagents`](#agent-文件格式) 列表来获得更深的委派链。如果 subagent 结束自己的轮次时仍有后台任务在运行，那么只有在这些后台任务全部落定后，这次运行才会回报完成——main agent 拿到结果时，背后的工作也已经真正完成。 +三种类型之外，使用 subagent 还有三条约定，分别关于工具边界、委派深度和完成时机： + +`coder` subagent 与 main agent 共享大部分工具集：可以在后台执行 Shell 命令、维护待办列表、进入 Plan 模式、调用 Agent Skills。三种内置 subagent 都不能继续派发新的 subagent。 + +自定义 Agent 缺省时继承内置委派列表（`coder`、`explore`、`plan`），这些内置类型自身不能再派发，因此委派链默认必然终止，不存在不受限的递归派发。如需更深的委派链，可以在 Agent 文件中显式声明 [`subagents`](#agent-文件格式) 列表。 + +如果 subagent 结束自己的轮次时仍有后台任务在运行，这次运行会等这些后台任务全部落定后才回报完成。main agent 拿到结果时，背后的工作也已经真正完成。 ## 调用方式 -subagent 由 main agent 自动调度——根据任务复杂度、上下文消耗和子任务的独立性，在适当时机派发，无需用户手动指定。 +调度的完整链路只有三个环节：派发、审批、回收，都不需要手动管理。 + +subagent 由 main agent 自动调度：根据任务复杂度、上下文消耗和子任务的独立性，在适当时机派发，无需用户手动指定。 -每次派发都会在终端以审批请求的形式呈现（除非命中 allow 规则或处于 "Ask When Needed" 模式），方便你审视任务描述。你也可以在对话中直接指示 main agent 使用特定 subagent，例如"先用 explore 把相关文件梳理一遍再动手"。 +每次派发都会在终端以审批请求的形式呈现，方便你审视任务描述，除非你已用 allow 规则放行或处于 YOLO 模式。你也可以在对话中直接指示 main agent 使用特定 subagent，例如"先用 explore 把相关文件梳理一遍再动手"。 subagent 支持在后台运行：完成后结果自动回到 main agent，无需手动轮询。也可以唤回已有的 subagent 实例继续推进同一任务。 @@ -31,7 +39,7 @@ subagent 支持在后台运行：完成后结果自动回到 main agent，无需 - **main agent 上下文保持精炼**，长会话中不会被大量探索性日志撑满。 - **多个 subagent 可以并行运行**，互不干扰。 -需要注意的是，每个 subagent 都会独立消耗模型 token。简单任务没有必要派发 subagent，main agent 直接处理更经济。 +每个 subagent 都会独立消耗模型 token。简单任务没有必要派发 subagent，由 main agent 直接处理更经济。 ## 权限继承 @@ -41,19 +49,23 @@ subagent 的权限规则继承自 main agent：main agent 通过 `/permission` ## 自定义 Agent -除了三个内置 subagent，你还可以用 Markdown 文件定义自己的 Agent。每个文件描述一个 Agent：文件顶部的 Frontmatter（YAML 元数据）声明名称、描述和工具权限，文件正文是它的系统提示词。自定义 Agent 可以作为 subagent 被委派 —— main agent 会自动发现它们，与内置 subagent 并列 —— 也可以在启动时选为 main agent。 +除了三个内置 subagent，你还可以用 Markdown 文件定义自己的 Agent。每个文件描述一个 Agent：文件顶部的 Frontmatter 声明名称、描述和工具权限，文件正文是它的系统提示词。 + +自定义 Agent 可以作为 subagent 被委派：main agent 会自动发现它们，与内置 subagent 并列。自定义 Agent 也可以在启动时选为 main agent。 ### Agent 目录 Kimi Code CLI 按作用域发现 Agent 文件，作用域越具体，优先级越高：**显式（`--agent-file`）> 项目 > 额外 > 用户 > Plugin > 内置**。两个文件定义了相同的 `name` 时，高优先级作用域胜出。每个目录都会递归扫描 `.md` 文件。 **用户级**（对所有项目生效）： + - `$KIMI_CODE_HOME/agents/`（默认：`~/.kimi-code/agents/`） - `~/.agents/agents/` Kimi 专属的用户 Agent 目录随 `KIMI_CODE_HOME` 移动，通用的 `~/.agents/agents/` 目录留在真实用户目录下，便于跨工具共享。 -**项目级**（项目根目录 = 从工作目录向上查找、最近的包含 `.git` 的目录）： +**项目级**：项目根目录指从工作目录向上查找、最近的包含 `.git` 的目录。可用位置： + - `.kimi-code/agents/` - `.agents/agents/` @@ -63,12 +75,14 @@ Kimi 专属的用户 Agent 目录随 `KIMI_CODE_HOME` 移动，通用的 `~/.age extra_agent_dirs = ["~/team-agents", ".agents/team-agents"] ``` -**Plugin 级**：已启用 plugin 在其 manifest 的 `agents` 字段中声明的目录（省略时自动采用 plugin 根下的 `agents/` 目录），见[插件 Agent](./plugins.md#插件-agent)。Plugin Agent 优先级仅高于内置 Agent。 +**Plugin 级**：已启用 plugin 在其 manifest 的 `agents` 字段中声明的目录，省略时自动采用 plugin 根下的 `agents/` 目录，见 [插件 Agent](./plugins.md#插件-agent)。Plugin Agent 优先级仅高于内置 Agent。 -**内置 Agent** 随 CLI 分发，优先级最低。目录中发现的文件不会仅凭同名覆盖内置 Agent；如确需替换，必须在 Frontmatter 中声明 `override: true`。通过 `--agent-file` 加载的文件视为显式启动意图，可以覆盖同名内置 Agent，优先级高于所有目录作用域，且仅对本次启动生效。另外，`$KIMI_CODE_HOME/SYSTEM.md` 可永久覆盖默认 main agent 的系统提示词（它不参与 Agent 文件发现），其优先级交互见下文 SYSTEM.md 小节。 +**内置 Agent** 随 CLI 分发，优先级最低。目录中发现的文件不会仅凭同名覆盖内置 Agent；如确需替换，必须在 Frontmatter 中声明 `override: true`。通过 `--agent-file` 加载的文件视为显式启动意图，可以覆盖同名内置 Agent，优先级高于所有目录作用域，且仅对本次启动生效。 + +另外，`$KIMI_CODE_HOME/SYSTEM.md` 可永久覆盖默认 main agent 的系统提示词，它不参与 Agent 文件发现，优先级交互见 [SYSTEM.md 小节](#用-systemmd-覆盖-main-agent-的系统提示词)。 ::: warning 信任模型 -Agent 文件属于提示词配置，而项目级文件来自仓库本身 —— 包括你刚刚 clone、尚不可信的仓库。项目作用域的文件可以完全接管内置 Agent：命名为 `agent.md` 并声明 `override: true` 会替换**默认 main agent 的整个系统提示词**，`coder.md` 加 `override: true` 则会替换默认 subagent 类型。与 `AGENTS.md` 内容（作为参考资料注入提示词）不同，override 文件**就是**系统提示词本身，且不写 `tools` 的文件保留全部工具。在不熟悉的仓库中运行 Kimi Code 之前，请以对待脚本同样的谨慎检查其中的 `.kimi-code/agents/` 与 `.agents/agents/` 目录。 +Agent 文件属于提示词配置，而项目级文件来自仓库本身，包括你刚刚 clone、尚不可信的仓库。项目作用域的文件可以完全接管内置 Agent：命名为 `agent.md` 并声明 `override: true` 会替换**默认 main agent 的整个系统提示词**，`coder.md` 加 `override: true` 则会替换默认 subagent 类型。不同于把 `AGENTS.md` 内容作为参考资料注入提示词，override 文件本身就是系统提示词，且不写 `tools` 的文件保留全部工具。在不熟悉的仓库中运行 Kimi Code 之前，请以对待脚本同样的谨慎检查其中的 `.kimi-code/agents/` 与 `.agents/agents/` 目录。 ::: ### Agent 文件格式 @@ -93,23 +107,29 @@ disallowedTools: 你是严格的代码审查者。阅读 diff 后，按严重度分级报告问题…… ``` +各字段的含义如下： + | 字段 | 必填 | 说明 | | --- | --- | --- | -| `name` | 否 | kebab-case 唯一标识。缺省时取文件名（去掉扩展名，如 `review.md` → `review`）；解析后名字缺失或不是 kebab-case 的文件会被跳过并告警 | +| `name` | 否 | kebab-case 唯一标识。缺省时取文件名去掉扩展名后的部分；名字缺失或不是 kebab-case 的文件会被跳过并告警 | | `description` | 是 | Agent 的用途。main agent 挑选 subagent 时会看到，请围绕委派决策来写 | | `whenToUse` | 否 | 补充说明何时应使用该 Agent | | `override` | 否 | 是否允许覆盖同名内置 Agent，默认 `false`。`--agent-file` 属于显式启动意图，无需设置此字段 | -| `tools` | 否 | 工具名允许列表，如 `Read`、`Bash`；MCP 工具用 glob 匹配，如 `mcp__github__*`。支持 YAML 列表或逗号分隔字符串（`tools: Read, Grep`）两种写法。缺省表示允许全部工具；单独的 `*` 同样表示允许全部工具；空列表（`tools: []`）表示禁用全部工具 | -| `disallowedTools` | 否 | 禁止列表，写法与匹配规则相同，在 `tools` 之后应用 | -| `subagents` | 否 | 允许委派的 subagent 名称列表，写法与 `tools` 相同（YAML 列表或逗号分隔字符串）。缺省表示继承默认 Agent 的委派列表（内置默认为 `coder`、`explore`、`plan`，它们自身都不能再派发，因此继承得到的链路必然终止）；单独的 `*` 表示可委派所有类型。main agent 的有效委派列表还会自动并入所有发现的自定义 Agent，因此自定义 Agent 默认即可被委派 | +| `tools` | 否 | 工具允许列表。MCP 工具用 glob 匹配（如 `mcp__github__*`）；支持 YAML 列表或逗号分隔字符串。缺省或单独的 `*` 表示允许全部工具，空列表表示禁用全部工具 | +| `disallowedTools` | 否 | 工具禁止列表，写法与匹配规则和 `tools` 相同，在 `tools` 之后应用 | +| `subagents` | 否 | 允许委派的 subagent 名称列表，写法与 `tools` 相同。缺省继承内置默认委派列表，单独的 `*` 表示可委派所有类型。main agent 的有效委派列表会自动并入所有发现的自定义 Agent | + +内置工具与用户工具按名称精确匹配（区分大小写）；以 `mcp__` 开头的条目按 glob 匹配 MCP 工具。以下三种写法永远匹配不到任何工具，在 profile 生效时会给出警告： -内置工具与用户工具按名称精确匹配（区分大小写）；以 `mcp__` 开头的条目按 glob 匹配 MCP 工具。有三种写法永远匹配不到任何工具，在 profile 生效时会给出警告：`mcp__` 模式之外使用通配符（`disallowedTools` 里单独的 `*` 什么也禁不掉）；不是完整 `mcp__<服务器>__<工具>` 形式的 `mcp__` 字面量（`mcp__github` 匹配不到任何工具 —— 匹配整个服务器要用 `mcp__github__*`）；以及任何已注册或内置工具都没有的名字（通常是笔误，如把 `Read` 写成 `read`）。 +- 在 `mcp__` 模式之外使用通配符：`disallowedTools` 里单独的 `*` 什么也禁不掉。 +- 写不全的 `mcp__` 字面量：`mcp__github` 匹配不到任何工具；匹配整个服务器要用 `mcp__github__*`。 +- 任何已注册或内置工具都没有的名字：通常是笔误，如把 `Read` 写成 `read`。 -正文即 Agent 的系统提示词，每次构建提示词时都会作为模板渲染：`${var}` 占位符替换为实时上下文值——未知变量保持原样，单独的 `$` 没有特殊含义，上下文中缺失的变量渲染为空字符串。`${base_prompt}` 会在你放置它的位置嵌入有效默认系统提示词（内置默认，或存在时为你的 `SYSTEM.md` 覆盖），因此文件可以"包裹"默认行为而不是替换它。如果文件会替换默认提示词、但仍要保留已启用 plugin 提供的指令，请把 `${plugin_sections}` 放在希望出现这些指令的位置。可用变量见下文 SYSTEM.md 变量表。 +正文即 Agent 的系统提示词，每次构建提示词时都会作为模板渲染。`${var}` 占位符替换为实时上下文值：未知变量保持原样，单独的 `$` 没有特殊含义，上下文中缺失的变量渲染为空字符串。`${base_prompt}` 会在放置它的位置嵌入有效默认系统提示词（内置默认，或存在时为你的 `SYSTEM.md` 覆盖），因此文件可以包裹默认行为而不是替换它。如果文件替换默认提示词后仍要保留已启用 plugin 提供的指令，把 `${plugin_sections}` 放在希望出现这些指令的位置即可。可用变量见 [SYSTEM.md 变量表](#用-systemmd-覆盖-main-agent-的系统提示词)。 -未知字段会被忽略，新版本写的文件在旧版本上仍可读取。其他 Agent 工具的字段（如 Claude Code 的 `model`、OpenCode 的 `mode`）同样会被忽略；加上 `tools` 的逗号分隔写法和 `name` 缺省回退到文件名，Claude Code 与 OpenCode 风格的 Agent 文件一般可直接加载 —— 只含 `description` 和正文的最小文件可跨工具通用。 +未知字段会被忽略，新版本写的文件在旧版本上仍可读取。其他 Agent 工具的字段（如 Claude Code 的 `model`、OpenCode 的 `mode`）同样会被忽略。加上 `tools` 的逗号分隔写法和 `name` 缺省回退到文件名，Claude Code 与 OpenCode 风格的 Agent 文件一般可直接加载，只含 `description` 和正文的最小文件可跨工具通用。 -目录中发现的非法文件会被跳过并告警，不影响其他文件。通过 `--agent-file` 显式传入的文件必须合法 —— 否则 CLI 会报错并退出。 +目录中发现的非法文件会被跳过并告警，不影响其他文件。通过 `--agent-file` 显式传入的文件必须合法，否则 CLI 会报错并退出。 ::: warning 注意 `tools` 与 `disallowedTools` 不仅决定模型能"看到"哪些工具，还会在执行前再次强制检查。`subagents` 同样双重生效：`Agent` 工具的类型列表只包含允许委派的 subagent，`Agent` 与 `AgentSwarm` 在实际派发前都会强制校验；唤回已有 subagent 不受此限制。权限规则仍是独立的控制层，用于决定哪些操作需要审批。 @@ -124,7 +144,7 @@ disallowedTools: - **`--agent `**：以指定 Agent 作为 main agent 启动会话。名称可以指向内置 Agent 或任何已发现的文件；名称不存在时会报错，并列出可用的 Agent。 - **`--agent-file `**：以最高优先级加载一个 Agent 文件（仅本次启动）并以其启动。该 flag 只接受一个文件：不可重复传入，也不能与 `--agent` 同时使用。 -两个 flag 都仅在新建会话时有效——都不能与 `--session`/`--continue` 组合。Agent 在会话创建时绑定，恢复会话时会自动还原已绑定的 Agent，因此恢复时不需要（也不允许）携带这些 flag。 +两个 flag 都仅在新建会话时有效，不能与 `--session`/`--continue` 组合。Agent 在会话创建时绑定，恢复会话时会自动还原已绑定的 Agent，因此恢复时不需要（也不允许）携带这些 flag。 例如： @@ -133,17 +153,23 @@ kimi --agent reviewer kimi -p --agent reviewer "审查这个分支上的改动" ``` -绑定的 Agent 即会话的身份：在会话首次绑定后即固定，之后不可切换。在 TUI 中，这些 flag 只绑定启动时的会话；之后在同一进程内新建的会话（例如通过 `/new`）使用默认 Agent。 +绑定的 Agent 即会话的身份，在会话首次绑定后即固定，之后不可切换。在 TUI 中，这些 flag 只绑定启动时的会话；之后在同一进程内新建的会话（例如通过 `/new`）使用默认 Agent。 -定制 main agent 时，在正文中引用 `${base_prompt}` 可保持有效默认提示词中已有的环境、工作区指令、Skill 和 plugin 注入生效。如果要替换默认提示词、但只保留 plugin 提供的指令，请改用 `${plugin_sections}`。正文同时不引用 `${base_prompt}` 和 `${plugin_sections}` 时，会完全拥有自己的提示词并排除 plugin 指令，适合自包含的 subagent。 +定制 main agent 时，在正文中引用 `${base_prompt}` 可保留有效默认提示词中已有的环境、工作区指令、Skill 和 plugin 注入。要替换默认提示词、但只保留 plugin 提供的指令，改用 `${plugin_sections}`。正文同时不引用这两个变量时，Agent 拥有完全独立的提示词，plugin 指令不会注入，适合自包含的场景。 ### 用 SYSTEM.md 覆盖 main agent 的系统提示词 -希望永久覆盖 main agent 的系统提示词、而不必每次启动都传入 `--agent` 或 `--agent-file` 时，可以写一份 `$KIMI_CODE_HOME/SYSTEM.md`（默认：`~/.kimi-code/SYSTEM.md`，随 `KIMI_CODE_HOME` 移动）。文件存在且非空期间，它整体替换内置默认 main agent 的系统提示词——但只替换提示词，描述、工具集与允许委派的 subagent 列表仍沿用内置默认值。SYSTEM.md 在包括交互式 TUI 会话在内的所有启动方式下生效。 +希望永久覆盖 main agent 的系统提示词、而不必每次启动都传入 `--agent` 或 `--agent-file` 时，可以写一份 `$KIMI_CODE_HOME/SYSTEM.md`，默认位置为 `~/.kimi-code/SYSTEM.md`，随 `KIMI_CODE_HOME` 移动。文件存在且非空期间，它整体替换内置默认 main agent 的系统提示词；但只替换提示词，描述、工具集与允许委派的 subagent 列表仍沿用内置默认值。SYSTEM.md 在包括交互式 TUI 会话在内的所有启动方式下生效。 -SYSTEM.md 是纯 Markdown 正文，不需要也不读取 Frontmatter。文件缺失或为空时不生效；读取失败时会告警并回退到内置提示词。优先级上，显式意图仍然胜出：项目作用域中声明了 `override: true` 的同名 Agent 文件、通过 `--agent-file` 传入的文件都排在 SYSTEM.md 之前，用 `--agent` 选择其他 Agent 时 SYSTEM.md 也不会生效；而在用户作用域内部，SYSTEM.md 优先于 `agents/` 目录中扫描到的同名文件。 +SYSTEM.md 是纯 Markdown 正文，不需要也不读取 Frontmatter。文件缺失或为空时不生效；读取失败时会告警并回退到内置提示词。 -与普通 Agent 文件的正文一样，SYSTEM.md 在每次构建提示词时作为模板渲染——正文中的 `${var}` 占位符会被替换为实时上下文： +优先级上，显式意图仍然胜出： + +- 项目作用域中声明了 `override: true` 的同名 Agent 文件、通过 `--agent-file` 传入的文件都排在 SYSTEM.md 之前。 +- 用 `--agent` 选择其他 Agent 时，SYSTEM.md 不生效。 +- 在用户作用域内部，SYSTEM.md 优先于 `agents/` 目录中扫描到的同名文件。 + +与普通 Agent 文件的正文一样，SYSTEM.md 在每次构建提示词时作为模板渲染，正文中的 `${var}` 占位符会被替换为实时上下文： | 变量 | 内容 | | --- | --- | @@ -153,11 +179,14 @@ SYSTEM.md 是纯 Markdown 正文，不需要也不读取 Frontmatter。文件缺 | `${cwd_listing}` | 工作目录的文件列表 | | `${os}` | 操作系统类型 | | `${shell}` | Shell 名称与路径，例如 `bash (\`/bin/bash\`)` | +| `${now}` | 当前时间（ISO 格式） | | `${additional_dirs_info}` | 加入工作区的额外目录信息；没有时为空 | -| `${base_prompt}` | 默认系统提示词。在 `SYSTEM.md` 中指内置默认提示词；在 Agent 文件中指有效默认提示词（内置默认，或存在时为你的 `SYSTEM.md` 覆盖） | +| `${base_prompt}` | 默认系统提示词。在 `SYSTEM.md` 中指内置默认提示词；在 Agent 文件中指有效默认提示词（内置默认，或存在时的 `SYSTEM.md` 覆盖） | | `${plugin_sections}` | 已启用 plugin 提供的完整 Plugin Instructions 块；没有已启用 plugin 提供指令时为空 | -未知变量原样保留，单独的 `$` 没有特殊含义；上下文中缺失的变量渲染为空字符串。另有四个预组合块——`${windows_notes}`、`${additional_dirs_section}`、`${skills_section}`、`${plugin_sections}`——渲染对应的内置提示词段落，不适用时为空字符串。内置默认提示词已经包含 `${plugin_sections}`；当 `${base_prompt}` 已展开为该提示词时，不要再重复加入此变量。利用这些变量可以重建内置提示词的骨架，例如： +未知变量原样保留，单独的 `$` 没有特殊含义；上下文中缺失的变量渲染为空字符串。另有四个预组合块 `${windows_notes}`、`${additional_dirs_section}`、`${skills_section}`、`${plugin_sections}`，渲染对应的内置提示词段落，不适用时为空字符串。 + +内置默认提示词已经包含 `${plugin_sections}`；当 `${base_prompt}` 已展开为该提示词时，不要再重复加入此变量。利用这些变量可以重建内置提示词的骨架，例如： ```markdown You are Kimi, running at ${cwd} on ${os}. diff --git a/docs/zh/customization/hooks.md b/docs/zh/customization/hooks.md index b23ec914314..6ca70e94e4e 100644 --- a/docs/zh/customization/hooks.md +++ b/docs/zh/customization/hooks.md @@ -10,14 +10,14 @@ Hooks（钩子）是一种自动触发机制：你预先告诉 Kimi Code CLI"每 配置一条 hook 规则，需要指定三件事：**在什么事件上触发**、**匹配哪些目标**、**运行哪个脚本**。 -触发时，CLI 会把事件的详细信息（触发原因、工具名称、命令内容等）打包成 JSON（一种结构化文本格式），通过**标准输入**（stdin，程序运行时用来接收外部数据的通道）传给你的脚本。脚本读取这些信息后，决定怎么响应。 +触发时，CLI 会把事件的详细信息（触发原因、工具名称、命令内容等）打包成 JSON，通过**标准输入**（stdin，程序运行时用来接收外部数据的通道）传给脚本。脚本读取这些信息后，决定怎么响应。 脚本的响应结果由两样东西决定： - **退出码**（exit code，程序结束时向操作系统报告的状态数字）：`0` 表示放行，`2` 表示阻断，其他数字默认放行 -- **标准输出**（stdout，就是你用 `console.log` 或 `print` 打印出来的内容）：可以附带说明文字 +- **标准输出**（stdout，脚本打印到终端的内容）：可以附带说明文字 -即使脚本报错、超时，CLI 也**不会因此中断你的工作**——这种"出错就放行"的设计叫 fail-open（失败开放），避免 hook 异常变成绊脚石。 +即使脚本报错或超时，CLI 也**不会因此中断你的工作**。这种"出错就放行"的设计称为 fail-open（失败开放），避免 hook 异常阻塞主流程。 ::: warning 注意 正因为 fail-open，Hooks 适合做提醒和轻量拦截，但**不应作为唯一的安全防线**。对真正高风险的操作，仍需依赖权限审批和人工确认。 @@ -39,11 +39,11 @@ command = "terminal-notifier -title Kimi -message 'Task done'" ## 配置 -所有 hook 规则写在 `~/.kimi-code/config.toml` 的 `[[hooks]]` 数组里，每一项是一条规则： +所有 hook 规则写在 `~/.kimi-code/config.toml` 的 `[[hooks]]` 数组里： | 字段 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | -| `event` | `string` | 是 | 触发事件名，必须是下文「事件一览」表中的某一项 | +| `event` | `string` | 是 | 触发事件名，取值见 [事件一览](#事件一览) | | `matcher` | `string` | 否 | 用正则表达式（一种字符串匹配语法）过滤事件目标；不填则匹配全部 | | `command` | `string` | 是 | 触发时要运行的 Shell 命令 | | `timeout` | `integer` | 否 | 超时秒数，范围 1–600；默认 30 秒 | @@ -52,7 +52,14 @@ command = "terminal-notifier -title Kimi -message 'Task done'" **同一事件匹配多条规则时**，所有命中的 hook 并行运行；`command` 完全相同的多条规则只运行一次。 -Hook 命令的工作目录是当前会话的项目目录。非 Windows 平台上，hook 进程放在独立进程组里，超时时先发信号让它有机会善后，之后才强制终止。 +Hook 命令的工作目录是当前会话的项目目录。 + +
+进程组与超时处理 + +非 Windows 平台上，hook 进程运行在独立进程组中；超时后 CLI 先发送信号让脚本有机会善后，再强制终止。 + +
### 事件数据格式 @@ -68,7 +75,7 @@ Hook 命令的工作目录是当前会话的项目目录。非 Windows 平台上 } ``` -具体事件还会附带额外字段（如工具名称、命令内容），见下方事件一览。所有字段名使用下划线命名（snake_case）。 +具体事件还会附带额外字段（如工具名称、命令内容），见 [事件一览](#事件一览)。所有字段名使用下划线命名（snake_case）。 ## 返回值 @@ -92,38 +99,38 @@ Hook 命令的工作目录是当前会话的项目目录。非 Windows 平台上 } ``` -::: info 哪些事件支持阻断？ -只有**可阻断事件**（`PreToolUse`、`Stop`、`UserPromptSubmit`）的返回值会影响主流程。其余事件属于**观察型事件**——触发后即发即忘，不管脚本返回什么，主流程都不会改变。 +::: info 说明 +只有**可阻断事件**（`PreToolUse`、`Stop`、`UserPromptSubmit`）的返回值会影响主流程。其余事件属于**观察型事件**：触发后即发即忘，不管脚本返回什么，主流程都不会改变。 ::: ## 事件一览 | 事件 | Matcher 匹配的是 | 会触发阻断？ | 说明 | | --- | --- | --- | --- | -| `UserPromptSubmit` | 用户提交的文本内容 | ✓ | 用户发送消息时触发；返回文本会附加到上下文；若阻断，本轮不调用模型 | -| `UserPromptQueued` | 排队消息的文本内容 | — | 上一回合仍在运行、消息进入队列时触发；payload 含 `prompt_id`、`prompt` 和 `queue_length`（观察用） | -| `PreToolUse` | 工具名 | ✓ | 工具调用前触发（权限检查前）；阻断后工具不会执行 | +| `UserPromptSubmit` | 用户提交的文本内容 | ✓ | 用户发送消息时触发；返回文本会附加到上下文，阻断则本轮不调用模型 | +| `UserPromptQueued` | 排队消息的文本内容 | — | 上一回合仍在运行、新消息进入队列时触发；payload 含 `prompt_id`、`prompt`、`queue_length` | +| `PreToolUse` | 工具名 | ✓ | 工具调用前、权限检查前触发；阻断后工具不会执行 | | `Stop` | 空字符串 | ✓ | 模型准备结束本轮时触发；阻断后可追加一条消息让模型继续 | -| `TurnStarted` | 回合来源类型（如 `user`、`task`、`system_trigger`） | — | 新回合开始时触发；payload 含 `turn_id`、`origin_kind`、`origin_name` 和 `prompt`（观察用） | -| `PostToolUse` | 工具名 | — | 工具成功执行后触发（观察用） | -| `PostToolUseFailure` | 工具名 | — | 工具失败或被阻断后触发（观察用） | -| `PermissionRequest` | 工具名 | — | 即将等待用户审批前触发（观察用） | -| `PermissionResult` | 工具名 | — | 审批结束后触发（观察用） | -| `SessionStart` | `startup` 或 `resume` | — | 新会话启动或历史会话恢复后触发；payload 含 `source`、`model` 和 `profile` | +| `TurnStarted` | 回合来源类型（如 `user`、`task`、`system_trigger`） | — | 新回合开始时触发；payload 含 `turn_id`、`origin_kind`、`origin_name`、`prompt` | +| `PostToolUse` | 工具名 | — | 工具成功执行后触发 | +| `PostToolUseFailure` | 工具名 | — | 工具失败或被阻断后触发 | +| `PermissionRequest` | 工具名 | — | 即将等待用户审批前触发 | +| `PermissionResult` | 工具名 | — | 审批结束后触发 | +| `SessionStart` | `startup` 或 `resume` | — | 新会话启动或历史会话恢复后触发；payload 含 `source`、`model`、`profile` | | `SessionEnd` | `exit` 或 `archive` | — | 会话关闭后触发；`archive` 表示会话被归档而非退出 | -| `SessionHeartbeat` | 空字符串 | — | 会话存活期间每 60 秒触发一次；仅当配置了本事件时计时器才会运行。payload 含 `uptime_ms`（观察用） | +| `SessionHeartbeat` | 空字符串 | — | 会话存活期间每 60 秒触发一次，仅配置本事件时计时器才运行；payload 含 `uptime_ms` | | `SubagentStart` | subagent 名称 | — | subagent 开始运行前触发 | -| `SubagentStop` | subagent 名称 | — | subagent 成功完成后触发（观察用） | -| `TaskStarted` | 任务类型（`agent`、`process` 或 `question`） | — | 后台任务启动时触发；payload 含 `task_id`、`description` 和 `detached`（观察用） | -| `StopFailure` | 错误类型 | — | 本轮因错误失败后触发（观察用） | -| `Interrupt` | 空字符串 | — | 用户中断本轮时触发（例如按下 Esc）；超时或其他程序性中断不会触发。中断时 `Stop` 不会触发，由本事件替代。payload 含 `reason` 字段（观察用） | +| `SubagentStop` | subagent 名称 | — | subagent 成功完成后触发 | +| `TaskStarted` | 任务类型（`agent`、`process` 或 `question`） | — | 后台任务启动时触发；payload 含 `task_id`、`description`、`detached` | +| `StopFailure` | 错误类型 | — | 本轮因错误失败后触发 | +| `Interrupt` | 空字符串 | — | 用户中断本轮时触发（如按 Esc）；超时等程序性中断不触发，此时 `Stop` 由本事件替代；payload 含 `reason` | | `PreCompact` | `manual` 或 `auto` | — | 上下文压缩开始前触发；返回值被完全忽略 | -| `PostCompact` | `manual` 或 `auto` | — | 上下文压缩完成后触发（观察用） | -| `Notification` | 通知类型（如 `task.completed`） | — | 后台任务状态变化时触发（观察用） | +| `PostCompact` | `manual` 或 `auto` | — | 上下文压缩完成后触发 | +| `Notification` | 通知类型（如 `task.completed`） | — | 后台任务状态变化时触发 | ## 示例：阻断危险 Shell 命令 -下面的 hook 在 Agent 调用 `Bash` 工具前检查命令内容，发现 `rm -rf` 就阻断： +下面的 hook 在 Agent 调用 `Bash` 工具前检查命令内容，命中 `rm -rf` 时阻断： ```toml [[hooks]] diff --git a/docs/zh/customization/mcp.md b/docs/zh/customization/mcp.md index 02dc59015a6..3235d11b8d0 100644 --- a/docs/zh/customization/mcp.md +++ b/docs/zh/customization/mcp.md @@ -1,6 +1,6 @@ # Model Context Protocol -[Model Context Protocol（MCP）](https://modelcontextprotocol.io/) 是一个开放协议，让模型可以安全地调用外部进程或服务暴露的工具——例如读取 GitHub issues、查询数据库、操作本地文件系统。Kimi Code CLI 作为 MCP client 接入这些外部工具，并把它们与内置工具（`Read`、`Bash`、`Grep` 等）一起暴露给 Agent 使用，行为上没有差异。 +[Model Context Protocol（MCP）](https://modelcontextprotocol.io/) 是一个开放协议，让模型可以安全地调用外部进程或服务暴露的工具：读取 GitHub issues、查询数据库、操作本地文件系统。Kimi Code CLI 作为 MCP client 接入这些外部工具，把它们与内置工具一起暴露给 Agent 使用，行为上没有差异。 ## 接入方式 @@ -8,7 +8,7 @@ Kimi Code CLI 支持三种 MCP server 接入方式： - **stdio**：CLI 以子进程方式启动本地 MCP server，通过标准输入输出通信。适合本地命令行工具。 - **HTTP**：CLI 连接一个已在运行的 HTTP 端点。适合远程服务或需要持久运行的进程。 -- **SSE**：CLI 连接旧式 HTTP+SSE 端点（Server-Sent Events，一种流式 HTTP 机制）。新 MCP server 优先使用 HTTP；只有服务仍仅暴露旧式 SSE 传输时，才设置 `transport: "sse"`。 +- **SSE**：CLI 连接旧式 HTTP+SSE 端点。新 MCP server 优先使用 HTTP；只有服务仍仅暴露旧式 SSE 传输时，才设置 `transport: "sse"`。 ## 配置 @@ -21,9 +21,9 @@ MCP server 配置写在 `mcp.json` 中，分两层： 在 TUI 中运行 `/mcp-config` 可以交互式地新增、编辑或删除 server，无需手动编辑 JSON 文件。运行 `/mcp` 可查看当前所有 server 的连接状态。 -从配置中删除某个 server 不会打断进行中的会话：该 server 在 `/mcp` 中仍显示为 `removed`，其工具在这些会话中保持可见，但调用会失败并返回移除提示；新会话则完全不会注册这些工具。反过来，会话进行中新增的 server——无论是编辑 `mcp.json` 还是安装 plugin——都不会注册到已打开的会话中，只会加入之后创建的会话。 +从配置中删除某个 server 不会打断进行中的会话：该 server 在 `/mcp` 中仍显示为 `removed`，其工具在这些会话中保持可见，但调用会失败并返回移除提示；新会话则完全不会注册这些工具。反过来，编辑 `mcp.json` 或安装 plugin 新增的 server 也不会注册到已打开的会话，只会加入之后创建的会话。 -当 Kimi Code 在不受信任的文件夹中发现项目级 MCP server 时，工作区信任提示会显示每个 server 的传输方式和启动目标。提示默认选中 `Trust this folder`；请先核对列出的命令与参数或远程 URL，再确认信任。信任文件夹后，该工作区的项目级 MCP server 才会启用。 +当 Kimi Code 在不受信任的文件夹中发现项目级 MCP server 时，工作区信任提示会显示每个 server 的传输方式和启动目标。提示默认选中 `Trust this folder`；核对列出的命令与参数或远程 URL 后确认即可，选择 `Don't trust` 则该工作区的项目级 MCP server 不会启用。 `mcp.json` 的结构： @@ -56,8 +56,8 @@ MCP server 配置写在 `mcp.json` 中，分两层： | `headers` | `Record` | HTTP、SSE | 附加到每次请求的静态请求头 | | `bearerTokenEnvVar` | `string` | HTTP、SSE | 存放 bearer token 的环境变量名 | | `enabled` | `boolean` | 全部 | 设为 `false` 可禁用该 server | -| `startupTimeoutMs` | `number` | 全部 | 连接超时，取值范围为 `1` 到 `2147483647` 毫秒，默认 `30000` | -| `toolTimeoutMs` | `number` | 全部 | 单次工具调用超时，取值范围为 `1` 到 `2147483647` 毫秒 | +| `startupTimeoutMs` | `number` | 全部 | 连接超时，默认 `30000` 毫秒 | +| `toolTimeoutMs` | `number` | 全部 | 单次工具调用超时（毫秒） | | `enabledTools` | `string[]` | 全部 | 工具白名单 | | `disabledTools` | `string[]` | 全部 | 工具黑名单 | @@ -75,7 +75,7 @@ Plugins 也可以在 manifest 中声明 MCP servers。Plugin 声明的 servers MCP 工具按 `mcp____` 格式命名，例如 `mcp__github__create_issue`。权限规则中支持 `*` 和 `**` 通配，例如 `mcp__github__*` 命中该 server 下所有工具。MCP 工具参数不参与权限匹配。 -未命中权限规则的调用会触发审批请求；在审批弹窗中选择"Approve for this session"后，本次会话内的后续同类调用自动放行。 +未命中权限规则的调用会触发审批请求；在审批弹窗中选择“Approve for this session”后，本次会话内的后续同类调用自动放行。 也可以在 `config.toml` 的 `[[permission.rules]]` 中预置永久规则： @@ -89,7 +89,7 @@ decision = "deny" pattern = "mcp__filesystem__write_file" ``` -权限规则的完整语法见[配置文件](../configuration/config-files.md#permission)。 +权限规则的完整语法见 [配置文件](../configuration/config-files.md#permission)。 ## 安全性 @@ -100,7 +100,7 @@ pattern = "mcp__filesystem__write_file" - 对高风险工具（写文件、执行命令等）维持手动审批，避免用 `mcp__*` 通配放行全部工具 ::: warning 注意 -在 "Ask When Needed" 模式下，MCP 工具调用会被自动批准。仅在完全信任所接入的 MCP server 时使用此模式。 +在 [YOLO 模式](../guides/interaction.md#三种权限模式)下，MCP 工具调用会被自动批准。仅在完全信任所接入的 MCP server 时使用此模式。 ::: ## 下一步 diff --git a/docs/zh/customization/plugins.md b/docs/zh/customization/plugins.md index 2163ce1ae93..e0a1ce64258 100644 --- a/docs/zh/customization/plugins.md +++ b/docs/zh/customization/plugins.md @@ -1,17 +1,17 @@ # Plugins -Plugins 把可复用的 Kimi Code CLI 能力打包成可安装单元——可以添加 [Agent Skills](./skills.md)、自定义 [Agent](./agents.md)、在会话启动时自动加载指定 Skill、提供系统提示词指令，也可以声明 MCP servers 来提供真实工具能力。适合把工作流共享给团队、连接外部服务，或从[官方插件](#官方插件)安装扩展。 +Plugins 把可复用的 Kimi Code CLI 能力打包成可安装单元：可以添加 [Agent Skills](./skills.md)、自定义 [Agent](./agents.md)，可以指定会话启动时自动加载的 Skill、提供系统提示词指令，也可以声明 MCP servers 提供真实工具能力。适合把工作流共享给团队、连接外部服务，或从 [官方插件](#官方插件)安装扩展。 ## 安装与管理 -在 TUI 中运行 `/plugins` 打开 plugin 管理器。它是一个面板，有四个 tab： +在 TUI 中运行 `/plugins` 打开 plugin 管理器，面板内有四个 tab： -- **Installed**：管理已装的 +- **Installed**：管理已安装的 plugin - **Official**：Kimi 官方 marketplace plugin - **Curated**：默认 marketplace 中来自 Kimi 合作伙伴的第三方 plugin - **Custom**：从 URL 安装 -用 `Tab` / `Shift-Tab` 切换。常用按键： +面板内按键： | 按键 | 操作 | | --- | --- | @@ -20,11 +20,11 @@ Plugins 把可复用的 Kimi Code CLI 能力打包成可安装单元——可以 | `D` | 移除选中的已安装 plugin（Installed tab） | | `M` | 管理选中 plugin 的 MCP servers（Installed tab） | | `R` | 重新加载 `installed.json` 和所有 manifest（Installed tab） | -| `Enter` | Installed tab：有更新时安装更新，否则查看 plugin 详情 · Official/Curated tab：安装或更新 · Custom tab：安装 | +| `Enter` | Installed：有更新时安装更新，否则查看 plugin 详情；Official/Curated：安装或更新；Custom：安装 | | `I` | 查看 plugin 详情（Installed tab） | | `Esc` | 返回或取消 | -也可以直接使用斜杠命令： +也可以使用斜杠命令： | 命令 | 说明 | | --- | --- | @@ -53,14 +53,14 @@ Plugins 把可复用的 Kimi Code CLI 能力打包成可安装单元——可以 ### 注意事项 -- Plugin 变更需要通过 `/reload` 或新会话生效。安装、启用/禁用、移除后，运行 `/reload` 或 `/new`；当前会话不会更新。 +- 安装、启用/禁用、移除 plugin 后，当前会话不会更新，运行 `/reload` 或 `/new` 后生效。 - 本地安装会被拷贝到 `$KIMI_CODE_HOME/plugins/managed//`，CLI 始终从这份托管副本运行。安装后编辑原始源目录不会生效，需重新安装。 - 移除 plugin 只会删除安装记录，托管副本和原始源文件仍保留在磁盘上。 - Plugin 目前按用户安装，对所有项目生效，暂不支持项目级安装范围。 ### 自定义 marketplace JSON -浏览自定义目录时，把 JSON 路径或 URL 传给 `/plugins marketplace `；或通过 [`KIMI_CODE_PLUGIN_MARKETPLACE_URL`](../configuration/env-vars.md) 覆盖默认 marketplace。`plugins` 数组中每个条目需要 `id` 和 `source`（本地路径、zip URL 或 GitHub URL）： +浏览自定义目录时，把 JSON 路径或 URL 传给 `/plugins marketplace `，或通过 [`KIMI_CODE_PLUGIN_MARKETPLACE_URL`](../configuration/env-vars.md) 覆盖默认 marketplace。`plugins` 数组中每个条目需要 `id` 和 `source` 两个字段，`source` 支持本地路径、zip URL 和 GitHub URL： ```json { @@ -87,7 +87,7 @@ Plugins 把可复用的 Kimi Code CLI 能力打包成可安装单元——可以 官方插件的安装与升级流程一致： -1. 运行 `/plugins`，tab键选择 **Official** +1. 运行 `/plugins`，按 `Tab` 键选中 **Official** tab 2. 找到要安装的插件，按 `Enter` 安装 3. 安装完成后运行 `/reload` 或 `/new` 激活 @@ -95,19 +95,19 @@ Plugins 把可复用的 Kimi Code CLI 能力打包成可安装单元——可以 Kimi WebBridge 分两步安装：完成上述步骤后，还需要[安装浏览器扩展](#install-the-browser-extension)才能使用。 ::: -官方插件更新后会在使用旧版时提示更新，不会自动更新，要升级到新版本，重复上述安装步骤即可。 +官方插件不会自动更新，使用旧版时会提示更新。升级到新版本只需重复上述安装步骤。 ### Kimi Datasource -Kimi Datasource 是 Kimi Code 官方数据插件，让你用自然语言直接查询金融行情、财经资讯、宏观经济、企业工商、学术文献、中国法律法规和国际组织官方数据，无需手动调用接口或申请数据账号。 +Kimi Datasource 是 Kimi Code 官方数据插件。用自然语言直接查询金融行情、财经资讯、宏观经济、企业工商、学术文献、中国法律法规和国际组织官方数据，无需手动调用接口或申请数据账号。 数据来源包括世界银行、IMF、OECD、FRED、WHO、FAO、国家统计局、Wind、S&P Capital IQ、SEC EDGAR、财新、新华财经、恒生聚源等权威机构与知名数据库，信源可溯源。 -使用前需先通过 `/login` 完成 Kimi Code 账号 OAuth 登录，数据查询会消耗你的 Kimi Code 套餐额度。 +> 使用前需先通过 `/login` 完成 Kimi Code 账号 OAuth 登录。数据查询会消耗 Kimi Code 套餐额度。 #### 使用方式 -1. 直接用自然语言描述你的需求，Kimi Code 会自动调用数据能力 +1. 直接用自然语言描述需求，Kimi Code 会自动调用数据能力 2. 通过 `/skill:kimi-datasource` 明确触发数据查询 Skill #### 能做什么 @@ -147,15 +147,15 @@ Kimi Datasource 是 Kimi Code 官方数据插件，让你用自然语言直接 #### 数据覆盖 | 类别 | 覆盖范围 | -|---|---| -| 股票与金融市场 | Wind、S&P Capital IQ、SEC EDGAR 等知名数据库，能力涵盖 A 股、港股、美股等主要市场的行情、技术指标、财报估值、分析师预期，以及 8,000+ 美股上市公司的官方披露文件 | -| 财经资讯与行业数据 | 财新、新华财经等知名数据平台，能力涵盖市场资讯与快讯、上市公司公告、监管政策、债券基金期货数据、企业失信记录、上市公司产业链关系 | -| 宏观经济 | 世界银行、IMF、OECD、FRED、国家统计局等知名数据库及 WHO、FAO 等国际组织官方统计，能力涵盖全球 189 个国家 50 年以上时间序列与中国全国/省/市指标：GDP、贸易、人口、汇率、CPI、国际收支、GDP 预测等 | -| 中国标准 | 国家标准（GB）、行业标准、地方标准和团体标准的编号、名称、发布状态与详情，部分国标和公开团标提供官方全文入口 | -| 企业数据 | 中国大陆境内企业工商信息、股权穿透、司法风险、关联图谱 | +| --- | --- | +| 股票与金融市场 | Wind、S&P Capital IQ、SEC EDGAR 等；A 股、港股、美股行情、技术指标、财报估值、分析师预期，8,000+ 美股上市公司官方披露文件 | +| 财经资讯与行业数据 | 财新、新华财经等；市场资讯与快讯、上市公司公告、监管政策、债券基金期货数据、企业失信记录、产业链关系 | +| 宏观经济 | 世界银行、IMF、OECD、FRED、国家统计局及 WHO、FAO 等；全球 189 个国家 50 年以上时间序列，中国全国/省/市指标（GDP、贸易、人口、汇率、CPI、国际收支） | +| 中国标准 | 国家标准（GB）、行业标准、地方标准、团体标准的编号、名称、发布状态与详情；部分国标和公开团标提供官方全文入口 | +| 企业数据 | 中国大陆企业工商信息、股权穿透、司法风险、关联图谱 | | 学术文献 | 物理、数学、计算机、金融、经济等领域百万量级论文，支持预印本查询 | -| 法律法规 | 元典智库等知名法律数据库，能力涵盖中国法律法规与司法案例：各效力层次的法规检索与详情，普通及权威判例检索 | -| 智能筛选 | 恒生聚源等知名数据库，能力涵盖自然语言选股、选基金、选基金经理，以及宏观行业数据、研报、公告与新闻 | +| 法律法规 | 元典智库等；中国法律法规与司法案例，含各效力层次法规检索与详情、权威判例检索 | +| 智能筛选 | 恒生聚源等；自然语言选股、选基金、选基金经理，及宏观行业数据、研报、公告与新闻 | #### 计费与限制 @@ -166,23 +166,23 @@ Kimi Datasource 是 Kimi Code 官方数据插件，让你用自然语言直接 ### Kimi WebBridge -Kimi WebBridge 让 AI 直接操控你的浏览器，带着你的登录状态和 Cookie，AI 可以像你一样打开网页、阅读内容、点击按钮、填写表单、截图保存，把重复繁琐的网页操作交给它完成。产品介绍见 [Kimi WebBridge 官网](https://www.kimi.com/zh-cn/features/webbridge)。 +Kimi WebBridge 让 AI 直接操控你的浏览器，带着你的登录状态和 Cookie 打开网页、阅读内容、点击按钮、填写表单、截图保存，把重复的网页操作交给它完成。产品介绍见 [Kimi WebBridge 官网](https://www.kimi.com/zh-cn/features/webbridge)。 #### 安装浏览器扩展 -通过 `/plugins` 安装后，还需要在浏览器中安装 Kimi WebBridge 扩展，AI 才能操控你的浏览器。有两种安装方式： +通过 `/plugins` 安装后，还需要在浏览器中安装 Kimi WebBridge 扩展才能使用。有两种安装方式： **方式一：应用商店安装（推荐）** -打开 [Chrome 应用商店](https://chromewebstore.google.com/detail/kimi-webbridge/fldmhceldgbpfpkbgopacenieobmligc)或 [Edge 应用商店](https://microsoftedge.microsoft.com/addons/detail/kimi-webbridge/bnlffdbcfnanfbknnlaflhlhkocccckg)，点击添加即可。 +打开 [Chrome 应用商店](https://chromewebstore.google.com/detail/kimi-webbridge/fldmhceldgbpfpkbgopacenieobmligc) 或 [Edge 应用商店](https://microsoftedge.microsoft.com/addons/detail/kimi-webbridge/bnlffdbcfnanfbknnlaflhlhkocccckg)，点击添加即可。 **方式二：手动安装** 无法访问应用商店时使用这种方式，按以下步骤操作： -1. [下载扩展安装包](https://kimi-web-img.moonshot.cn/webbridge/latest/extension/kimi-webbridge-extension.zip)并解压 +1. [下载扩展安装包](https://kimi-web-img.moonshot.cn/webbridge/latest/extension/kimi-webbridge-extension.zip) 并解压 2. 在浏览器地址栏输入 `chrome://extensions/` 打开扩展管理页，开启右上角的**开发者模式** ![开启开发者模式](../../media/webbridge-dev-mode.jpeg) @@ -191,13 +191,13 @@ Kimi WebBridge 让 AI 直接操控你的浏览器，带着你的登录状态和 ![加载未打包的扩展程序](../../media/webbridge-load-unpacked.jpeg) -4. 装好后，浏览器工具栏会出现 Kimi WebBridge 图标，看到图标即安装成功，之后就可以让 AI 帮你操作网页了。 +4. 安装完成后，浏览器工具栏会出现 Kimi WebBridge 图标，即表示安装成功 ![工具栏出现 Kimi WebBridge 图标](../../media/webbridge-install-success.jpeg) #### 能做什么 -- **网页操作自动化**：你说话，AI 帮你点网页、填表单、读内容、截图，重复性的网页操作交给它就好 +- **网页操作自动化**：你说话，AI 帮你点网页、填表单、读内容、截图，把重复性的网页操作交给它 - **社媒热点选题**：自动浏览 X（Twitter）、微博、小红书的热门话题，筛选你感兴趣的方向，逐个打开高赞内容截图、提取核心观点，整理成素材库并给出选题建议 - **求职信息搜集**：在招聘网站按条件筛选岗位（关键词、城市、岗位类型），把岗位名称、链接、公司、薪资、投递方式整理成表格 - **竞品分析**：自动在多个 AI 产品间批量发问并采集回答，生成横向对比报告 @@ -205,14 +205,14 @@ Kimi WebBridge 让 AI 直接操控你的浏览器，带着你的登录状态和 ### Kimi Computer Use -Kimi Computer Use 让 AI 直接操作你的桌面应用，可以完成点击、拖拽、滚动、输入等操作。macOS 版全程在后台静默运行，不抢占你的鼠标（少量弹窗操作仍会唤起前台 App）；Windows 版的差异见[下文注意事项](#windows-版注意事项)。 +Kimi Computer Use 让 AI 直接操作你的桌面应用，可以完成点击、拖拽、滚动、输入等操作。macOS 版全程在后台静默运行，不抢占你的鼠标；少量弹窗操作仍会唤起前台 App。Windows 版的差异见 [Windows 版注意事项](#windows-版注意事项)。 #### 授权（macOS） 安装后首次使用时，Kimi Computer Use 会弹出授权窗口，按照提示操作即可： -1. 点击**辅助功能**和**屏幕录制**右侧的**去授权**，在系统设置中开启这两项权限。前者用于执行点击、输入与滚动，后者用于读取屏幕内容、识别需要操作的位置 -2. 在**接入本地 Agent**中打开 **Kimi Code** 开关，重启 Kimi Code 后生效 +1. 点击**辅助功能**和**屏幕录制**右侧的**去授权**，在系统设置中开启这两项权限。前者用于执行点击、输入与滚动，后者用于读取屏幕内容、识别需要操作的位置。 +2. 在**接入本地 Agent**中打开 **Kimi Code** 开关，重启 Kimi Code 后生效。
@@ -222,7 +222,6 @@ Kimi Computer Use 让 AI 直接操作你的桌面应用，可以完成点击、 #### Windows 版注意事项 - - **会短暂占用键鼠**：Windows 版无法像 macOS 版那样稳定地全程后台输入，执行操作时可能短暂激活目标窗口并使用你的鼠标键盘 - **系统要求**：Windows 10 version 1903（Build 18362）或更新版本 / Windows 11，x64；需要真实交互式桌面会话，Windows Server 需要 Desktop Experience - **无需额外授权**：Windows 不需要 macOS 那样的**辅助功能**和**屏幕录制**权限 @@ -231,9 +230,9 @@ Kimi Computer Use 让 AI 直接操作你的桌面应用，可以完成点击、 #### 能做什么 - **在桌面软件整理和录入信息**：让 AI 把散落在各处的信息整理进备忘录、表格或笔记软件，不用手动逐条输入 -- **测试网站和应用流程**：将重复的测试步骤交给AI，截图确认渲染和跳转是否正常 -- **处理重复操作**：反复打开、复制、粘贴、检查类型的工作，让AI在后台静默完成，不抢占鼠标 -- **搞定没有接口的软件**：操作没有 CLI 或 API 的桌面端应用，例如让它把剪映里这段视频的片头剪掉三秒再导出 +- **测试网站和应用流程**：将重复的测试步骤交给 AI，截图确认渲染和跳转是否正常 +- **处理重复操作**：反复打开、复制、粘贴、检查类型的工作，让 AI 在后台静默完成，不抢占鼠标 +- **操作无接口的软件**：操作没有 CLI 或 API 的桌面端应用，例如把剪映里这段视频的片头剪掉三秒再导出 ::: warning 注意 涉及资金、账号和对外发布的操作不建议使用此能力。 @@ -273,24 +272,28 @@ Plugin 是一个带 manifest 的目录或 zip 文件。Manifest 可以放在以 | 字段 | 说明 | | --- | --- | -| `name` | 必填，作为 plugin id。必须匹配 `[a-z0-9][a-z0-9_-]{0,63}` | +| `name` | 必填，作为 plugin id，必须匹配 `[a-z0-9][a-z0-9_-]{0,63}` | | `version`、`description`、`keywords`、`author`、`homepage`、`license` | 展示元数据 | | `interface` | 在 `/plugins` 中展示的字段：`displayName`、`shortDescription`、`longDescription`、`developerName`、`websiteURL` | | `skills` | 一个或多个 `./` 路径，必须位于 plugin 根目录内。省略时根目录的 `SKILL.md` 被当作单个 Skill root | -| `agents` | 一个或多个 `./` 路径，必须位于 plugin 根目录内，指向含有 [Agent 文件](./agents.md#自定义-agent)的目录。省略时根下的 `agents/` 目录（若存在）被自动采用 | +| `agents` | 一个或多个 `./` 路径，必须位于 plugin 根目录内，指向含有 [Agent 文件](./agents.md#自定义-agent) 的目录。省略时若根目录存在 `agents/` 目录则自动采用 | | `sessionStart.skill` | 在新会话或恢复会话开始时，把指定 plugin Skill 加载到 main agent | | `skillInstructions` | 每次加载此 plugin 的 Skill 时一并附带的额外说明 | | `systemPrompt` | plugin 启用期间提供给 Agent 系统提示词的内联指令 | | `systemPromptPath` | 指向 UTF-8 文本文件的 `./` 路径；同时设置 `systemPrompt` 时，文件内容拼接在内联指令之后 | | `mcpServers` | MCP server 声明，默认启用，可从 `/plugins` 中禁用 | -| `hooks` | 在 plugin 启用期间于生命周期事件上运行的 hook 规则；见[插件中的 Hooks](#插件中的-hooks) | -| `commands` | 一个或多个 `./` 路径，指向目录或 `.md` 文件，把其中的 Markdown 文件注册为斜杠命令；见[插件斜杠命令](#插件斜杠命令) | +| `hooks` | 在 plugin 启用期间于生命周期事件上运行的 hook 规则，见 [插件中的 Hooks](#插件中的-hooks) | +| `commands` | 一个或多个 `./` 路径，指向目录或 `.md` 文件，把其中的 Markdown 文件注册为斜杠命令，见 [插件斜杠命令](#插件斜杠命令) | `tools`、`apps`、`inject`、`configFile` 等不支持的运行时字段会显示为 diagnostics 并被忽略。 ### 系统提示词指令 -短指令可以直接写在 `systemPrompt`，较长内容则用 `systemPromptPath` 指向 plugin 根目录内的文件。两个字段同时存在时，内联文本在前，文件内容在后。文件内容在安装或重载 plugin 时读取，因此修改文件后需要 `/plugins reload` 才会生效。例如： +Plugin 通过 `systemPrompt` 和 `systemPromptPath` 两个字段向 Agent 的系统提示词注入指令。本节按三块说明：写法与读取时机、大小限制、两个引擎的差异。 + +### 写法与读取时机 + +短指令可以直接写在 `systemPrompt`，较长内容则用 `systemPromptPath` 指向 plugin 根目录内的文件。两个字段同时存在时，内联文本在前，文件内容在后。文件内容在安装或重载 plugin 时读取，修改文件后需要 `/plugins reload` 才会生效。例如： ```json { @@ -299,17 +302,28 @@ Plugin 是一个带 manifest 的目录或 zip 文件。Manifest 可以放在以 } ``` +内置 Agent 提示词会自动包含已启用 plugin 的指令。自定义 `SYSTEM.md` 或 Agent 文件完全拥有自己的模板，应在希望出现 plugin 指令的位置加入 `${plugin_sections}`。如果自定义模板包含 `${base_prompt}`，且该有效默认提示词已经包含 plugin 块，则不要再重复加入 `${plugin_sections}`。变量完整列表见 [自定义 Agent 与 SYSTEM.md](./agents.md#用-systemmd-覆盖-main-agent-的系统提示词)。 + +### 大小限制 + +`systemPrompt` 字段与 `systemPromptPath` 文件各限制为 32 KB（UTF-8 字节），超限内容会被忽略并显示在 plugin 的 diagnostics 中。一次提示词构建最多注入所有已启用 plugin 合计 64 KB 的指令，超出预算的贡献会被跳过并给出警告；单个 plugin 的内联文本与文件合计超过该预算时同样整体跳过。 + +### 两个引擎的差异 + 系统提示词贡献在两个 Agent 引擎上都生效。交互式 TUI、`kimi -p` 和 `kimi web` 默认使用 v2 引擎；设置 `KIMI_CODE_LEGACY_FLAG=1` 后，本地 CLI 界面会改用旧版引擎。 -`systemPrompt` 字段与 `systemPromptPath` 文件各限制为 32 KB（UTF-8 字节）：超限内容会被忽略，并显示在 plugin 的 diagnostics 中。一次提示词构建最多注入所有已启用 plugin 合计 64 KB 的指令；超出预算的贡献会被跳过并给出警告——单个 plugin 的内联文本与文件合计超过该预算时同样整体跳过。 +新会话和新建 Agent 会读取当前已启用 plugin 的指令，正在进行的请求继续使用已有的系统提示词。`/plugins reload` 会刷新 plugin Skill 列表，并请求重建活跃 Agent 的提示词；需要让变更在下一轮前明确收敛时使用该命令。切换 plugin 的 MCP server 不会改变系统提示词指令。 + +
+两个引擎下的指令刷新行为 -新会话和新建 Agent 会读取当前已启用 plugin 的指令。正在进行的请求会继续使用已有的系统提示词。`/plugins reload` 会刷新 plugin Skill 列表，并请求重建活跃 Agent 的提示词；如果需要让变更在下一轮前明确收敛，请使用这个命令。在 v2 引擎中，安装、启用、禁用或移除 plugin 会立即更新 catalog，后续的提示词重建（例如压缩上下文或修改工具策略后）可能会读取新的指令。legacy 引擎会让每个活跃 session 保留自己的 plugin 快照，直到 `/plugins reload` 或创建新 session。从磁盘恢复的 session 会先使用持久化的提示词，后续重建再遵循对应引擎的行为。切换 plugin 的 MCP server 不会改变系统提示词指令。 +在 v2 引擎中，安装、启用、禁用或移除 plugin 会立即更新 catalog，后续的提示词重建可能会读取新的指令。legacy 引擎中每个活跃 session 保留自己的 plugin 快照，直到 `/plugins reload` 或创建新 session。从磁盘恢复的 session 先使用持久化的提示词，后续重建再遵循对应引擎的行为。 -内置 Agent 提示词会自动包含已启用 plugin 的指令。自定义 `SYSTEM.md` 或 Agent 文件完全拥有自己的模板，因此应在希望出现 plugin 指令的位置加入 `${plugin_sections}`。如果自定义模板包含 `${base_prompt}`，且该有效默认提示词已经包含 plugin 块，就不要再重复加入 `${plugin_sections}`。完整变量表见 [自定义 Agent 与 SYSTEM.md](./agents.md#用-system-md-覆盖-main-agent-的系统提示词)。 +
## 插件斜杠命令 -斜杠命令把一段常用提示词存成 `/命令`，输入它就能触发，省得每次重打。 +斜杠命令把一段常用提示词存成 `/命令`，输入即可触发。 下面是一个最小完整例子，插件目录结构： @@ -330,7 +344,7 @@ manifest（`kimi.plugin.json`）用 `commands` 字段指出命令文件的位置 } ``` -命令文件 `commands/report.md`。顶部两行 `---` 之间是 frontmatter（描述命令的元数据），下面的正文是触发时发给 Agent 的提示词： +命令文件 `commands/report.md` 中，顶部两行 `---` 之间是 frontmatter，其下正文是触发时发给 Agent 的提示词： ```markdown --- @@ -340,7 +354,7 @@ description: 拉取指定股票的财报并总结 拉取 $ARGUMENTS 的最新财报数据，总结营收、利润和关键风险。 ``` -装好并启用后，在对话里输入： +安装并启用后，在对话里输入： ```text /kimi-finance:report TSLA @@ -352,22 +366,22 @@ Kimi 会把正文里的 `$ARGUMENTS` 替换成 `TSLA`，再执行这段提示词 `commands` 填一个 `./` 路径或路径数组，指向 plugin 根目录内的目录或 `.md` 文件： -- 指向**目录**：递归收集其中所有 `.md` 文件，每个各成为一个命令。 +- 指向**目录**：递归收集其中所有 `.md` 文件，每个文件各成为一个命令。 - 指向**单个 `.md` 文件**：只注册这一个。 -- 指向非 `.md` 或不存在的路径：显示为 diagnostics（`/plugins` 面板里的诊断提示）并被忽略。 +- 指向非 `.md` 或不存在的路径：显示为 diagnostics 并被忽略。 ### 编写命令文件 -命令文件分两部分：可选的 **frontmatter**（顶部两行 `---` 之间的元数据，可写 `name`、`description`）和**正文**（`---` 之后的提示词）。两个字段省略时的回退规则： +命令文件分两部分：可选的 **frontmatter**（顶部两行 `---` 之间，可写 `name`、`description`）和**正文**（`---` 之后的提示词）。两个字段省略时的回退规则： -- `name`（命令名）：省略时用文件相对 `commands` 路径的路径命名（去 `.md`、`/` 分隔），如 `commands/frontend/component.md` → `frontend/component`；frontmatter 里显式写的优先。 -- `description`（命令列表里的说明）：省略时取正文首行非空文字（超 240 字符截断）；正文也为空则显示 `No description provided.`。 +- `name`（命令名）：省略时按文件相对 `commands` 的路径命名，去掉 `.md`、以 `/` 分隔，如 `commands/frontend/component.md` 注册为 `frontend/component`；frontmatter 里显式写的优先 +- `description`（命令列表里的说明）：省略时取正文首行非空文字，超 240 字符截断；正文也为空则显示 `No description provided.` ### 调用命令与传参 -命令自动以插件 id 作前缀（即命名空间），注册成 `<插件名>:<命令名>`，所以上面的命令实际叫 `/kimi-finance:report`，不同插件的同名命令因此不会冲突。 +命令自动以插件 id 作前缀注册成 `<插件名>:<命令名>`，所以上面的命令实际叫 `/kimi-finance:report`，不同插件的同名命令因此不会冲突。 -命令后输入的文字会替换正文里的 `$ARGUMENTS`（上例中 `TSLA` 替换掉 `$ARGUMENTS`）。若正文没写 `$ARGUMENTS` 却传了参数，参数不会丢弃，而是以 `ARGUMENTS: <你输入的内容>` 追加到正文末尾。 +命令后输入的文字会替换正文里的 `$ARGUMENTS`。若正文没写 `$ARGUMENTS` 却传了参数，参数不会丢弃，而是以 `ARGUMENTS: <你输入的内容>` 追加到正文末尾。 ## Skills 与会话启动 @@ -389,7 +403,7 @@ my-plugin/ ## 插件 Agent -Plugin 可以携带自定义 Agent：在 manifest 的 `agents` 字段里声明一个或多个 `./` 目录（或直接在 plugin 根下放置 `agents/` 目录），其中的 Agent 文件与[自定义 Agent](./agents.md#自定义-agent) 格式相同，会在 plugin 启用期间作为 subagent 被 main agent 自动发现和委派。 +Plugin 可以携带自定义 Agent：在 manifest 的 `agents` 字段里声明一个或多个 `./` 目录，或直接在 plugin 根下放置 `agents/` 目录。其中的 Agent 文件与 [自定义 Agent](./agents.md#自定义-agent) 格式相同，会在 plugin 启用期间作为 subagent 被 main agent 自动发现和委派。 ```text my-plugin/ @@ -398,7 +412,7 @@ my-plugin/ reviewer.md ``` -Plugin Agent 的优先级低于其他文件来源：同名时用户级、额外目录、项目级和 `--agent-file` 的 Agent 都会覆盖 plugin 提供的版本；替换内置 Agent 同样需要在 frontmatter 里显式写 `override: true`。安装、启用、禁用或移除 plugin 后，Agent 列表在新会话（或 `/reload`）时刷新；v2 引擎的当前会话还会在 `/plugins reload` 后刷新。 +Plugin Agent 的优先级低于其他文件来源：同名时用户级、额外目录、项目级和 `--agent-file` 的 Agent 都会覆盖 plugin 提供的版本；替换内置 Agent 同样需要在 frontmatter 里显式写 `override: true`。安装、启用、禁用或移除 plugin 后，Agent 列表在新会话或 `/reload` 时刷新；v2 引擎的当前会话还会在 `/plugins reload` 后刷新。 ## Plugin 中的 MCP servers @@ -443,7 +457,7 @@ Plugin MCP servers 会在 `/reload` 后或新会话中启动。启用或禁用 ## 插件中的 Hooks -plugin 可以在其 manifest 中声明 hook 规则，在 plugin 启用期间于生命周期事件上运行。每一项使用与 [`config.toml` 中的 `[[hooks]]` 规则](./hooks.md#配置)相同的字段（`event`、`matcher`、`command`、`timeout`）： +plugin 可以在其 manifest 中声明 hook 规则，在 plugin 启用期间于生命周期事件上运行。每一项的字段与 [`config.toml` 中的 `[[hooks]]` 规则](./hooks.md#配置) 相同（`event`、`matcher`、`command`、`timeout`）： ```json { @@ -458,19 +472,26 @@ plugin 可以在其 manifest 中声明 hook 规则，在 plugin 启用期间于 } ``` -plugin hooks 复用与全局 hooks 相同的机制——事件列表、stdin JSON 载荷以及退出码和返回值如何影响主流程，详见 [Hooks](./hooks.md)。区别如下： +plugin hooks 复用与全局 hooks 相同的机制。事件列表、stdin JSON 载荷、退出码与返回值对主流程的影响，详见 [Hooks](./hooks.md)。两者区别： - plugin 的 hooks 仅在 plugin **启用**期间生效；禁用 plugin 后其 hooks 停止运行。 -- 每条 hook 的工作目录为 plugin 根目录，因此 `command` 可以使用 plugin 内的 `./` 路径。 +- 每条 hook 的工作目录为 plugin 根目录，`command` 可以使用 plugin 内的 `./` 路径。 - hook 进程会额外收到两个环境变量：`KIMI_CODE_HOME` 和 `KIMI_PLUGIN_ROOT`（plugin 根目录）。 -仅安装 plugin 本身不会运行其 hooks——它们只在 plugin 启用期间、匹配的事件触发时运行。 +仅安装 plugin 本身不会运行其 hooks；它们只在 plugin 启用期间、匹配的事件触发时运行。 ## 安全模型 -Plugin 的加载范围有限，以下操作不会在安装或会话启动时发生： +Plugin 的加载范围有限，安装和运行时的安全边界如下： - 不会执行命令型 plugin tools 或旧式工具运行时 - 所有路径在解析符号链接后仍必须位于 plugin 根目录内 -- 已启用 plugin 的 MCP servers 会在 `/reload` 后或新会话中启动，且可随时从 `/plugins` 禁用 -- 损坏的 manifest 或不安全路径会显示在 `/plugins info ` 的 diagnostics 中，不影响其他会话 +- 已启用 plugin 的 MCP servers 在 `/reload` 后或新会话中启动，可随时从 `/plugins` 禁用 +- 损坏的 manifest 或不安全路径显示在 `/plugins info ` 的 diagnostics 中，不影响其他会话 + +## 下一步 + +- [Agent Skills](./skills.md) — 了解 SKILL.md 格式，编写 plugin 携带的 Skill +- [自定义 Agent](./agents.md) — 了解 Agent 文件格式与目录作用域优先级 +- [MCP](./mcp.md) — 了解 plugin 中 MCP server 声明复用的 schema +- [Hooks](./hooks.md) — 了解 plugin hooks 复用的全局 hook 机制 diff --git a/docs/zh/customization/skills.md b/docs/zh/customization/skills.md index a6472210a1e..a392deae79d 100644 --- a/docs/zh/customization/skills.md +++ b/docs/zh/customization/skills.md @@ -1,8 +1,8 @@ # Agent Skills -Agent Skills 是 Kimi Code CLI 扩展模型能力的轻量机制。一个 Skill 就是一份带 YAML frontmatter 的 Markdown 文档，描述某项专业知识或工作流程——例如项目的代码风格规范、PR review 流程、提交消息格式。 +Agent Skills 是 Kimi Code CLI 扩展模型能力的轻量机制。一个 Skill 就是一份带 YAML frontmatter 的 Markdown 文档，描述某项专业知识或工作流程：项目的代码风格规范、PR review 流程、提交消息格式。 -相比每次把同样的指引粘到提示词里，Skill 的优势在于：内容沉淀在文件里、可以跨项目和团队复用、可以通过斜杠命令一键加载，也可以让模型在需要时自动调用。 +与每次把同样的指引粘到提示词里相比，Skill 把内容沉淀在文件里，可以跨项目和团队复用，既可以通过斜杠命令一键加载，也可以让模型在需要时自动调用。 ## 创建 Skill @@ -39,12 +39,12 @@ arguments: | 字段 | 说明 | | --- | --- | -| `name` | Skill 名称。目录型 `SKILL.md` 中为必填；扁平 `.md` 文件省略时使用文件名。名称大小写不敏感 | -| `description` | 一行总结，模型用它来判断何时使用这个 Skill。目录型 `SKILL.md` 中为必填；扁平 `.md` 文件省略时回退到正文第一行非空内容（截至 240 字符） | -| `type` | Skill 类型：`prompt`（默认）、`inline`（与 `prompt` 语义相同）、`flow`（只支持手动调用，不支持模型自动调用）。其他值会被跳过 | -| `whenToUse` | 触发场景描述。也接受 `when-to-use`、`when_to_use` 写法 | -| `disableModelInvocation` | 设为 `true` 时禁止模型自动调用此 Skill。也接受 `disable-model-invocation`、`disable_model_invocation` 写法 | -| `arguments` | 命名参数列表，可写成字符串数组或空白分隔的字符串（如 `arguments: target mode`）。声明后，正文可用 `$` 读取参数 | +| `name` | Skill 名称，大小写不敏感。目录型 `SKILL.md` 必填，扁平 `.md` 省略时取文件名 | +| `description` | 一行总结，模型用它判断何时使用。目录型必填，扁平 `.md` 省略时取正文第一行非空内容（截至 240 字符） | +| `type` | 类型：`prompt`（默认）、`inline`（同 `prompt`）、`flow`（仅手动调用）。其他值被跳过 | +| `whenToUse` | 触发场景描述，也接受 `when-to-use`、`when_to_use` 写法 | +| `disableModelInvocation` | 设为 true 禁止模型自动调用，也接受 `disable-model-invocation`、`disable_model_invocation` 写法 | +| `arguments` | 命名参数列表，字符串数组或空白分隔字符串（如 `arguments: target mode`）。声明后正文可用 `$` 读取 | ::: warning 注意 目录型 `SKILL.md` 中 `name` 和 `description` **必须**显式填写，省略任意一项均会导致解析失败。 @@ -59,17 +59,17 @@ arguments: - `$`：`arguments` 中声明的命名参数 - `${KIMI_SKILL_DIR}`：当前 Skill 文件所在目录 -位置参数支持单双引号包裹，如 `/skill:commit "fix login" patch` 中 `$0` 展开为 `fix login`。若正文不含任何参数占位符，调用时附带的文本会以 `\n\nARGUMENTS: <文本>` 的形式追加到正文末尾。 +位置参数支持单双引号包裹：在 `/skill:commit "fix login" patch` 中，`$0` 展开为 `fix login`。若正文不含任何参数占位符，调用时附带的文本会以 `\n\nARGUMENTS: <文本>` 的形式追加到正文末尾。 ## Skill 存放位置 -Kimi Code CLI 按作用域分四档扫描，越具体的作用域优先级越高：**Project > User > Extra > Built-in** +Kimi Code CLI 按作用域分四档扫描，越具体的作用域优先级越高：**Project > User > Extra > Built-in**。 **用户级**（对所有项目生效）： - `$KIMI_CODE_HOME/skills/`（默认：`~/.kimi-code/skills/`） - `~/.agents/skills/` -Kimi 专属用户级 Skill 目录会随 `KIMI_CODE_HOME` 移动，因此隔离数据根时也会隔离 Kimi 专属 Skills。通用 `~/.agents/skills/` 目录仍放在真实 OS home 下，以便跨工具共享。 +Kimi 专属用户级 Skill 目录会随 `KIMI_CODE_HOME` 移动，隔离数据根时也会隔离 Kimi 专属 Skills。通用 `~/.agents/skills/` 目录仍放在真实 OS home 下，以便跨工具共享。 **项目级**（项目根 = 工作目录向上最近的含 `.git` 的目录）： - `.kimi-code/skills/` @@ -81,7 +81,7 @@ Kimi 专属用户级 Skill 目录会随 `KIMI_CODE_HOME` 移动，因此隔离 extra_skill_dirs = ["~/team-skills", ".agents/team-skills"] ``` -**内置 Skills** 随 CLI 一起分发，优先级最低。它们为常见任务提供开箱即用的工作流，例如配置 MCP server、定制 TUI 主题和编辑配置文件。完整列表详见[内置 Skill 命令](../reference/slash-commands.md#内置-skill-命令)。其中介绍 Kimi Code 自身的部分可以通过顶层 [`builtin_product_skills`](../configuration/config-files.md#顶层字段) 字段关闭。 +**内置 Skills** 随 CLI 一起分发，优先级最低，为常见任务提供开箱即用的工作流，例如配置 MCP server、定制 TUI 主题和编辑配置文件。完整列表详见[内置 Skill 命令](../reference/slash-commands.md#内置-skill-命令)。其中介绍 Kimi Code 自身的部分可以通过顶层 [`builtin_product_skills`](../configuration/config-files.md#顶层字段) 字段关闭。 ## 调用 Skill @@ -92,7 +92,7 @@ extra_skill_dirs = ["~/team-skills", ".agents/team-skills"] /skill:git-commits 修复登录接口的并发问题 ``` -模型也可以根据 `description` 和 `whenToUse` 自动调用 Skill（除非 `disableModelInvocation` 设为 `true` 或 `type` 为 `flow`）。Skill 调用时最多允许嵌套 3 层，超过后会被终止。 +模型也可以根据 `description` 和 `whenToUse` 自动调用 Skill。`disableModelInvocation` 设为 true 或 `type` 设为 flow 时不自动调用。Skill 调用最多允许嵌套 3 层，超过后会被终止。 ## 完整示例 @@ -122,7 +122,7 @@ arguments: - 值得肯定的地方 ``` -保存为 `$KIMI_CODE_HOME/skills/review-pr/SKILL.md`（未设置 `KIMI_CODE_HOME` 时为 `~/.kimi-code/skills/review-pr/SKILL.md`），检查清单放在同目录的 `references/checklist.md`，重开会话后即可通过 `/skill:review-pr #1234` 调用，其中 `#1234` 会展开到 `$pr_ref`。 +将文件保存为 `$KIMI_CODE_HOME/skills/review-pr/SKILL.md`，未设置 `KIMI_CODE_HOME` 时为 `~/.kimi-code/skills/review-pr/SKILL.md`。检查清单放在同目录的 `references/checklist.md`。重开会话后即可调用，例如 `/skill:review-pr #1234`，其中的参数会展开到 `$pr_ref`。 ## 下一步 diff --git a/docs/zh/customization/themes.md b/docs/zh/customization/themes.md index 2fd5e843075..ce4eb83ed65 100644 --- a/docs/zh/customization/themes.md +++ b/docs/zh/customization/themes.md @@ -8,16 +8,16 @@ Kimi Code CLI 可以使用内置配色，也可以使用自定义 JSON 主题文 | Token | `dark` | `light` | 控制什么 | | --- | --- | --- | --- | -| `primary` | `#4FA8FF` | `#1565C0` | 最常用色。链接、行内代码、几乎所有对话框的选中项、编辑器聚焦边框、Plan/运行中徽章、spinner | -| `accent` | `#5BC0BE` | `#00838F` | 次级强调。审批 `▶` 前缀、设备码框、图片占位、BTW/队列面板、注册表导入 | -| `text` | `#E0E0E0` | `#1A1A1A` | 正文。对话框正文、todo 标题、footer 模型名、Markdown 标题、助手/工具消息子弹头、列表符号 | +| `primary` | `#4FA8FF` | `#1565C0` | 最常用色。链接、行内代码、对话框选中项、聚焦边框、徽章、spinner | +| `accent` | `#5BC0BE` | `#00838F` | 次级强调。审批 `▶` 前缀、设备码框、图片占位、面板、注册表导入 | +| `text` | `#E0E0E0` | `#1A1A1A` | 正文。对话框正文、todo 标题、footer 模型名、Markdown 标题、列表符号 | | `textStrong` | `#F5F5F5` | `#1A1A1A` | 加粗强调文字。输入类对话框、状态消息 | -| `textDim` | `#888888` | `#454545` | 次级、变暗文字。思考、提示、描述、已完成 todo、Markdown 引用、footer 状态栏 | -| `textMuted` | `#6B6B6B` | `#5F5F5F` | 最浅文字。计数、滚动信息、描述、Markdown 链接 URL、代码块边框 | +| `textDim` | `#888888` | `#454545` | 次级、变暗文字。思考、提示、已完成 todo、Markdown 引用、footer 状态栏 | +| `textMuted` | `#6B6B6B` | `#5F5F5F` | 最浅文字。计数、滚动信息、Markdown 链接 URL、代码块边框 | | `border` | `#5A5A5A` | `#737373` | 面板与编辑器的普通边框、Markdown 分隔线 | | `borderFocus` | `#E8A838` | `#92660A` | 聚焦/注意边框，目前仅审批面板使用 | | `success` | `#4EC87E` | `#0E7A38` | 成功态。`✓`、已启用、完成 | -| `warning` | `#E8A838` | `#92660A` | 警告态。"Ask When Needed" / "Never Ask" 徽章、过期标记、Plan 模式提示 | +| `warning` | `#E8A838` | `#92660A` | 警告态。auto/yolo 徽章、过期标记、Plan 模式提示 | | `error` | `#E85454` | `#B91C1C` | 错误态。错误信息、失败的工具输出 | | `diffAdded` | `#4EC87E` | `#0E7A38` | diff 新增行 | | `diffRemoved` | `#E85454` | `#B91C1C` | diff 删除行 | @@ -26,11 +26,11 @@ Kimi Code CLI 可以使用内置配色，也可以使用自定义 JSON 主题文 | `diffGutter` | `#6B6B6B` | `#737373` | diff 行号槽 | | `diffMeta` | `#888888` | `#5F5F5F` | diff 元信息 / hunk 头 | | `roleUser` | `#FFCB6B` | `#9A4A00` | 用户消息的子弹头与文字、技能激活名 | -| `shellMode` | `#BD93F9` | `#7C3AED` | Shell 模式（`!`）的提示符、编辑器边框，以及回显的 `$ 命令` 行 | +| `shellMode` | `#BD93F9` | `#7C3AED` | Shell 模式（`!`）的提示符、编辑器边框、回显的命令行 | ## 使用 custom-theme skill -你不需要手写 JSON。运行内置 `/custom-theme [附加文本]` skill 命令进入自定义主题流程；这个 skill 可以帮你选颜色，把文件写到 `~/.kimi-code/themes/`，校验十六进制色值，并告诉你如何应用。 +你不需要手写 JSON。运行内置的 `/custom-theme [附加文本]` skill 进入自定义主题流程：它会帮你选颜色，把文件写到 `~/.kimi-code/themes/`，校验十六进制色值，并告诉你如何应用。 调用示例： @@ -38,7 +38,7 @@ Kimi Code CLI 可以使用内置配色，也可以使用自定义 JSON 主题文 - `/custom-theme Make a light theme based on Solarized, but keep errors easy to see.` - `/custom-theme Tweak my ember theme so diffs have higher contrast.` -激活后，skill 通常会先问你想用浅色还是深色基准、偏好的风格或调色板，以及是否有必须包含的精确颜色。如果你用它编辑已有主题，请确保它先读取并备份文件，再覆盖写入。 +激活后，skill 通常会先问你想用浅色还是深色基准、偏好的风格或调色板，以及是否有必须包含的精确颜色。如果用它编辑已有主题，确保它先读取并备份文件，再覆盖写入。 ## 创建一个主题 @@ -47,9 +47,9 @@ Kimi Code CLI 可以使用内置配色，也可以使用自定义 JSON 主题文 - `~/.kimi-code/themes/` - 如果设置了 `KIMI_CODE_HOME` 环境变量，则是 `$KIMI_CODE_HOME/themes/` -目录不存在就自己建一个。**文件名就是主题名**：`ember.json` 会在 `/theme` 里显示为 `Custom: ember`。 +目录不存在就自己建一个。文件名就是主题名：`ember.json` 会在 `/theme` 里显示为 `Custom: ember`。 -一个最小的主题只需要写你想改的颜色，其余自动沿用**基准调色板**（默认是 `dark`）： +一个最小的主题只需要写你想改的颜色，其余自动沿用基准调色板（默认是 `dark`）： ```json { @@ -65,7 +65,7 @@ Kimi Code CLI 可以使用内置配色，也可以使用自定义 JSON 主题文 - `name`（必填）：主题的标识名。 - `displayName`（可选）：人类可读的名字。 -- `base`（可选）：未指定的 token 沿用哪个内置调色板——`"dark"`（默认）或 `"light"`。做**浅色**主题时设为 `"base": "light"`，这样你没写的 token 在浅色背景上仍然可读（否则会回退到 dark 调色板）。 +- `base`（可选）：未指定的 token 沿用哪个内置调色板，`"dark"`（默认）或 `"light"`。做浅色主题时设为 `"light"`，否则未写的 token 会沿用 dark 调色板，在浅色背景上可能不可读。 - `colors`（可选）：要覆盖的颜色 token，值是 6 位十六进制色值（如 `#FE8019`）。 使用 [内置颜色 token](#内置颜色-token) 里的 token 名。没有写到的 token 会自动回退到所选基准调色板的对应值，所以你完全可以只覆盖一部分： @@ -84,8 +84,8 @@ Kimi Code CLI 可以使用内置配色，也可以使用自定义 JSON 主题文 两种方式： -1. **`/theme` 命令**（推荐）：打开主题选择器，自定义主题会以 `Custom: <文件名>` 出现。选择器**每次打开都会重新扫描主题目录**，所以你新加的主题文件**无需重启**就能看到。 -2. **`tui.toml`**：把 `theme` 设成你的主题名： +1. **`/theme` 命令**（推荐）：打开主题选择器，自定义主题会以 `Custom: <文件名>` 出现。选择器每次打开都会重新扫描主题目录，新加的主题文件无需重启就能看到。 +2. **[`tui.toml`](../configuration/config-files.md#tuitoml)**：把 `theme` 设成你的主题名： ```toml # ~/.kimi-code/tui.toml @@ -102,11 +102,15 @@ Kimi Code CLI 可以使用内置配色，也可以使用自定义 JSON 主题文 ## 编辑正在使用的主题 -如果你修改的是**当前正在生效**的那个主题文件，改动不会自动重新加载。让新颜色生效有两种办法： +如果你修改的是当前正在生效的主题文件，改动不会自动重新加载。让新颜色生效有两种办法： -- 运行 `/reload-tui`——它会重新读取 `tui.toml` 并重新应用当前主题（包括重新读取主题文件）； +- 运行 `/reload-tui`，它会重新读取 `tui.toml` 并重新应用当前主题（包括重新读取主题文件）； - 或者在 `/theme` 里先切到另一个主题，再切回来。 ::: warning 注意 -在 `/theme` 里**重新选中同一个主题**不会触发重载（只会提示 “Theme unchanged”）。要重载已激活主题的改动，用上面两种办法之一。 +在 `/theme` 里重新选中同一个主题不会触发重载，只会提示 "Theme unchanged"。要重载已激活主题的改动，用上面两种办法之一。 ::: + +## 下一步 + +- [配置文件](../configuration/config-files.md#tuitoml) — `tui.toml` 的完整字段说明，包括 `theme` 配置项