Info::IA::pcClaude: comment lancer claude sur une LLM locale

De wiki_pcwiki2
Aller à la navigationAller à la recherche

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 :

  1. 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 ;

  1. 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() ;

  1. envoie une requête GET /health en TCP brut vers

http://HOTE:PORT/health et attend un code 200 (timeout de 5 secondes) ;

  1. en cas d'échec, affiche un message d'erreur détaillé en rouge et

quitte avec le code 1, sans jamais lancer claude ;

  1. interroge GET /models sur 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 ;

  1. 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 ;

  1. 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 ;

  1. change le titre du terminal et affiche une bannière magenta

(SESSION LOCALE — ...) pour marquer visuellement l'entrée en mode local ;

  1. réserve la dernière ligne du terminal (région de défilement DECSTBM)

pour une barre de statut affichant "mesure en cours..." ;

  1. 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") ;

  1. 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) ;

  1. si un slot dépasse le seuil d'alerte, émet un bip terminal en plus

(suggestion /compact ou /clear), sans jamais interrompre la session ;

  1. attend la fin de la session claude, puis arrête

proprement le thread de surveillance ;

  1. à 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

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é ; indisponible si l'API ne répond pas.
  • Saisie : un numéro, un identifiant de section, h (HAL), o (OpenRouter).
  • Quitter : 0, q ou x.

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 /slots en Transfer-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-next instable 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.