====== CLIProxyAPI ======

//Vytvořeno: **21.8.2026** | Aktualizováno: **~~LASTMOD~~**//

[[https://github.com/router-for-me/CLIProxyAPI|CLIProxyAPI]] je lokální proxy služba v Go, která převádí rozhraní OpenAI, Gemini, Anthropic/Claude, Codex a Grok. Umožňuje použít jeden AI klient nebo coding agent s modelem přihlášeným u jiného podporovaného poskytovatele.

===== Princip =====

CLIProxyAPI stojí mezi klientem a modelem. Přijme požadavek v protokolu klienta, přeloží jej pro zvolený upstream a odpověď vrátí zpět v očekávaném formátu.

<code>
Claude Code → CLIProxyAPI → Codex/GPT, Claude, Gemini, Grok nebo jiný kompatibilní upstream
</code>

Projekt podporuje OAuth přihlášení pro Codex, Claude Code, Gemini/Antigravity a Grok Build, API klíče i vlastní OpenAI-compatible upstreamy. Podle podpory upstreamu zprostředkuje streaming, tool/function calling, multimodální vstupy a některé WebSocket scénáře.

===== Ověřená instalace pro Claude Code a ChatGPT =====

Následující postup byl ověřený na Alpine Linuxu pro ARM64. CLIProxyAPI bylo sestavené ze zdrojových kódů; projekt vyžadoval Go alespoň ve verzi 1.26. Lokální Go 1.25.10 proto sestavení odmítlo. Pokud není vynucený ''GOTOOLCHAIN=local'', Go si může potřebný toolchain stáhnout automaticky.

Pro izolované lokální použití má proxy poslouchat na ''127.0.0.1'' a používat samostatný adresář ''~/.cli-proxy-api'' pro konfiguraci a OAuth credentials. V ověřené instalaci běžela na portu ''8317''.

==== Přihlášení k ChatGPT přes Codex OAuth ====

Podle [[https://help.router-for.me/agent-client/claude-code|dokumentace pro Claude Code]] umí CLIProxyAPI vystavit Anthropic-compatible rozhraní. Pro headless prostředí fungovalo přihlášení Codex device-code flow:

<code bash>
./cli-proxy-api --codex-device-login
</code>

Příkaz vypíše jednorázový kód. Ten se dokončí v prohlížeči na zařízení, kde je možné se přihlásit k ChatGPT účtu. Po úspěšném přihlášení se credentials uloží do ''~/.cli-proxy-api''.

Proxy se následně spustí například takto:

<code bash>
cd ~/cliproxyapi && nohup ./cli-proxy-api -config ~/.cli-proxy-api/config.yaml > ~/cliproxyapi.log 2>&1 &
</code>

Ověřené byly endpointy ''/v1/models'' i Anthropic-compatible ''/v1/messages''; proxy vrátila modely i odpověď z GPT modelu. Proces spuštěný přes ''nohup'' přežije zavření terminálu, ale ne restart kontejneru nebo hostitele. Trvalé spuštění přes OpenRC či jiný init systém je potřeba nastavit zvlášť.

==== Samostatný příkaz ''claudex'' ====

Globální ''~/.claude/settings.json'' není vhodné přepisovat, pokud má běžný příkaz ''claude'' dál mířit přímo na Anthropic. Praktické řešení je samostatný wrapper ''~/.local/bin/claudex'', který nastaví proxy pouze pro nový proces:

<code bash>
#!/usr/bin/env bash
export ANTHROPIC_BASE_URL="http://127.0.0.1:8317"
export ANTHROPIC_AUTH_TOKEN="<api-klic-z-config.yaml>"
export CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY="1"
exec claude "$@"
</code>

''ANTHROPIC_AUTH_TOKEN'' je API klíč nastavený pro CLIProxyAPI; do wrapperu nepatří skutečný klíč zkopírovaný do dokumentace nebo repozitáře. Proměnná ''CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1'' zpřístupní modely oznámené proxy. Po spuštění ''claudex'' lze model vybrat přes ''/model'' nebo ho předat při startu:

<code bash>
claudex --model gpt-5.6-sol
</code>

Při ověřené instalaci byly přes proxy dostupné mimo jiné modely ''gpt-5.6-sol'', ''gpt-5.6-terra'' a ''gpt-5.6-luna''. Dostupný seznam závisí na aktuálním přihlášeném účtu a verzi proxy; je vhodné si jej ověřit přes ''/v1/models''.

==== Co nelze přepnout za běhu ====

''ANTHROPIC_BASE_URL'' určuje server při startu Claude Code. Příkaz ''/model'' mění pouze vybraný model na již nastaveném serveru, ne připojený server. Nelze tedy mít jednu spuštěnou session přímo u Anthropicu a za běhu ji přepnout na lokální GPT proxy.

Pro zachování oddělených backendů je možné používat:

  * ''claude'' pro přímé připojení k Anthropicu,
  * ''claudex'' pro GPT přes lokální CLIProxyAPI.

Při změně backendu jde o nový proces Claude Code. Volba ''--continue'' může navázat na historii předchozí session, ale nejde o živé přepnutí backendu. Stejně tak nelze v jedné session nechat hlavního agenta přímo na Anthropicu a pouze subagenta poslat přes tuto proxy: všechny procesy session sdílejí stejné připojení.

===== Aliasování modelů pro vestavěné subagenty =====

Vestavěný nástroj ''Agent'' v Claude Code nepředává proxy obecné jméno jako ''luna'' nebo ''terra''. Při volbě například ''sonnet'' pošle přesné Claude ID ''claude-sonnet-5''. Původně proto vestavění subagenti přes Codex OAuth selhávali chybou ''API Error: 400 unknown provider for model claude-…'': proxy měla k dispozici GPT modely, ale neznala Claude ID, která volal harness.

Zakázat ''Agent'' není řešení. Přepínač ''%%--%%disallowedTools Agent'' by pouze odebral vestavěné subagenty; automaticky by je nepřesměroval na jiný CLI proces. Alias se řeší na správné vrstvě: [[https://help.router-for.me/agent-client/claude-code|CLIProxyAPI]] přepíše Claude ID před odesláním do Codex/GPT upstreamu a odpověď vrátí pod původním Claude ID.

==== Konfigurace aliasů ====

Aliasy jsou globální konfigurace sdílené proxy v ''~/.cli-proxy-api/config.yaml'', konkrétně v sekci ''oauth-model-alias.codex''. ''codex'' určuje, že se pravidla použijí pro Codex OAuth upstream. Aktivní mapování je:

<code yaml>
oauth-model-alias:
  codex:
    - name: "gpt-6-sol"
      alias: "claude-fable-5-1"
      fork: true
      force-mapping: true

    - name: "gpt-5.6-terra"
      alias: "claude-opus-5-5"
      fork: true
      force-mapping: true

    - name: "gpt-6-luna"
      alias: "claude-sonnet-5"
      fork: true
      force-mapping: true
</code>

^ Volba pro vestavěný ''Agent'' ^ Claude ID v požadavku ^ Skutečný GPT model ^
| ''fable'' | ''claude-fable-5-1'' | ''gpt-6-sol'' |
| ''opus'' | ''claude-opus-5-5'' | ''gpt-5.6-terra'' |
| ''sonnet'' | ''claude-sonnet-5'' | ''gpt-6-luna'' |

''name'' je cílový upstream model a ''alias'' je název, který přijímá klient. ''fork: true'' zachová v katalogu proxy také přímé GPT jméno. ''force-mapping: true'' zajistí, že Claude Code dostane odpověď pod stejným Claude ID, které požadoval. Harness tak nevidí změnu názvu modelu uprostřed relace.

Alias nerozšiřuje rozhraní ''Agent'' o novou volbu modelu. Nelze proto volat ''Agent(model: "luna")''. Pro Lunu se volí ''sonnet'', který CLIProxyAPI přeloží na ''gpt-6-luna''; pro Sol ''fable'' a pro Terru ''opus''.

==== Ověření a údržba ====

Mapování bylo ověřené 27.9.2026. Živý katalog proxy obsahoval všechny tři Claude aliasy, samostatný minimální požadavek přes každý alias skončil úspěšně a vestavěný subagent ''Explore'' dokončil běh bez chyby ''unknown provider''.

Alias je přesná shoda názvu. Po vydání nového modelu nebo změně ID, které Claude Code používá pro ''Agent'', je potřeba upravit stejnou sekci ''oauth-model-alias.codex''. Typickým příznakem chybějícího pravidla je ''API Error: 400 unknown provider for model claude-…''.

Po změně je potřeba ověřit alespoň:

  - že ''/v1/models'' zveřejňuje nový alias i očekávaný GPT cíl,
  - minimální požadavek přes nové Claude ID,
  - jeden vestavěný subagent, protože až ten prověří skutečnou cestu Claude Code → CLIProxyAPI → GPT.

V ověřené instalaci se změna konfigurace projevila v katalogu proxy bez restartu. Neber to ale jako záruku pro každou verzi CLIProxyAPI; po aktualizaci je nutné ověřit, jak načítá konfiguraci konkrétní běžící proces.

===== Routing více účtů a modelů =====

Při více přihlašovacích údajích umí CLIProxyAPI používat round-robin, weighted round-robin nebo fill-first routing. Konfigurace obsahuje také retry, cooldown po chybách, volitelnou afinitu relace ke konkrétnímu účtu a modelové prefixy pro jednoznačné směrování.

Tato vrstva je užitečná hlavně tehdy, když je potřeba:

  * přepínat backendové modely bez změny hlavního klienta,
  * používat více účtů stejného poskytovatele,
  * směrovat různé modelové názvy na různé upstreamy,
  * provozovat klienta nad vlastním OpenAI-compatible API.

===== Bezpečnost a provoz =====

Proxy pracuje s OAuth tokeny a API klíči. Výchozí konfigurační soubor nastavuje ''host: ""'', což znamená naslouchání na všech IPv4 a IPv6 rozhraních. Pro lokální použití je bezpečnější nastavit ''127.0.0.1'' nebo ''localhost'', používat vlastní silný API klíč a nevystavovat službu ani její management rozhraní přímo do internetu.

Přihlašovací údaje se standardně ukládají do ''~/.cli-proxy-api''. Management API vyžaduje samostatný tajný klíč; pokud zůstane prázdný, management endpointy se nezpřístupní. Pluginy jsou ve výchozí konfiguraci vypnuté, protože se načítají jako důvěryhodný kód přímo do procesu.

===== Kontextová okna GPT a wrapper ''claudex'' =====

CLIProxyAPI oznamuje klientovi velikosti oken přes ''/v1/models''. Hodnoty pro Codex/GPT ale vycházejí z [[https://github.com/router-for-me/models|komunitního katalogu router-for-me/models]], nikoli z měření konkrétního účtu. Katalog je vhodný jako průběžně aktualizovaný zdroj modelů, ale deklarované číslo není samo o sobě důkaz skutečného stropu API.

==== Obnovení přihlášení po změně tarifu ====

Po změně tarifu ChatGPT je vhodné vytvořit nové Codex OAuth přihlášení, aby proxy získala aktuální token:

<code bash>
cd ~/cliproxyapi
./cli-proxy-api --codex-device-login -config ~/.cli-proxy-api/config.yaml
</code>

Starý OAuth soubor pro stejný účet je potřeba z ''~/.cli-proxy-api'' odstranit, aby proxy neměla dva záznamy s rozdílnými atributy. Přípona v názvu souboru a ''plan_type'' jsou jen údaje pro výběr katalogu; nejsou samy o sobě spolehlivým důkazem dostupného kontextového okna.

==== Katalog, endpoint a skutečný limit jsou různé údaje ====

V této instalaci prošel vstup o 900 314 tokenech u ''gpt-5.6-luna'', ''gpt-5.6-sol'', ''gpt-5.6-terra'' a ''gpt-6-astra''. U luny a astry selhal vstup o 1 000 314 tokenech; luna selhala už při 950 314 tokenech. Hodnota 921 000 proto leží v ověřeném intervalu pro lunu a astru. U sol a terra je ověřena pouze dolní hranice 900 314 tokenů.

To opravuje původní závěr, že ''gpt-6-astra'' má pevné okno 272 000 tokenů. Katalog pro něj uváděl chybnou hodnotu 272 000; problém popisuje [[https://github.com/router-for-me/models/issues/53|issue #53 komunitního katalogu]]. Naopak ''gpt-5.5'' při testu neprošel přes 350 314 tokenů a ''gpt-5.3-codex-spark'' přes 200 314 tokenů. Velké okno proto nelze zobecnit na všechny GPT modely.

==== GPT prompt cache nad 272 000 tokenů ====

Hranice 272 000 tokenů cache nevypíná. Při opakování stejného požadavku byla druhá odpověď cacheovaná z 99,7 % u vstupu 60 314 tokenů a z 99,95 % u vstupu 400 314 tokenů. Druhé měření je přímo nad hranicí 272 000 tokenů.

Některé veřejné zdroje spojují tuto hranici s dražším dlouhým vstupem u placeného API. V této instalaci ale nebyl změřen dopad na kvótu ChatGPT předplatného. Výchozí strop 272 000 tokenů je proto provozní volba pro vědomé používání dlouhého kontextu, ne potvrzený tarifní limit ani hranice prompt cache.

==== Podmíněná oprava Astry a volba plného okna ====

Wrapper ''claudex'' načte okno živě z proxy a nastaví ho přes ''CLAUDE_CODE_MAX_CONTEXT_TOKENS''. Protože katalog Astry vracel přesně chybných 272 000 tokenů, wrapper obsahuje podmíněnou opravu:

<code bash>
CLAUDEX_WINDOW_FIXES="${CLAUDEX_WINDOW_FIXES-gpt-6-astra|272000|921000}"
</code>

Pravidlo znamená: pokud katalog pro ''gpt-6-astra'' hlásí právě 272 000, použij 921 000. Jakmile katalog začne vracet jinou hodnotu, podmínka přestane platit a wrapper znovu použije živý údaj z proxy. Korekci lze pro diagnostiku vypnout prázdnou proměnnou ''CLAUDEX_WINDOW_FIXES''.

Běžný běh wrapperu je zastropovaný proměnnou ''CLAUDEX_CTX_ECO'' na 272 000 tokenů. Plné okno se vyžádá explicitně:

<code bash>
claudex --ctx-max
</code>

Ruční hodnota ''CLAUDEX_CTX'' má přednost před údajem z proxy i úsporným stropem. Kontextové okno Claude Code nelze změnit v již běžící session, protože se předává proměnnou prostředí při startu procesu. Pro navázání na poslední session s plným oknem slouží:

<code bash>
claudex --ctx-max --continue
</code>

Konfigurace stejného problému pro OpenCode je samostatně v článku [[ai:platformy:opencode:kontextova-okna-gpt|Kontextová okna GPT v OpenCode]]. OpenCode v této instalaci používá přímé OpenAI OAuth, takže změna OAuth tokenu CLIProxyAPI jeho limity neovlivní.

===== Omezení =====

Překlad protokolu nemůže zaručit plnou shodu funkcí. Záleží na konkrétním modelu a upstreamu, zda správně fungují tool calls, streaming, reasoning bloky, prompt cache, dlouhé relace nebo poskytovatelem specifické funkce.

Použití OAuth předplatného přes jiný klient také automaticky neznamená oprávnění k API použití. Před nasazením je potřeba ověřit aktuální podmínky každého použitého poskytovatele; použití proxy s OAuth tokenem může nést riziko omezení nebo blokace účtu.

Pokud má Codex fungovat jako samostatný specialista vedle Claude Code, místo náhrady hlavního backendu, je vhodnější [[ai:mcp:cc-codex-bridge|cc-codex-bridge]].

===== Zdroje =====

  * [[https://github.com/router-for-me/CLIProxyAPI|CLIProxyAPI – zdrojový kód a dokumentace]]
  * [[https://help.router-for.me/agent-client/claude-code|CLIProxyAPI – konfigurace Claude Code]]
  * [[https://github.com/router-for-me/models|router-for-me/models – komunitní katalog modelů]]
  * [[https://github.com/router-for-me/models/issues/53|router-for-me/models issue #53 – nesoulad kontextového okna Astry]]
  * [[https://x.com/thsottiaux/status/2076119366647894371?s=20|Tibo na X – ukázka aliasu claudex]]