CLIProxyAPI

CLI サブスクリプション（Gemini / OpenAI Codex / Claude Code / Grok など）を OAuth または API キーで束ね、OpenAI・Gemini・Claude・Codex・Grok 互換のローカル API として公開する Go プロキシ。router-for-me/CLIProxyAPI の技術概要。

1 — 概要

何をするか

クライアント側はいつもの OpenAI / Anthropic / Gemini SDK やコーディングツールのまま、待ち受けはローカルの CLIProxyAPI。上流は複数アカウントのラウンドロビン、OAuth トークン更新、プロトコル翻訳（translator）、プロバイダ別 executor が担当する。バイナリ単体でも、sdk/cliproxy を埋め込んでも使える。

8317デフォルト待受ポート

Go 1.26+ランタイム

OAuthCodex / Claude / Gemini / Grok

v7Go module path

公式ガイドは help.router-for.me。管理 API・コントロールパネルは設定の remote-management 経由。

2 — アーキテクチャ

リクエスト経路

flowchart TD
  CLI["クライアント\nOpenAI / Claude / Gemini SDK"] --> API["internal/api\nGin ルート"]
  API --> AUTH["api-keys / access"]
  AUTH --> THINK["internal/thinking\n正規化"]
  THINK --> TR["internal/translator\nスキーマ変換"]
  TR --> MGR["auth.Manager\nアカウント選択"]
  MGR --> EXEC["runtime/executor\nプロバイダ呼出"]
  EXEC --> UP["上流\nCodex / Claude / Gemini / Grok / OpenAI互換"]
  UP --> EXEC
  EXEC --> TR
  TR --> CLI
  CFG["config.yaml + watcher"] -.-> API
  CFG -.-> MGR
  REG["model registry"] -.-> API

thinking は一度カノニカルな ThinkingConfig に落としてからプロバイダ別出力へ翻訳する。translator は inbound スキーマ ↔ プロバイダスキーマの双方向変換。executor が実際の HTTP / WebSocket 呼び出しを担う。

主要ディレクトリ

cmd/server/              # エントリポイント
internal/api/            # Gin HTTP（routes / middleware）
internal/runtime/executor/ # プロバイダ実行
internal/translator/     # プロトコル翻訳
internal/thinking/       # reasoning 正規化パイプライン
internal/registry/       # モデル一覧 + リモート更新
internal/watcher/        # 設定ホットリロード
sdk/cliproxy/            # 埋め込み用 SDK
config.example.yaml      # 設定テンプレート

3 — 互換 API

クライアントから見える面

面	内容
互換エンドポイント	OpenAI（Responses 含む）/ Gemini / Claude / Grok
OAuth ログイン	OpenAI Codex、Claude Code、Grok Build、Gemini 系
レスポンス形	ストリーミング / 非ストリーミング / WebSocket（対応プロバイダ）
ツール	function calling / tools、マルチモーダル（テキスト・画像）
負荷分散	Gemini / OpenAI / Claude / Grok のマルチアカウント・ラウンドロビン
上流プロバイダ	設定で OpenAI 互換（例: OpenRouter）を追加可能

クライアント形式 → translator → executor → 上流形式 → translator（応答）

4 — 起動と設定

ビルドと実行

go build -o cli-proxy-api ./cmd/server
go run ./cmd/server --config config.yaml
# よく使うフラグ: --tui --standalone --local-model --no-browser
#                --oauth-callback-port <port>

Docker は docker-compose.yml でイメージ eceasy/cli-proxy-api を起動。ホスト側の config.yaml と認証ディレクトリ（既定 ~/.cli-proxy-api）をマウントする。待受は主に 8317、OAuth コールバック用に追加ポートを公開する。

設定の要点（config.example.yaml）

キー	既定 / 例	説明
`host`	`""`（全インタフェース）	ローカル限定なら `127.0.0.1`
`port`	`8317`	HTTP 待受
`auth-dir`	`~/.cli-proxy-api`	OAuth / 認証マテリアル
`api-keys`	配列	クライアント認証用キー
`remote-management.secret-key`	空で無効	管理 API（`/v0/management`）有効化
`remote-management.allow-remote`	`false`	非 localhost からの管理アクセス
`plugins.enabled`	`false`	動的プラグイン（既定オフ）
`tls.enable`	`false`	HTTPS（cert / key 指定）

管理 API は secret-key 必須。 プレーンテキストを書くと起動時にハッシュ化される。空のままだと /v0/management は 404。パネル資産は GitHub の Cli-Proxy-API-Management-Center から取得する設定が既定。

5 — Go SDK

埋め込み（sdk/cliproxy）

モジュールパスは github.com/router-for-me/CLIProxyAPI/v7/...（go.mod 準拠。SDK ガイド文書に残る v6 表記よりこちらを優先）。設定ロード → Builder → Run(ctx) で、設定監視・トークン更新・グレースフルシャットダウンまで含む。

go get github.com/router-for-me/CLIProxyAPI/v7/sdk/cliproxy

cfg, _ := config.LoadConfig("config.yaml")
svc, _ := cliproxy.NewBuilder().
    WithConfig(cfg).
    WithConfigPath("config.yaml").
    Build()
_ = svc.Run(ctx) // cancel で停止

拡張ポイント

WithServerOptions — ミドルウェア、ルート、ログ
WithCoreAuthManager — 独自 transport / フック
カスタム executor + translator 登録（sdk-advanced）

SDK ドキュメント

6 — 管理と周辺

使用量・管理 UI

v6.10.0 以降、本体と CPAMC に内蔵の使用量統計は無い。必要なら外部プロジェクトを併用する。

プロジェクト	役割
CPA Usage Keeper	定期同期・SQLite・集計 API・ダッシュボード
CPA-Manager-Plus	リクエスト監視・コスト推定・Codex プール運用
Management Center	設定の管理パネル（バンドル資産）

エコシステム例: vibeproxy、Quotio、ProxyPilot、CCS など — CLI サブスクを API キーなしでコーディングツールへ繋ぐ GUI / CLI ラッパーが README に列挙されている。

プラグインは信頼境界あり。 plugins.enabled は既定 false。c-shared / C ABI の動的ライブラリはプロセス内コードとして扱われる。OpenAI 互換設定とネイティブ executor が衝突する場合はネイティブ側が優先。

7 — 参考リンク

公式・ガイド

GitHub: router-for-me/CLIProxyAPI — 本体（MIT）
CLIProxyAPI Guides — 公式ドキュメント
Management API — 管理エンドポイント
config.example.yaml — 設定テンプレート
examples/custom-provider — カスタムプロバイダ例