From 13bef008ad2f3530827920d3fc3fc8c301982f2c Mon Sep 17 00:00:00 2001 From: Louis Gu Date: Wed, 12 Aug 2026 22:43:01 +0800 Subject: [PATCH 1/2] docs: document custom registry format --- docs/en/configuration/providers.md | 98 +++++++++++++++++++++++++++++- docs/zh/configuration/providers.md | 98 +++++++++++++++++++++++++++++- 2 files changed, 194 insertions(+), 2 deletions(-) diff --git a/docs/en/configuration/providers.md b/docs/en/configuration/providers.md index 43aeabb442..29fa2729af 100644 --- a/docs/en/configuration/providers.md +++ b/docs/en/configuration/providers.md @@ -32,7 +32,7 @@ The manager displays providers as a list of entries grouped by source. Navigatio Two paths when adding: - **Known third-party provider**: fetches the model catalog from [models.dev](https://models.dev/), select a provider → enter an API key → select a default model. Vendors whose protocol the catalog does not declare (e.g. xai, openrouter, and other vendor-specific SDKs) are imported as OpenAI-compatible with a "guessed" note; when the catalog provides no usable endpoint, a base URL prompt appears first; proprietary protocols (Amazon Bedrock, Cohere) and unrecognized explicit protocols are refused. Deprecated and alpha-status models are excluded from the import list. If the public catalog is unreachable, the CLI falls back to a built-in snapshot of the catalog, so the import still works offline or in blocked networks -- **Custom registry (api.json)**: paste a custom registry URL and Bearer token; the CLI automatically creates the `providers` / `models` entries. On later startup, providers from the same registry URL are refreshed together, so upstream provider additions, removals, and model metadata changes are synced. +- **[Custom registry (`api.json`)](#custom-registry-format)**: paste a custom registry URL and Bearer token; the CLI automatically creates the `providers` / `models` entries. On later startup, providers from the same registry URL are refreshed together, so upstream provider additions, removals, and model metadata changes are synced. ::: warning Kimi Code OAuth managed accounts logged in via `/login` do not appear in `/provider`. Use `/login` and `/logout` to manage them. @@ -40,6 +40,102 @@ Kimi Code OAuth managed accounts logged in via `/login` do not appear in `/provi The same operations are also available in non-interactive environments via the shell command: [`kimi provider`](../reference/kimi-command.md#kimi-provider). +## Custom registry format + +A custom registry is a hosted JSON catalog that describes one or more providers and their models. Serve the file from an HTTPS URL, then import it through `/provider` or `kimi provider add`. + +### Minimal example + +The smallest useful registry defines one provider and one model: + +```json +{ + "example": { + "id": "example", + "name": "Example provider", + "api": "https://api.example.com/v1", + "type": "openai", + "models": { + "example-model": { + "id": "example-model" + } + } + } +} +``` + +After publishing that file, import it with a neutral placeholder API key: + +```sh +kimi provider add https://registry.example.com/api.json --api-key YOUR_API_KEY +``` + +The key is sent to the registry as `Authorization: Bearer YOUR_API_KEY` and is also saved as the API key for every provider imported from the file. The top-level `example` key identifies the registry record, while the nested `id` becomes the provider ID. Likewise, the model object key creates the Kimi Code alias `example/example-model`, and the nested model `id` is sent to the upstream API. + +### Provider fields + +Each top-level value is a provider object. Missing or invalid required fields, or an unsupported `type`, cause that provider entry to be skipped; invalid optional fields are ignored. + +| Field | Type | Required | Description | +| --- | --- | --- | --- | +| `id` | `string` | Yes | Non-empty, stable provider ID used in generated configuration and model aliases | +| `name` | `string` | Yes | Non-empty display name | +| `api` | `string` | Yes | Non-empty base URL used for model requests | +| `type` | `string` | Yes | API protocol; must be one of the four values below | +| `models` | `object` | Yes | Object keyed by the alias suffix for each model | +| `env` | `string[]` | No | Compatibility metadata listing credential environment-variable names; the importer accepts it but uses the supplied Bearer token for credentials | + +Custom registries support these four provider types. The `google-genai` and `vertexai` types available in `config.toml` are not accepted in `api.json`. + +| `type` | Protocol | +| --- | --- | +| `kimi` | Kimi's OpenAI-compatible protocol | +| `anthropic` | Anthropic Messages | +| `openai` | OpenAI Chat Completions | +| `openai_responses` | OpenAI Responses API | + +### Model fields + +Each value under `models` is a model object. A model entry without a non-empty string `id` is skipped without rejecting the rest of its provider. + +| Field | Type | Required | Description | +| --- | --- | --- | --- | +| `id` | `string` | Yes | Model ID sent to the provider API | +| `name` | `string` | No | Display name; defaults to `id` | +| `limit` | `object` | No | Positive numeric `context` and `output` limits. `context` becomes `max_context_size`; when it is absent, `output` is used as the fallback. If neither is valid, the default is `131072`. `output` does not currently create `max_output_size` | +| `tool_call` | `boolean` | No | Whether the model supports tool calls | +| `reasoning` | `boolean` | No | Whether the model supports Thinking | +| `modalities` | `object` | No | String arrays under `input` and `output` that describe supported media | +| `support_efforts` | `string[]` | No | Available Thinking effort names, such as `low`, `medium`, and `high` | +| `default_effort` | `string` | No | Non-empty default Thinking effort; normally one of `support_efforts` | + +### Capability mapping + +Capability metadata is translated into the generated model alias as follows: + +| Registry value | Generated model metadata | +| --- | --- | +| `limit.context: 200000` | `max_context_size = 200000` | +| `tool_call: true` | `tool_use` capability | +| `reasoning: true` | `thinking` capability | +| `modalities.input` contains `image` / `video` | `image_in` / `video_in` capability | +| `modalities.output` contains `image` / `audio` | `image_out` / `audio_out` capability | +| Non-empty `support_efforts` | `thinking` capability plus the listed effort levels | +| `default_effort: "medium"` | Default effort `medium` | + +When any of `tool_call`, `reasoning`, `modalities`, or `support_efforts` is present, the importer derives the complete capability list from those fields. Include `tool_call: true` alongside the other hints when the model supports tools. If all four fields are omitted, the importer falls back to `tool_use`; `default_effort` by itself does not enable Thinking. + +### Refresh behavior + +Every imported provider stores the registry source. On a normal startup refresh, Kimi Code groups providers by the exact source URL; the URL remains the registry identity even if its API key changes. After a successful fetch, Kimi Code: + +- adds provider and model entries newly published at that URL +- removes providers no longer present and every alias that references them; removes generated aliases for deleted models; clears default provider or model selections when their target disappears +- updates provider protocol, base URL, credential, model ID, display name, context size, capabilities, and effort metadata +- preserves unrelated providers, hand-created aliases outside the generated `/...` namespace for providers that remain, and extra model fields that the registry does not own + +If the registry fetch fails, the existing provider configuration is left unchanged and the refresh reports the failure. + ## `kimi` For connecting to Moonshot AI's OpenAI-compatible interface, including the Kimi Code managed service and Kimi Platform API keys. diff --git a/docs/zh/configuration/providers.md b/docs/zh/configuration/providers.md index f97df28030..26af5495f0 100644 --- a/docs/zh/configuration/providers.md +++ b/docs/zh/configuration/providers.md @@ -32,7 +32,7 @@ Kimi Code CLI 支持同时接入多家 LLM 平台——用 Kimi Code 托管服 添加时有两条路径： - **Known third-party provider**：从 [models.dev](https://models.dev/) 拉取模型目录，选供应商 → 输入 API 密钥 → 选默认模型。目录未声明协议类型的供应商（如 xai、openrouter 这类厂商专用 SDK）会按 OpenAI 兼容协议导入并显示 "guessed" 提示；目录没有可用端点时会先弹出 base URL 输入框；Amazon Bedrock / Cohere 等专有协议和无法识别的显式协议会被拒绝导入。已下线（deprecated）和 alpha 状态的模型不会出现在导入列表中。如果公共目录不可达，CLI 会回退到内置目录快照，离线或网络受限环境下也能完成导入 -- **Custom registry (api.json)**：粘贴自定义 registry 地址和 Bearer token，CLI 自动创建 `providers` / `models` 条目。后续启动时，同一个 registry 地址下的供应商会一起刷新，因此上游新增、删除供应商以及模型元数据变化都会同步。 +- **[Custom registry（`api.json`）](#自定义-registry-格式)**：粘贴自定义 registry 地址和 Bearer token，CLI 自动创建 `providers` / `models` 条目。后续启动时，同一个 registry 地址下的供应商会一起刷新，因此上游新增、删除供应商以及模型元数据变化都会同步。 ::: warning 通过 `/login` 登录的 Kimi Code OAuth 托管账号不会在 `/provider` 里显示，请用 `/login` 和 `/logout` 管理。 @@ -40,6 +40,102 @@ Kimi Code CLI 支持同时接入多家 LLM 平台——用 Kimi Code 托管服 非交互环境下也可以用 shell 命令完成同样操作：[`kimi provider`](../reference/kimi-command.md#kimi-provider)。 +## 自定义 registry 格式 + +自定义 registry 是托管在网络上的 JSON 目录，用于描述一个或多个供应商及其模型。将文件放在 HTTPS 地址，然后通过 `/provider` 或 `kimi provider add` 导入。 + +### 最小示例 + +最小可用 registry 只需定义一个供应商和一个模型： + +```json +{ + "example": { + "id": "example", + "name": "Example provider", + "api": "https://api.example.com/v1", + "type": "openai", + "models": { + "example-model": { + "id": "example-model" + } + } + } +} +``` + +发布文件后，用中性的占位 API 密钥导入： + +```sh +kimi provider add https://registry.example.com/api.json --api-key YOUR_API_KEY +``` + +该密钥会以 `Authorization: Bearer YOUR_API_KEY` 发给 registry，并保存为该文件所导入每个供应商的 API 密钥。顶层的 `example` 键用于标识 registry 记录，内部的 `id` 则成为供应商 ID。同样，模型对象的键会生成 Kimi Code 别名 `example/example-model`，内部的模型 `id` 会发送给上游 API。 + +### 供应商字段 + +每个顶层值都是一个供应商对象。必填字段缺失或无效，或 `type` 不受支持时，该供应商条目会被跳过；无效的可选字段会被忽略。 + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `id` | `string` | 是 | 非空且稳定的供应商 ID，用于生成配置和模型别名 | +| `name` | `string` | 是 | 非空显示名称 | +| `api` | `string` | 是 | 发送模型请求时使用的非空 base URL | +| `type` | `string` | 是 | API 协议，必须是下列四种值之一 | +| `models` | `object` | 是 | 以每个模型的别名后缀为键的对象 | +| `env` | `string[]` | 否 | 列出凭证环境变量名的兼容元数据；导入器接受该字段，但凭证使用导入时提供的 Bearer token | + +自定义 registry 支持以下四种供应商类型。`config.toml` 支持的 `google-genai` 和 `vertexai` 类型不能用于 `api.json`。 + +| `type` | 协议 | +| --- | --- | +| `kimi` | Kimi 的 OpenAI 兼容协议 | +| `anthropic` | Anthropic Messages | +| `openai` | OpenAI Chat Completions | +| `openai_responses` | OpenAI Responses API | + +### 模型字段 + +`models` 下的每个值都是一个模型对象。模型条目若没有非空字符串 `id`，会被跳过，但不会导致其余供应商内容导入失败。 + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `id` | `string` | 是 | 发送给供应商 API 的模型 ID | +| `name` | `string` | 否 | 显示名称，默认使用 `id` | +| `limit` | `object` | 否 | 包含正数 `context` 和 `output` 上限。`context` 会生成 `max_context_size`；缺少时用 `output` 回退。两者都无效时默认值为 `131072`。当前不会由 `output` 生成 `max_output_size` | +| `tool_call` | `boolean` | 否 | 模型是否支持工具调用 | +| `reasoning` | `boolean` | 否 | 模型是否支持 Thinking | +| `modalities` | `object` | 否 | `input` 和 `output` 下的字符串数组，用于描述支持的媒体类型 | +| `support_efforts` | `string[]` | 否 | 可用的 Thinking effort 名称，如 `low`、`medium`、`high` | +| `default_effort` | `string` | 否 | 非空的默认 Thinking effort，通常是 `support_efforts` 中的一项 | + +### 能力映射 + +能力元数据会按下表转换到生成的模型别名： + +| registry 值 | 生成的模型元数据 | +| --- | --- | +| `limit.context: 200000` | `max_context_size = 200000` | +| `tool_call: true` | `tool_use` 能力 | +| `reasoning: true` | `thinking` 能力 | +| `modalities.input` 包含 `image` / `video` | `image_in` / `video_in` 能力 | +| `modalities.output` 包含 `image` / `audio` | `image_out` / `audio_out` 能力 | +| 非空 `support_efforts` | `thinking` 能力及列出的 effort 等级 | +| `default_effort: "medium"` | 默认 effort `medium` | + +只要出现 `tool_call`、`reasoning`、`modalities`、`support_efforts` 中任一能力提示字段，导入器就会完全根据这些字段生成能力列表。如果模型同时支持工具调用，请显式写入 `tool_call: true`。四个字段全部省略时，导入器会回退到 `tool_use`；单独设置 `default_effort` 不会启用 Thinking。 + +### 刷新行为 + +每个导入的供应商都会保存 registry 来源。正常启动刷新时，Kimi Code 会按完全一致的来源 URL 对供应商分组；即使 API 密钥变化，该 URL 仍是 registry 的身份标识。成功拉取后，Kimi Code 会： + +- 添加该 URL 新发布的供应商和模型条目 +- 删除已不存在的供应商及所有引用它的别名；删除已下线模型对应的生成别名；默认供应商或模型的目标消失时清除默认选择 +- 更新供应商协议、base URL、凭证、模型 ID、显示名称、上下文大小、能力和 effort 元数据 +- 保留无关供应商、仍存在供应商在自动生成的 `/...` 命名空间之外的手动别名，以及 registry 不负责管理的额外模型字段 + +如果拉取 registry 失败，现有供应商配置会保持不变，刷新结果会报告该失败。 + ## `kimi` 用于对接 Moonshot AI 的 OpenAI 兼容接口，包括 Kimi Code 托管服务和 Kimi Platform API 密钥。 From 13716a2c30be126efe30ee6c22677c2c9c0a34e9 Mon Sep 17 00:00:00 2001 From: Louis Gu Date: Fri, 14 Aug 2026 01:04:45 +0800 Subject: [PATCH 2/2] docs(provider): define model alias at first use --- docs/en/configuration/providers.md | 2 +- docs/zh/configuration/providers.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/en/configuration/providers.md b/docs/en/configuration/providers.md index 29fa2729af..15e651237b 100644 --- a/docs/en/configuration/providers.md +++ b/docs/en/configuration/providers.md @@ -70,7 +70,7 @@ After publishing that file, import it with a neutral placeholder API key: kimi provider add https://registry.example.com/api.json --api-key YOUR_API_KEY ``` -The key is sent to the registry as `Authorization: Bearer YOUR_API_KEY` and is also saved as the API key for every provider imported from the file. The top-level `example` key identifies the registry record, while the nested `id` becomes the provider ID. Likewise, the model object key creates the Kimi Code alias `example/example-model`, and the nested model `id` is sent to the upstream API. +The key is sent to the registry as `Authorization: Bearer YOUR_API_KEY` and is also saved as the API key for every provider imported from the file. The top-level `example` key identifies the registry record, while the nested `id` becomes the provider ID. Likewise, the model object key creates the model alias `example/example-model` (the model name users select or reference in Kimi Code), and the nested model `id` is sent to the upstream API. ### Provider fields diff --git a/docs/zh/configuration/providers.md b/docs/zh/configuration/providers.md index 26af5495f0..d1e6cb662e 100644 --- a/docs/zh/configuration/providers.md +++ b/docs/zh/configuration/providers.md @@ -70,7 +70,7 @@ Kimi Code CLI 支持同时接入多家 LLM 平台——用 Kimi Code 托管服 kimi provider add https://registry.example.com/api.json --api-key YOUR_API_KEY ``` -该密钥会以 `Authorization: Bearer YOUR_API_KEY` 发给 registry，并保存为该文件所导入每个供应商的 API 密钥。顶层的 `example` 键用于标识 registry 记录，内部的 `id` 则成为供应商 ID。同样，模型对象的键会生成 Kimi Code 别名 `example/example-model`，内部的模型 `id` 会发送给上游 API。 +该密钥会以 `Authorization: Bearer YOUR_API_KEY` 发给 registry，并保存为该文件所导入每个供应商的 API 密钥。顶层的 `example` 键用于标识 registry 记录，内部的 `id` 则成为供应商 ID。同样，模型对象的键会生成模型别名 `example/example-model`（用户在 Kimi Code 中选择或引用模型时使用的名称），内部的模型 `id` 会发送给上游 API。 ### 供应商字段