From b91e539eabbd4c9c0cbc1936a0f035ef596b37aa Mon Sep 17 00:00:00 2001 From: jiachen Date: Sun, 20 Sep 2026 00:14:50 +0800 Subject: [PATCH] docs: document custom_provider headers for third-party relays --- README.md | 2 ++ README_ZH.md | 2 ++ docs/examples.md | 20 ++++++++++++++++++++ 3 files changed, 24 insertions(+) diff --git a/README.md b/README.md index 68a1104c1..c32c50211 100644 --- a/README.md +++ b/README.md @@ -98,6 +98,8 @@ mcode Supported API formats: `openai-completions`, `openai-responses`, and `anthropic-messages`. See the [model examples](docs/examples.md#2-choose-your-own-model) for environment variable setup, connection checks, and model overrides for a single run. +Providers added this way are stored under `custom_provider` in the active profile's `config.yaml`; this is the supported path for third-party or self-hosted endpoints, while `minimax_api` stays reserved for the official MiniMax API. Relays that require `Authorization: Bearer` on an Anthropic-compatible endpoint can set custom headers in `config.yaml`; see [Third-party relays and custom auth headers](docs/examples.md#third-party-relays-and-custom-auth-headers). + ### 3. Run your first task diff --git a/README_ZH.md b/README_ZH.md index 32d3ab2b9..64459aa64 100644 --- a/README_ZH.md +++ b/README_ZH.md @@ -98,6 +98,8 @@ mcode 支持 `openai-completions`、`openai-responses` 和 `anthropic-messages`。连接测试、单次模型切换及环境变量设置见 [模型示例](docs/examples.md#2-choose-your-own-model)。 +通过该命令添加的提供方保存在当前 profile `config.yaml` 的 `custom_provider` 下；第三方或自建端点一律走这条路径，`minimax_api` 保留给官方 MiniMax API。若中转端点只提供 Anthropic 兼容接口且要求 `Authorization: Bearer` 鉴权，可在 `config.yaml` 中为提供方配置自定义 headers；见[第三方中转与自定义鉴权头](docs/examples.md#third-party-relays-and-custom-auth-headers)。 + ### 3. 完成第一个任务 diff --git a/docs/examples.md b/docs/examples.md index 12a536569..6e92c7327 100644 --- a/docs/examples.md +++ b/docs/examples.md @@ -66,6 +66,26 @@ pnpm mcode provider list --json `--api-key-env` reads the current environment variable value and stores that value in the active profile's `config.yaml`; it does not save an environment-variable reference. The file still contains plaintext credentials. On POSIX systems, config writes and temporary copies use `0600`. When loading existing files, MCode removes group/other access while preserving the owner's permissions; already-private files such as `0400` or `0600` do not require a permission change. Loading fails if an unsafe main config cannot be restricted. Older migration backups are also checked, but inspection or repair failures produce a warning identifying the directory or backup that needs manual attention rather than preventing the main config from loading. Windows file modes do not provide equivalent ACL protection; restrict access to the profile directory using Windows permissions. +### Third-party relays and custom auth headers + +Providers created by `mcode provider add` are stored under `custom_provider` in the active profile's `config.yaml`. That tree is the supported home for any endpoint other than the official MiniMax API; `minimax_api` is reserved for the official endpoint and keeps its fixed authentication scheme. + +Authentication follows the API format: `openai-completions` and `openai-responses` send `Authorization: Bearer `, and `anthropic-messages` sends the key as `x-api-key`. A relay that expects Bearer authentication on an OpenAI-compatible endpoint therefore needs no extra configuration. If a relay only exposes an Anthropic-compatible endpoint (`/v1/messages`) and requires Bearer authentication, add explicit headers to the provider entry in `config.yaml`: + +```yaml +custom_provider: + my-relay: + options: + apiKey: sk-relay-key + baseURL: https://relay.example.com + headers: + Authorization: Bearer sk-relay-key + models: + MiniMax-M2: {} +``` + +`api` can be omitted and defaults to `anthropic-messages`. Configured headers are sent on both connection tests and conversation requests, and they are part of the connection-test fingerprint, so editing them retires a cached test verdict. The default `x-api-key` header is still sent alongside; the relay must tolerate rather than reject it. Header values are stored in plaintext like `apiKey` and are reported by name only in provider views. After editing the file, verify with `mcode provider list` and `mcode provider test `. + [Live acceptance](verification.md) separately verified MiniMax Token Plan and one configured BYOK provider. This is not a guarantee for every compatible service. ## 3. Search and image input