# Le proxy LLM

> tokenade llm-proxy se place en local entre un agent et son fournisseur, replie les résultats déjà dans l'historique et lit l'usage réel.

Source: https://tokenade.net/fr/docs/llm-proxy · Updated: 2026-10-07

`tokenade llm-proxy` est un proxy HTTP local entre votre agent et son fournisseur de modèle. À l'aller, il replie les résultats d'outils déjà présents dans l'historique de la conversation, retire les doublons exacts et masque les identifiants ; au retour, il lit la consommation de tokens annoncée par le fournisseur lui-même. C'est la solution de repli pour les agents, ou les parties d'agents, que les hooks ne peuvent pas atteindre.

## Sa place

Tokenade atteint un agent par le meilleur canal disponible, dans cet ordre :

1. les hooks (ou un plugin passerelle), qui agissent avant même l'envoi d'un résultat d'outil ;
2. l'enveloppe shell (`tokenade wrap`) ;
3. le proxy MCP ([`mcp-wrap`](https://tokenade.net/fr/docs/mcp-wrap)) ;
4. le proxy LLM.

Le proxy LLM arrive en dernier parce qu'il ne peut pas changer le tour où un résultat brut arrive pour la première fois : il retire le coût de ce résultat de tous les tours suivants. Quand les hooks d'un agent fonctionnent, le proxy ne couvre que ce qu'ils ne font pas, et rien n'est fait deux fois.

## Utilisation

```text
tokenade llm-proxy --upstream <url> [--listen 127.0.0.1:8787] [--agent <name>]
                   [--remote] [--no-compaction]

tokenade llm-proxy install --agent <name> [--listen <addr>] [--autostart]
tokenade llm-proxy uninstall --agent <name>
tokenade llm-proxy status
```

Alias : `llm_proxy`.

| Option | Défaut | Effet |
| --- | --- | --- |
| `--upstream <url>` | | URL de base du fournisseur. Sans elle, `llm-proxy` sert tous les agents enregistrés par `install` |
| `--listen <addr>` | `127.0.0.1:8787` | Adresse d'écoute. `install` attribue un port à chaque agent (8787, 8788, …) |
| `--agent <name>` | | Agent servi par ce port ; les économies lui sont attribuées |
| `--remote` | désactivé | Obligatoire pour écouter ailleurs qu'en local. Le processus détient votre clé d'API : une écoute hors boucle locale est joignable depuis d'autres machines |
| `--no-compaction` | désactivé | Relaie sans replier |
| `--autostart` | désactivé | Avec `install` : écrit la définition de service de la plateforme et affiche les commandes qui l'activent |
| `--enable` | désactivé | Avec `install --autostart` : exécute aussi ces commandes |

## Faire pointer un agent vers le proxy

```bash
tokenade llm-proxy install --agent aider --autostart
```

`install` annonce d'abord ce qu'il va changer et où partira le trafic, puis réécrit la configuration de l'agent pour qu'il passe par le proxy local :

| Agent | Ce qui change |
| --- | --- |
| Codex (CLI et app) | `~/.codex/config.toml` : `model_provider = "tokenade"` et un `base_url` dans `[model_providers.tokenade]` |
| Claude Code | `ANTHROPIC_BASE_URL` dans le bloc `env` de `settings.json`. Sert surtout à des chiffres de coût exacts : les hooks font déjà le repli, le proxy ne replie donc que ce qu'ils n'ont pas touché, par exemple un résultat de `WebFetch` |
| Qwen Code, OpenClaw | `OPENAI_BASE_URL` dans les réglages de l'agent |
| Copilot CLI | `COPILOT_PROVIDER_BASE_URL` |
| Cursor | `CURSOR_API_ENDPOINT` dans le profil de votre shell |
| Autres | Aider, OpenCode, Kilo Code, Grok, Cline, Hermes, Droid, Pi, Copilot dans VS Code, Devin Desktop : leur propre fichier de configuration |

Claude Desktop, Claude Cowork et l'app Codex en tant que cible distincte sont refusés. L'app Codex partage `~/.codex/config.toml` avec la CLI : `--agent codex` couvre donc les deux.

`uninstall --agent <name>` remet le point d'accès d'origine de l'agent.

```text
$ tokenade llm-proxy status
aider        ~/.aider.conf.yml on 127.0.0.1:8787 → https://api.openai.com/v1
grok         ~/.grok/config.toml on 127.0.0.1:8788 → https://api.x.ai/v1
qwen-code    ~/.qwen/.env on 127.0.0.1:8789 → https://openrouter.ai/api/v1

aider
 (— = not supported · partial = partly · yes = supported)
 Command compaction partial → yes
 Web search partial → yes
 …
```

`status` liste chaque agent installé, son port et son fournisseur, et les fonctions que le proxy ajoute à ce que l'agent a déjà.

## Mise en place automatique

`tokenade install`, `tokenade upgrade` et la vérification quotidienne en arrière-plan installent le proxy d'eux-mêmes, mais seulement pour les agents où il apporte ce que l'agent ne peut pas obtenir autrement , comme Aider, Grok, Qwen Code, ou Codex tant que ses hooks ne sont pas approuvés. Partout ailleurs, il s'active à la main, agent par agent. Trois garde-fous s'appliquent :

- un agent déjà couvert par ses hooks n'est pas touché ;
- le proxy est démarré puis interrogé ; s'il ne répond pas, la configuration de l'agent est remise exactement comme avant ;
- `tokenade llm-proxy uninstall --agent <name>` est mémorisé (`~/.tokenade/llm-proxy-declined`) : la mise en place automatique ne revient jamais sur votre choix. Relancer `llm-proxy install` pour cet agent annule ce refus.

## Démarrage automatique

Une URL de base qui pointe vers un proxy arrêté fait échouer chaque tour : le proxy doit donc tourner dès que l'agent tourne. Avec `--autostart`, le proxy de chaque agent reçoit son propre service :

| Système | Service |
| --- | --- |
| Linux | Unité systemd utilisateur `~/.config/systemd/user/tokenade-llm-proxy*.service`. Lancez `loginctl enable-linger` pour qu'elle survive à un redémarrage sans ouverture de session |
| macOS | LaunchAgent (plist) dans `~/Library/LaunchAgents` |
| Windows | Tâche planifiée |

Tokenade affiche les commandes qui activent le service ; passez `--enable` pour qu'il les exécute. Il ne lance jamais `sudo` lui-même : toute commande qui demande des droits d'administrateur vous est affichée pour que vous la lanciez. Ajouter `--autostart` à un agent déjà installé conserve la configuration existante et ajoute l'entrée de démarrage.

## Codex est configuré automatiquement

Codex n'exécute que les hooks que vous avez approuvés dans Codex. `tokenade install` marque les hooks Codex de Tokenade comme approuvés (`tokenade codex-trust` le refait), et installe aussi le proxy LLM pour Codex, CLI et app de bureau, comme décrit plus haut. Tant que les hooks ne tournent pas réellement, le proxy assure la compaction, le masquage des identifiants, la note de style et les chiffres d'économies ; dès qu'ils tournent, le proxy sert surtout à mesurer, et ne replie que ce que les hooks n'ont pas touché. Codex reste connecté avec votre compte ChatGPT à travers le proxy.

## Ce que le proxy fait d'une requête

- Comprend les formats Anthropic Messages, OpenAI Chat et OpenAI Responses. Tout le reste est relayé octet pour octet.
- Replie les résultats d'outils de l'historique sortant avec le compacteur de leur commande, et remplace la répétition exacte d'un résultat précédent par un court renvoi.
- Masque les identifiants dans chaque résultat d'outil relayé, replié ou non.
- N'ajoute la note de [style](https://tokenade.net/fr/docs/style-statusline) qu'aux agents qui ne la reçoivent pas autrement.
- En cas d'erreur interne, relaie votre requête d'origine.
Les économies sont comptées une fois par bloc replié, au premier envoi, puis prudemment comme relectures évitées sur les requêtes suivantes. Voir [Comment les économies sont mesurées](https://tokenade.net/fr/docs/savings-measurement).

## Pièges

- Si le proxy est arrêté, les requêtes de l'agent échouent. Vérifiez `tokenade llm-proxy status`, démarrez le service, ou lancez `tokenade llm-proxy uninstall --agent <name>` pour revenir au point d'accès direct.
- Restez en boucle locale. `--remote` expose un processus qui détient la clé de votre fournisseur.
- Code de sortie `2` quand il n'y a rien à installer pour cet agent, ou que la configuration ne peut pas être préparée.

## Voir aussi

- [Envelopper les serveurs MCP](https://tokenade.net/fr/docs/mcp-wrap)
- [Codex (CLI et app)](https://tokenade.net/fr/docs/codex)
- [Comment les hooks interceptent les appels d'outils](https://tokenade.net/fr/docs/hooks)
- [Comment les économies sont mesurées](https://tokenade.net/fr/docs/savings-measurement)
