Info::IA::pcClaude: comment lancer claude sur une LLM locale
KEYWORDS: PCCLAUDE, IA, LLM, CLAUDE
Le 151/09/2026: gpcClaude le 15/11/2026
pcClaude
Version : 1.05
Date : 25/09/2026
Rôle : vérifie qu'un serveur llama-server local
(routeur natif sur HAL, port 8090) répond bien, bascule ce routeur sur
le modèle demandé (défaut : gpt-oss-120b), puis lance une
session Claude Code redirigée vers ce backend local, avec un marquage
visuel clair (titre de terminal + bannière colorée) pour ne jamais
confondre cette session avec une session pointée sur l'API Anthropic
classique. Pendant la session, un thread de surveillance interroge
périodiquement l'occupation du contexte du modèle et l'affiche en
continu, dès le lancement, sur une barre de statut fixée en dernière
ligne du terminal (bip terminal en plus au franchissement du seuil
d'alerte).
Ne pas confondre avec pcIaRouter (application
graphique de supervision/pilotage manuel du même routeur, plusieurs
serveurs cibles possibles) : pcClaude ne fait que basculer
automatiquement, au lancement, sur un seul modèle prédéterminé
par --model, sans interface de supervision. Voir
ChaineIA-RAG.wiki pour la vue d'ensemble de toute la
chaîne IA (HAL, srv18, RAG).
Fonctionnement
Au lancement, pcClaude :
- affiche sa version et sa date de compilation
(PROJECT_VERSION/string(TIMESTAMP ...) dans
CMakeLists.txt, injectées via
PCCLAUDE_VERSION/PCCLAUDE_BUILD_DATE) —
volontairement la date de compilation plutôt que celle du dernier
commit git : reste correcte même sur un binaire copié hors du dépôt
(ex. /home/local/bin/pcClaude), sans dépendance à git à
l'exécution ;
- affiche le réseau emprunté pour joindre le serveur cible (LAN
domestique, Tailscale depuis un VPS distant ovh1/ovh2, ou personnalisé
si --host a été fourni) ainsi que l'adresse complète
utilisée (http://HOTE:PORT), avant toute autre étape —
voir ClassConfig::getNetworkLabel() ;
- envoie une requête
GET /healthen TCP brut vers
http://HOTE:PORT/health et attend un code 200
(timeout de 5 secondes) ;
- en cas d'échec, affiche un message d'erreur détaillé en rouge et
quitte avec le code 1, sans jamais lancer claude ;
- interroge
GET /modelssur le routeur natif
llama-server (fonctionnalité "Using multiple models" de
llama.cpp, même API que pcIaRouter), décharge tout modèle
actuellement chargé différent de celui demandé (POST
/models/unload), puis charge celui-ci (POST
/models/load, avec nouvelles tentatives toutes les 3 secondes en
cas d'échec transitoire "model limit reached", dans la limite de
--load-timeout) — sans effet si c'est déjà l'unique modèle
chargé ; relit ensuite GET /models pour découvrir le
ctx-size réel du modèle désormais chargé (champ
meta.n_ctx), à utiliser à la place de
--max-context ;
- en cas d'échec de cette bascule (routeur injoignable, hors mode
routeur natif, chargement en échec après nouvelles tentatives), affiche
un message d'erreur détaillé en rouge et quitte avec le code
1, sans jamais lancer claude ;
- en cas de succès, positionne
ANTHROPIC_BASE_URL,
ANTHROPIC_AUTH_TOKEN et CLAUDE_CODE_MAX_CONTEXT_TOKENS
(valeur découverte à l'étape précédente si disponible, sinon
--max-context) dans l'environnement, ainsi que toutes les
variables de choix de modèle de Claude Code, forcées sur le modèle
local : ANTHROPIC_MODEL,
ANTHROPIC_DEFAULT_FABLE_MODEL,
ANTHROPIC_DEFAULT_OPUS_MODEL,
ANTHROPIC_DEFAULT_SONNET_MODEL,
ANTHROPIC_DEFAULT_HAIKU_MODEL,
ANTHROPIC_SMALL_FAST_MODEL (obsolète) et
CLAUDE_CODE_SUBAGENT_MODEL ; ainsi aucun alias
(/model opus, sous-agent, tâche de fond) n'envoie un nom
de modèle Claude à llama-server. Les variables
ANTHROPIC_DEFAULT_{FABLE,OPUS,SONNET,HAIKU}_MODEL_NAME et
_DESCRIPTION renomment ces alias dans le sélecteur
/model (ex. gpt-oss-120b (alias opus)), pour
qu'aucune entrée ne laisse croire à un modèle Anthropic. Enfin,
ANTHROPIC_CUSTOM_MODEL_OPTION (avec _NAME =
<modèle> (local) et _DESCRIPTION)
ajoute le modèle local au sélecteur /model, pour pouvoir
y revenir après avoir choisi une autre entrée ;
- change le titre du terminal et affiche une bannière magenta
(SESSION LOCALE — ...) pour marquer visuellement l'entrée
en mode local ;
- réserve la dernière ligne du terminal (région de défilement DECSTBM)
pour une barre de statut affichant "mesure en cours..." ;
- lance
claude --model <NOM>en sous-processus, et démarre
en parallèle un thread qui interroge GET /slots?model=<NOM>
toutes les 20 secondes pour surveiller l'occupation du contexte du
modèle — le paramètre model est requis par le routeur
natif llama-server en mode "Using multiple models" (sans lui : erreur
400 "model name is missing from the request") ;
- après chaque sondage réussi, met à jour la barre de statut avec le
pourcentage courant (verte < 75 %, jaune 75-90 %, rouge ≥ 90 % par
défaut, seuils pilotés par --context-alert-threshold) ;
- si un slot dépasse le seuil d'alerte, émet un bip terminal en plus
(suggestion /compact ou /clear), sans jamais
interrompre la session ;
- attend la fin de la session
claude, puis arrête
proprement le thread de surveillance ;
- à la fin de la session, libère la dernière ligne du terminal, affiche
une bannière de sortie symétrique et restaure le titre du terminal à
terminal.
Le code de sortie de pcClaude est celui du sous-processus
claude (ou 127 si l'exécutable
claude est introuvable, ou 128+signal s'il a
été terminé par un signal).
Syntaxe
pcClaude [options]
Build
Paquets Debian requis :
apt install cmake g++ libboost-dev nlohmann-json3-dev
Compilation :
cmake -B build -S . cmake --build build
Le binaire est produit dans build/pcClaude.
Options
-h, --help
Affiche cette aide (fonctionnement, syntaxe, exemple par option) et quitte.
Exemple : pcClaude --help
--host <HOTE>
Hôte du serveur llama-server, déterminé automatiquement
selon la machine sur laquelle pcClaude s'exécute (nom
d'hôte local, via gethostname()) :
HAL(défaut sur le LAN domestique et ailleurs) —
résolu vers l'adresse privée de HAL (192.168.1.0/24) via
/etc/hosts ou le DNS local.
100.64.254.1— adresse tailscale stable de HAL,
utilisée automatiquement lorsque pcClaude détecte qu'il
tourne sur l'un des VPS distants ovh1 (hostname OS
mail.apsi.net) ou ovh2 (hostname OS
backup.apsi.net, vérifiés le 24/09/2026 via
hostname -f sur chaque VPS — ovh1/ovh2
ne sont que des noms tailscale, jamais renvoyés par
gethostname()). Depuis ces deux machines, la résolution
DNS de HAL aboutit d'ailleurs vers l'adresse privée
192.168.1.0/24, injoignable (le search domain pcstreet.org
est prioritaire sur ts.pcstreet.org dans
/etc/resolv.conf) — seule la voie tailscale explicite
fonctionne.
Reste surchargeable explicitement dans tous les cas via
--host.
Exemple : pcClaude --host 192.168.1.10
--port <PORT>
Port du serveur llama-server. Entier entre 1 et 65535.
Défaut : 8090.
Exemple : pcClaude --port 8091
--model <NOM>
Nom de modèle annoncé à Claude Code, et identifiant du modèle sur
lequel basculer le routeur natif llama-server avant de
lancer la session (voir Fonctionnement) — doit correspondre à un id du
catalogue GET /models du routeur (ex.
gpt-oss-120b, qwen3-coder-next). Défaut :
gpt-oss-120b — retenu pour sa fiabilité constatée dans le
harnais Claude Code (tool-calling agentique, format "harmony").
qwen3-coder-next (format peg-native/
deepseek côté llama-server) reste utilisable
via cette option, mais a provoqué des plantages reproductibles au
/compact lors de l'évaluation du 14/09/2026 — cause non
confirmée mais plausible : maturité moindre de ce format avec ce
harnais précis (voir Pièges).
Exemple : pcClaude --model qwen3-coder-next
--max-context <N>
Fenêtre de contexte en tokens, transmise via la variable
CLAUDE_CODE_MAX_CONTEXT_TOKENS — valeur de repli
uniquement : pcClaude découvre normalement le vrai
ctx-size configuré sur HAL pour le modèle chargé (champ
meta.n_ctx de GET /models, voir
Fonctionnement) et l'utilise à la place ; cette option ne sert que si
cette découverte échoue (ancien llama-server sans champ
meta). Entier strictement positif. Défaut :
131072 (fenêtre native de gpt-oss-120b).
Piège corrigé le 14/09/2026 : une première version de pcClaude
codait en dur 65536 comme fenêtre supposée de
qwen3-coder-next, alors que le ctx-size
réellement configuré sur HAL était 262144 — Claude Code
déclenchait alors un auto-compactage bien avant qu'il ne soit
nécessaire, y compris pour de petites demandes. La découverte
dynamique évite qu'un tel écart entre une valeur figée côté pcClaude
et la configuration réelle de HAL ne se reproduise.
Exemple : pcClaude --max-context 65536
--load-timeout <SECONDES>
Délai maximum accordé au routeur pour charger le modèle cible
(POST /models/load, voir Fonctionnement) — un gros modèle
peut prendre plusieurs dizaines de secondes, et des nouvelles tentatives
automatiques (toutes les 3 secondes) sont comprises dans ce budget.
Entier strictement positif. Défaut : 120.
Exemple : pcClaude --load-timeout 300
--context-alert-threshold <POURCENTAGE>
Seuil d'occupation du contexte (du slot llama-server le
plus chargé) au-delà duquel pcClaude alerte par un bip terminal
(suggestion /compact ou /clear) et à partir
duquel la barre de statut passe en rouge. Nombre dans
]0, 100]. Défaut : 75.
Exemple : pcClaude --context-alert-threshold 90
Menu de choix du fournisseur
Sans option de fournisseur, pcClaude affiche un menu (HAL, OpenRouter, puis les sections de ~/.config/pcClaude/providers.conf).
- Prix : lus en direct sur l'API OpenRouter (USD par million de tokens, entrée/sortie). Aucun prix de repli : un modèle introuvable au catalogue affiche
(prix inconnu). - Budget restant : minimum entre le solde du compte et le plafond de la clé ;
indisponiblesi l'API ne répond pas. - Saisie : un numéro, un identifiant de section,
h(HAL),o(OpenRouter). - Quitter :
0,qoux.
Clé OpenRouter
Ordre de recherche : variable d'environnement OPENROUTER_API_KEY (prioritaire), puis secret openrouter du coffre pcSecretd (libpcSecret, socket /run/pcvault.sock, root uniquement). Aucune clé n'est compilée dans le binaire (includes/Secrets.h n'est plus utilisé). Le coffre est lu à chaque lancement ; après ajout du secret, redémarrer pcSecretd. Au lancement, pcClaude affiche l'origine de la clé (« Clé d'API fournie par pcSecretd (secret "openrouter") » ou « fournie par la variable d'environnement … » ; en jaune si absente, clé factice dummy). gpcClaude affiche la même origine à côté du budget. La clé n'est jamais envoyée à un hôte autre qu'OpenRouter.
Pièges
- Bascule ovh1/ovh2 dépendante de tailscale : la détection du
défaut --host (voir option ci-dessus) se base uniquement
sur le nom d'hôte local (gethostname()), pas sur l'état
réel du réseau — si tailscale n'est pas up sur le VPS ou
que HAL est injoignable sur le tailnet, le GET /health
échoue normalement (voir Fonctionnement), mais le message d'erreur ne
mentionne pas explicitement une piste tailscale ; vérifier
tailscale status sur le VPS et sur HAL en cas d'échec
inattendu depuis ovh1/ovh2.
- Pas de dépendance libcurl : la vérification
/health
utilise une socket TCP brute (POSIX getaddrinfo/
connect/select), donc uniquement Linux/Debian.
- Titre de terminal : la séquence OSC 0 utilisée pour changer le
titre à l'entrée/sortie de session fonctionne sur la quasi-totalité des émulateurs modernes (xterm, gnome-terminal, konsole, iTerm2, Windows Terminal), mais peut être ignorée par un émulateur non conforme sans que ce soit une erreur. C'est aussi pour cette raison que le pourcentage de contexte n'est plus affiché via le titre depuis la 1.03 : Claude Code réécrit lui-même le titre en cours de session, ce qui rendait ce marquage invisible ou instable — d'où la barre de statut en dernière ligne du terminal, jamais touchée par Claude Code.
- Barre de statut (région de défilement DECSTBM) : la dernière
ligne du terminal est réservée via la séquence ESC[1;{rows-1}r
(technique utilisée notamment par tmux/screen pour leur ligne de
statut), restaurée à la sortie (ESC[r). Fonctionnalité
purement cosmétique et best-effort : désactivée automatiquement si la
sortie standard n'est pas un terminal (ex. redirection vers un fichier)
ou si la taille du terminal ne peut pas être obtenue ; redessinée
automatiquement sur redimensionnement (SIGWINCH). Un
sous-processus qui basculerait vers l'écran alternatif (ESC[?1049h,
rare pour un CLI comme Claude Code) réinitialiserait la région de
défilement à sa sortie, sans que pcClaude ne le détecte avant la
prochaine mesure (jusqu'à 20 secondes).
ANTHROPIC_AUTH_TOKEN=dummy: le token factice
n'est valide que parce que llama-server ne vérifie pas
l'authentification. Ne jamais réutiliser ce mécanisme avec l'API
Anthropic réelle.
- Annonce « Opus 5.5 is now your default model » : Claude Code
peut afficher ce message au démarrage même sous pcClaude. C'est une
annonce générique sur son modèle par défaut, sans effet ici : le modèle
réellement utilisé est celui indiqué dans la bannière de Claude Code
(ex. gpt-oss-120b with xhigh effort), et toutes les
variables de choix de modèle (alias fable/opus/sonnet/haiku, modèle
léger, sous-agents) sont forcées sur le modèle local (constaté le
25/09/2026 avec Claude Code 2.1.280). Si une version future de Claude
Code ajoute une famille de modèles, ajouter sa variable
ANTHROPIC_DEFAULT_*_MODEL au tableau de
ClassClaudeSessionLauncher::configureEnvironment().
- Occupation de contexte approximative : la surveillance se base
sur le champ n_prompt_tokens du slot llama-server
le plus chargé renvoyé par GET /slots. Si plusieurs
sessions partagent le même serveur (plusieurs slots actifs
simultanément), l'alerte peut se déclencher à cause d'une session
tierce, faute de moyen fiable de distinguer les slots par session via
cette API.
- Réponse
/slotsenTransfer-Encoding: chunked
sur HAL : volumineuse (tous les paramètres de sampling par slot),
contrairement à /models qui tient en
Content-Length. Le client HTTP maison de
ClassContextMonitor dé-chunk désormais le corps avant de
le parser (constaté et corrigé le 24/09/2026 — curl
masquait le problème car il dé-chunk automatiquement ; validé depuis
en session réelle, aussi bien en LAN qu'en Tailscale depuis un VPS
distant). Un serveur différent (mono-modèle, réponse plus petite) peut
ne jamais déclencher ce cas.
- Écriture concurrente sur le terminal : le thread de
surveillance et le sous-processus claude écrivent tous les
deux sur le même terminal (aucune redirection au fork()).
Le risque d'entrelacement est limité en pratique (séquences courtes,
une par mise à jour de la barre de statut ou par franchissement de
seuil), mais pas nul.
- Erreurs réseau ignorées : une panne temporaire de
llama-server pendant la session est journalisée une seule
fois sur stderr puis ignorée — la barre de statut conserve
la dernière valeur connue (mention "dernière mesure valide") et la
surveillance retente en arrière-plan sans jamais interrompre la session
claude en cours.
- Routeur HAL partagé : le port 8090 sert à la fois pcClaude et
d'autres consommateurs (ex. Open WebUI "IA PC" sur srv18, qui charge
gpt-oss-120b à la demande). Un lancement de pcClaude peut
donc décharger un modèle qu'un autre usage est en train d'utiliser, et
inversement une charge déclenchée ailleurs pendant la bascule de
pcClaude peut provoquer un échec transitoire "model limit
reached" sur POST /models/load (constaté en
conditions réelles le 14/09/2026) — les nouvelles tentatives
automatiques absorbent ce cas tant que la VRAM se libère dans le délai
--load-timeout. Aucun mécanisme ne protège un modèle
chargé par un autre usage contre un déchargement déclenché par
pcClaude.
qwen3-coder-nextinstable au/compact:
lors de l'évaluation du 14/09/2026, ce modèle a provoqué des plantages
reproductibles ("à chaque fois", selon retour utilisateur) au moment
où Claude Code déclenche un auto-compactage. Cause non confirmée : le
chat_format (peg-native) et le
reasoning_format (deepseek) utilisés côté
llama-server pour ce modèle diffèrent de ceux de
gpt-oss-120b (format "harmony", conçu spécifiquement pour
l'usage agentique avec outils) — hypothèse : compatibilité moindre
avec le format de requête interne que Claude Code génère pour un
compactage. D'où le retour à gpt-oss-120b comme modèle
par défaut. À ré-investiguer si qwen3-coder-next doit être
utilisé au quotidien : capturer la sortie de pcClaude
(pcClaude 2>&1 | tee ~/pcclaude.log) au moment du
plantage pour en avoir la trace exacte.
- Hors mode routeur natif : pointer
--host/
--port vers une instance llama-server
lancée directement avec un seul modèle (ex. le serveur FIM HAL:8012, ou
un ancien déploiement pré-routeur) fait échouer la bascule (pas de
GET /models avec un champ data) et donc tout
le lancement de pcClaude, y compris si /health répond —
ces cibles ne sont pas utilisables avec pcClaude en l'état.