Skip to content

docs(provider): document custom registry format #2864

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
LouisDM wants to merge 1 commit into
base: main
Choose a base branch
from
+194 −2
Open

docs(provider): document custom registry format #2864

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
98 changes: 97 additions & 1 deletion docs/en/configuration/providers.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -32,14 +32,110 @@ 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.
:::

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.

@chatgpt-codex-connector chatgpt-codex-connector Bot Aug 13, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Define “model alias” at first use

The new section calls example/example-model an alias without explaining that this is the model name users select or reference, yet later field and refresh descriptions rely on “alias” and “namespace” to explain important behavior. Add a short parenthetical gloss at this first occurrence so non-technical readers can understand those rules without prior configuration knowledge.

AGENTS.md reference: docs/AGENTS.md:L44-L46

Useful? React with 👍 / 👎.


### 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 `<providerId>/...` 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.
Expand Down
98 changes: 97 additions & 1 deletion docs/zh/configuration/providers.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -32,14 +32,110 @@ 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` 管理。
:::

非交互环境下也可以用 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 元数据
- 保留无关供应商、仍存在供应商在自动生成的 `<providerId>/...` 命名空间之外的手动别名，以及 registry 不负责管理的额外模型字段

如果拉取 registry 失败，现有供应商配置会保持不变，刷新结果会报告该失败。

## `kimi`

用于对接 Moonshot AI 的 OpenAI 兼容接口，包括 Kimi Code 托管服务和 Kimi Platform API 密钥。
Expand Down