diff --git a/README.md b/README.md index 25e0090e..ab427e6c 100644 --- a/README.md +++ b/README.md @@ -74,6 +74,14 @@ CLIProxyAPI includes integrated support for [Amp CLI](https://ampcode.com) and A - **Model mapping** to route unavailable models to alternatives (e.g., `claude-opus-4.5` → `claude-sonnet-4`) - Security-first design with localhost-only management endpoints +When routing needs to stay deterministic, prefer the provider-specific paths over the merged OpenAI-compatible `/v1/...` endpoints: + +- Use `/api/provider/anthropic/v1/messages` to force the Anthropic executor. +- Use `/api/provider/google/v1beta/models/...` to force the Gemini/Google executor. +- Use `/api/provider/openai/v1/chat/completions` for OpenAI-compatible executors. + +This matters when `oauth-model-alias`, alias pools, or fallback mappings reuse the same client-visible model name across multiple backends. In those cases, `/v1/models` may show the merged alias view instead of the executor you intend to hit. Treat the provider-specific request path as the source of truth for backend selection. + **→ [Complete Amp CLI Integration Guide](https://help.router-for.me/agent-client/amp-cli.html)** ## SDK Docs diff --git a/README_CN.md b/README_CN.md index 6301e403..a5675499 100644 --- a/README_CN.md +++ b/README_CN.md @@ -73,6 +73,14 @@ CLIProxyAPI 已内置对 [Amp CLI](https://ampcode.com) 和 Amp IDE 扩展的支 - 智能模型回退与自动路由 - 以安全为先的设计,管理端点仅限 localhost +当你需要确定地命中某个后端执行器时,优先使用 provider-specific 路径,而不是合并后的 OpenAI 兼容 `/v1/...` 端点: + +- 使用 `/api/provider/anthropic/v1/messages` 强制走 Anthropic 执行器。 +- 使用 `/api/provider/google/v1beta/models/...` 强制走 Gemini/Google 执行器。 +- 使用 `/api/provider/openai/v1/chat/completions` 强制走 OpenAI 兼容执行器。 + +这一点在 `oauth-model-alias`、alias 池或 model fallback 让多个后端复用同一个客户端可见模型名时尤其重要。此时 `/v1/models` 可能展示的是合并后的别名视图,而不是你真正想命中的执行器。对于后端选择,请以 provider-specific 的请求路径为准。 + **→ [Amp CLI 完整集成指南](https://help.router-for.me/cn/agent-client/amp-cli.html)** ## SDK 文档 diff --git a/README_JA.md b/README_JA.md index 4dbd36bb..036fdcc2 100644 --- a/README_JA.md +++ b/README_JA.md @@ -74,6 +74,14 @@ CLIProxyAPIは[Amp CLI](https://ampcode.com)およびAmp IDE拡張機能の統 - 利用できないモデルを代替モデルにルーティングする**モデルマッピング**(例:`claude-opus-4.5` → `claude-sonnet-4`) - localhostのみの管理エンドポイントによるセキュリティファーストの設計 +どのバックエンド実行系に送るかを確定させたい場合は、統合された OpenAI 互換 `/v1/...` エンドポイントよりも provider-specific のパスを優先してください。 + +- Anthropic 実行系を強制したい場合は `/api/provider/anthropic/v1/messages` +- Gemini/Google 実行系を強制したい場合は `/api/provider/google/v1beta/models/...` +- OpenAI 互換実行系を強制したい場合は `/api/provider/openai/v1/chat/completions` + +これは `oauth-model-alias`、alias プール、model fallback によって複数のバックエンドが同じクライアント向けモデル名を共有する場合に特に重要です。その場合、`/v1/models` は実際に狙っている実行系ではなく、統合後のエイリアス表示を返すことがあります。バックエンド選択の基準としては provider-specific のリクエストパスを使ってください。 + **→ [Amp CLI統合ガイドの完全版](https://help.router-for.me/agent-client/amp-cli.html)** ## SDKドキュメント diff --git a/config.example.yaml b/config.example.yaml index 42867ecb..0493c544 100644 --- a/config.example.yaml +++ b/config.example.yaml @@ -281,6 +281,9 @@ nonstream-keepalive-interval: 0 # These aliases rename model IDs for both model listing and request routing. # Supported channels: gemini-cli, vertex, aistudio, antigravity, claude, codex, qwen, iflow, kimi. # NOTE: Aliases do not apply to gemini-api-key, codex-api-key, claude-api-key, openai-compatibility, vertex-api-key, or ampcode. +# NOTE: Because aliases affect the merged /v1 model list and merged request routing, overlapping +# client-visible names can become ambiguous across providers. When you need deterministic backend +# selection, prefer /api/provider/{provider}/... instead of the generic /v1/... endpoints. # You can repeat the same name with different aliases to expose multiple client model names. # oauth-model-alias: # gemini-cli: