feat(providers): manage provider headers via PATCH and ocx provider edit --headers (#959)

docs-site/src/content/docs/ja/reference/cli/providers-accounts.md

@@ -15,7 +15,7 @@ description: プロバイダー構成、資格情報、クォータ、および
 | --- | --- | --- |
 | `list` | `--json` |構成されたプロバイダーと残りのレジストリ エントリを一覧表示します。 |
 | `add <name>` | `--adapter <adapter>`、`--base-url <url>`、`--api-key <key>`、`--default-model <model>`、`--set-default`、`--force`、`--json`、`--sync` |レジストリ/カスタムプロバイダーを追加します。 `--force` は上書きします。 `--sync` は、実行中のプロキシを人間出力モードで更新します。 |
-| `edit <name>` |プロバイダーフィールドフラグ、`--json` |キー プールを置き換えずに、検証済みのライブ プロバイダー フィールドを編集します。 |
+| `edit <name>` |プロバイダーフィールドフラグ、`--headers <json>`、`--json` |キー プールを置き換えずに、検証済みのライブ プロバイダー フィールドを編集します。`--headers` はカスタム要求ヘッダーをマージします。`{}` または `-` を渡すとクリアします。 |
 | `test <name>` | `--json` |実際の上流モデルのエンドポイントを調査します。 |
 | `show <name>` | `--json` | API キーをマスクして設定を表示します。 |
 | `remove <name>` | `--json` |デフォルト以外のプロバイダーを削除します。最後のプロバイダーは削除できません。 |
@@ -35,6 +35,23 @@ ocx models --provider anthropic --json
 ocx models live --provider ark --json
 ```
 
+:::caution[カスタムヘッダーは認証情報の経路ではありません]
+`--headers` は秘密ではないリクエストメタデータ用です — ルーティングヒント、テナントや
+プロジェクトのセレクター、トレース ID など。認証情報を入れる場所ではなく、バリデーターは
+標準的な認証ヘッダー名（`Authorization`、`X-Api-Key`、`Cookie` など）を
+`apiKey` / `authMode` を使うよう案内して拒否します。
+
+ただし `X-My-Token` のような任意の名前までは判別できないため、その境界は利用者が守る
+必要があります。理由は 2 つです。
+
+- JSON はコマンドライン引数なので、秘密を入れるとシェル履歴とプロセス一覧に残ります。
+  CLI が何かを伏せるより先に、同じマシンの別プロセスが読み取れます。
+- ヘッダー値は `config.json` に平文で保存されます。専用の保存・マスキング経路を持つ
+  API キーとは異なります。
+
+秘密にあたる値は `--api-key` か OAuth ログインを使ってください。
+:::
+
 ## 認証
 
 ### `ocx login <provider>`

docs-site/src/content/docs/ja/reference/management-api.md

@@ -166,7 +166,7 @@ Authorization: Bearer <admin-token>
 | --- | --- | --- |
 | `GET /api/providers` |編集されたプロバイダー設定と検出状態をリストする | — |
 | `POST /api/providers` |検証済みプロバイダーを 1 つ追加または置換し、必要に応じてそれをデフォルトにします。 400 無効または危険な宛先または構成。 409 名前空間の衝突 |
-| `PATCH /api/providers?name=...` |許可されたプロバイダー フィールド、有効/デフォルト状態、または OpenAI アカウント モードを更新します。 400 無効なフィールドまたは遷移。 404 不明なプロバイダ |
+| `PATCH /api/providers?name=...` |許可されたプロバイダー フィールド（マージされる `headers` ブロックを含む）、有効/デフォルト状態、または OpenAI アカウント モードを更新します。 400 無効なフィールドまたは遷移。 404 不明なプロバイダ |
 | `DELETE /api/providers?name=...` |プロバイダーを削除し、可能な場合はデフォルトを再割り当てします。 404 不明なプロバイダー。 409 `last_provider`; 409 `provider_has_dependent_combos` |
 | `POST /api/providers/test?name=...` |制限されたライブプロバイダー接続/モデル検出プローブを実行する | 404 不明なプロバイダー。障害は通常、`ok: false` の証拠として返されます。
 | `GET /api/provider-quotas` |プロバイダー クォータ レポートを読む。 `refresh=1` 強制更新 | — |

docs-site/src/content/docs/ko/reference/cli/providers-accounts.md

@@ -15,7 +15,7 @@ description: 제공자 설정, 자격 증명, 할당량, 모델 카탈로그 명
 | --- | --- | --- |
 | `list` | `--json` | 설정된 제공자와 남아 있는 레지스트리 항목을 나열합니다. |
 | `add <name>` | `--adapter <adapter>`, `--base-url <url>`, `--api-key <key>`, `--default-model <model>`, `--set-default`, `--force`, `--json`, `--sync` | 레지스트리/사용자 지정 제공자를 추가합니다. `--force`는 덮어쓰고, `--sync`는 사람이 읽는 출력 모드에서 실행 중인 프록시를 새로 고칩니다. |
-| `edit <name>` | 제공자 필드 플래그, `--json` | 키 풀을 바꾸지 않고 검증된 실시간 제공자 필드를 수정합니다. |
+| `edit <name>` | 제공자 필드 플래그, `--headers <json>`, `--json` | 키 풀을 바꾸지 않고 검증된 실시간 제공자 필드를 수정합니다. `--headers`는 사용자 지정 요청 헤더를 병합하며, `{}` 또는 `-`로 지울 수 있습니다. |
 | `test <name>` | `--json` | 실제 상위 모델 엔드포인트를 확인합니다. |
 | `show <name>` | `--json` | API 키를 마스킹한 설정을 보여줍니다. |
 | `remove <name>` | `--json` | 기본값이 아닌 제공자를 제거합니다. 마지막 제공자는 제거할 수 없습니다. |
@@ -35,6 +35,23 @@ ocx models --provider anthropic --json
 ocx models live --provider ark --json
 ```
 
+:::caution[커스텀 헤더는 자격증명 통로가 아닙니다]
+`--headers`는 비밀이 아닌 요청 메타데이터용입니다 — 라우팅 힌트, 테넌트나 프로젝트
+선택자, 추적 id 같은 것들이요. 인증 정보를 넣는 자리가 아니고, 검증기는 표준 자격증명
+헤더 이름(`Authorization`, `X-Api-Key`, `Cookie` 등)을 `apiKey` / `authMode`를
+쓰라는 안내와 함께 거부합니다.
+
+다만 `X-My-Token` 같은 임의 이름까지 알아볼 수는 없으니 그 경계는 사용자가 지켜야
+합니다. 이유는 두 가지입니다.
+
+- JSON이 명령줄 인자라서, 비밀이 들어가면 셸 히스토리와 프로세스 목록에 남습니다.
+  CLI가 무엇을 가리기도 전에 같은 머신의 다른 프로세스가 읽을 수 있습니다.
+- 헤더 값은 `config.json`에 평문으로 저장됩니다. 별도 저장·마스킹 경로가 있는
+  API 키와 다릅니다.
+
+비밀에 해당하는 값은 `--api-key`나 OAuth 로그인을 쓰세요.
+:::
+
 ## 인증
 
 ### `ocx login <provider>`

docs-site/src/content/docs/ko/reference/management-api.md

@@ -166,7 +166,7 @@ Authorization: Bearer <admin-token>
 | --- | --- | --- |
 | `GET /api/providers` | redacted된 provider 구성과 discovery 상태를 나열합니다 | — |
 | `POST /api/providers` | 검증된 provider 하나를 추가하거나 교체하고, 선택적으로 기본 provider로 설정합니다 | 400 잘못되었거나 위험한 대상 또는 구성; 409 namespace 충돌 |
-| `PATCH /api/providers?name=...` | 허용된 provider 필드, enabled/default 상태, 또는 OpenAI account mode를 업데이트합니다 | 400 잘못된 필드 또는 전환; 404 알 수 없는 provider |
+| `PATCH /api/providers?name=...` | 허용된 provider 필드(병합되는 `headers` 블록 포함), enabled/default 상태, 또는 OpenAI account mode를 업데이트합니다 | 400 잘못된 필드 또는 전환; 404 알 수 없는 provider |
 | `DELETE /api/providers?name=...` | provider를 삭제하고, 가능하면 기본 provider를 재지정합니다 | 404 알 수 없는 provider; 409 `last_provider`; 409 `provider_has_dependent_combos` |
 | `POST /api/providers/test?name=...` | 제한된 live provider connectivity/model-discovery 탐색을 수행합니다 | 404 알 수 없는 provider; 실패는 보통 `ok: false` 증거로 반환됩니다 |
 | `GET /api/provider-quotas` | provider quota 보고서를 읽습니다. `refresh=1`은 새로 고침을 강제합니다 | — |

docs-site/src/content/docs/reference/cli/providers-accounts.md

@@ -16,7 +16,7 @@ both `--adapter` and `--base-url`.
 | --- | --- | --- |
 | `list` | `--json` | List configured providers and the remaining registry entries. |
 | `add <name>` | `--adapter <adapter>`, `--base-url <url>`, `--api-key <key>`, `--default-model <model>`, `--set-default`, `--force`, `--json`, `--sync` | Add a registry/custom provider. `--force` overwrites; `--sync` refreshes a running proxy in human-output mode. |
-| `edit <name>` | provider field flags, `--json` | Edit validated live provider fields without replacing key pools. |
+| `edit <name>` | provider field flags, `--headers <json>`, `--json` | Edit validated live provider fields without replacing key pools. `--headers` merges custom request headers; pass `{}` or `-` to clear them. |
 | `test <name>` | `--json` | Probe the real upstream model endpoint. |
 | `show <name>` | `--json` | Show config with API keys masked. |
 | `remove <name>` | `--json` | Remove a non-default provider; the last provider cannot be removed. |
@@ -36,6 +36,25 @@ ocx models --provider anthropic --json
 ocx models live --provider ark --json
 ```
 
+:::caution[Custom headers are not a credential channel]
+`--headers` is for non-secret request metadata — routing hints, tenant or
+project selectors, tracing ids. It is **not** a place to put authentication
+material, and the validator rejects the standard credential header names
+(`Authorization`, `X-Api-Key`, `Cookie`, and the rest) with a pointer to
+`apiKey` / `authMode`.
+
+The validator cannot recognize an arbitrary name such as `X-My-Token`, so the
+boundary is yours to respect. Two reasons it matters:
+
+- The JSON is a command-line argument, so a secret in it lands in shell history
+  and in the process list, where any other process on the machine can read it
+  before the CLI ever redacts anything.
+- Header values are persisted in `config.json` in cleartext, unlike API keys,
+  which have their own storage and masking path.
+
+Use `--api-key` or an OAuth login for anything secret.
+:::
+
 ## Authentication
 
 ### `ocx login <provider>`

docs-site/src/content/docs/reference/management-api.md

@@ -183,7 +183,7 @@ keys are not returned to dashboard clients.
 | --- | --- | --- |
 | `GET /api/providers` | List redacted provider configuration and discovery state | — |
 | `POST /api/providers` | Add or replace one validated provider and optionally make it default | 400 invalid/dangerous destination or config; 409 namespace collision |
-| `PATCH /api/providers?name=...` | Update allowed provider fields, enabled/default state, or OpenAI account mode | 400 invalid field or transition; 404 unknown provider |
+| `PATCH /api/providers?name=...` | Update allowed provider fields (including a merged `headers` block), enabled/default state, or OpenAI account mode | 400 invalid field or transition; 404 unknown provider |
 | `DELETE /api/providers?name=...` | Delete a provider, reassigning the default when possible | 404 unknown provider; 409 `last_provider`; 409 `provider_has_dependent_combos` |
 | `POST /api/providers/test?name=...` | Perform a bounded live provider connectivity/model-discovery probe | 404 unknown provider; failures are normally returned as `ok: false` evidence |
 | `GET /api/provider-quotas` | Read provider quota reports; `refresh=1` forces refresh | — |

docs-site/src/content/docs/ru/reference/cli/providers-accounts.md

@@ -17,7 +17,7 @@ pool'ами и контролируют каталог моделей, кото
 | --- | --- | --- |
 | `list` | `--json` | Показать настроенных провайдеров и оставшиеся записи registry. |
 | `add <name>` | `--adapter <adapter>`, `--base-url <url>`, `--api-key <key>`, `--default-model <model>`, `--set-default`, `--force`, `--json`, `--sync` | Добавить registry/custom-провайдера. `--force` перезаписывает; `--sync` обновляет живой прокси в human-output mode. |
-| `edit <name>` | provider field flags, `--json` | Изменить валидированные live-поля провайдера, не заменяя key-pool'ы. |
+| `edit <name>` | provider field flags, `--headers <json>`, `--json` | Изменить валидированные live-поля провайдера, не заменяя key-pool'ы. `--headers` объединяет пользовательские request-header'ы; передайте `{}` или `-`, чтобы очистить их. |
 | `test <name>` | `--json` | Пробный запрос к реальному upstream model-endpoint'у. |
 | `show <name>` | `--json` | Показать конфиг с замаскированными API-key'ами. |
 | `remove <name>` | `--json` | Удалить не-default-провайдера; последний провайдер удалить нельзя. |
@@ -37,6 +37,25 @@ ocx models --provider anthropic --json
 ocx models live --provider ark --json
 ```
 
+:::caution[Пользовательские заголовки — не канал для учётных данных]
+`--headers` предназначен для несекретных метаданных запроса — подсказок
+маршрутизации, селекторов тенанта или проекта, идентификаторов трассировки. Это не
+место для аутентификационных данных: валидатор отклоняет стандартные имена
+заголовков с учётными данными (`Authorization`, `X-Api-Key`, `Cookie` и другие),
+указывая на `apiKey` / `authMode`.
+
+Произвольное имя вроде `X-My-Token` валидатор распознать не может, поэтому границу
+соблюдает пользователь. Две причины, почему это важно:
+
+- JSON передаётся как аргумент командной строки, поэтому секрет попадает в историю
+  оболочки и в список процессов, где его прочитает любой другой процесс на машине —
+  ещё до того, как CLI что-либо скроет.
+- Значения заголовков сохраняются в `config.json` открытым текстом, в отличие от
+  API-ключей с их собственным путём хранения и маскирования.
+
+Для всего секретного используйте `--api-key` или вход через OAuth.
+:::
+
 ## Аутентификация
 
 ### `ocx login <provider>`

docs-site/src/content/docs/ru/reference/management-api.md

@@ -185,7 +185,7 @@ Endpoint'ы storage cleanup могут перемещать или навсег
 | --- | --- | --- |
 | `GET /api/providers` | Список redacted provider config'ов и состояния discovery | — |
 | `POST /api/providers` | Добавить или заменить одного валидированного провайдера и при желании сделать его default | 400 invalid/dangerous destination or config; 409 namespace collision |
-| `PATCH /api/providers?name=...` | Обновить допустимые поля провайдера, enabled/default state или OpenAI account mode | 400 invalid field or transition; 404 unknown provider |
+| `PATCH /api/providers?name=...` | Обновить допустимые поля провайдера (включая объединяемый блок `headers`), enabled/default state или OpenAI account mode | 400 invalid field or transition; 404 unknown provider |
 | `DELETE /api/providers?name=...` | Удалить провайдера, при возможности переназначив default | 404 unknown provider; 409 `last_provider`; 409 `provider_has_dependent_combos` |
 | `POST /api/providers/test?name=...` | Выполнить ограниченный live-probe connectivity/model-discovery для провайдера | 404 unknown provider; сбои обычно возвращаются как evidence с `ok: false` |
 | `GET /api/provider-quotas` | Прочитать отчёты по provider quota; `refresh=1` форсирует refresh | — |

docs-site/src/content/docs/zh-cn/reference/cli/providers-accounts.md

@@ -16,7 +16,7 @@ description: 提供方配置、凭据、配额，以及模型目录命令。
 | --- | --- | --- |
 | `list` | `--json` | 列出已配置的提供方以及剩余的注册表条目。 |
 | `add <name>` | `--adapter <adapter>`, `--base-url <url>`, `--api-key <key>`, `--default-model <model>`, `--set-default`, `--force`, `--json`, `--sync` | 添加一个注册表/自定义提供方。`--force` 会覆盖；`--sync` 会在有人类输出模式运行的代理上刷新配置。 |
-| `edit <name>` | 提供方字段标志，`--json` | 在不替换密钥池的情况下，编辑经过校验的在线提供方字段。 |
+| `edit <name>` | 提供方字段标志，`--headers <json>`，`--json` | 在不替换密钥池的情况下，编辑经过校验的在线提供方字段。`--headers` 会合并自定义请求头；传入 `{}` 或 `-` 可清空。 |
 | `test <name>` | `--json` | 探测真实的上游模型端点。 |
 | `show <name>` | `--json` | 显示已屏蔽 API 密钥的配置。 |
 | `remove <name>` | `--json` | 移除一个非默认提供方；最后一个提供方不能被移除。 |
@@ -36,6 +36,20 @@ ocx models --provider anthropic --json
 ocx models live --provider ark --json
 ```
 
+:::caution[自定义请求头不是凭据通道]
+`--headers` 用于非机密的请求元数据 —— 路由提示、租户或项目选择器、追踪 ID 等。它不是
+存放认证信息的地方，校验器会拒绝标准凭据请求头名称（`Authorization`、`X-Api-Key`、
+`Cookie` 等），并提示改用 `apiKey` / `authMode`。
+
+但校验器无法识别 `X-My-Token` 这类任意名称，因此这条边界需要你自己遵守。原因有两点：
+
+- 该 JSON 是命令行参数，机密会留在 shell 历史和进程列表中；在 CLI 做任何脱敏之前，
+  同一台机器上的其他进程就能读到。
+- 请求头的值以明文保存在 `config.json` 中，这与拥有独立存储和脱敏路径的 API 密钥不同。
+
+任何机密内容请使用 `--api-key` 或 OAuth 登录。
+:::
+
 ## 认证
 
 ### `ocx login <provider>`

docs-site/src/content/docs/zh-cn/reference/management-api.md

@@ -166,7 +166,7 @@ Authorization: Bearer <admin-token>
 | --- | --- | --- |
 | `GET /api/providers` | 列出已脱敏的 provider 配置和发现状态 | — |
 | `POST /api/providers` | 添加或替换一个已验证的 provider，并可选地将其设为默认 | 400 目标或配置无效/危险；409 命名空间冲突 |
-| `PATCH /api/providers?name=...` | 更新允许的 provider 字段、启用/默认状态，或 OpenAI 账户模式 | 400 字段或转换无效；404 未知 provider |
+| `PATCH /api/providers?name=...` | 更新允许的 provider 字段（包括合并的 `headers` 块）、启用/默认状态，或 OpenAI 账户模式 | 400 字段或转换无效；404 未知 provider |
 | `DELETE /api/providers?name=...` | 删除一个 provider，并在可能时重新分配默认值 | 404 未知 provider；409 `last_provider`；409 `provider_has_dependent_combos` |
 | `POST /api/providers/test?name=...` | 执行一个有上限的在线 provider 连通性/模型发现探测 | 404 未知 provider；失败通常以 `ok: false` 证据返回 |
 | `GET /api/provider-quotas` | 读取 provider 配额报告；`refresh=1` 会强制刷新 | — |