Aller au contenu

Interface des sous-agents (v1 / base / v2)

Un sous-agent est un travailleur Codex distinct que l’agent principal peut créer pour une tâche ciblée. Il possède son propre contexte et ses propres outils, afin que plusieurs tâches indépendantes puissent s’exécuter en parallèle. opencodex contrôle quelle surface de collaboration Codex expose ces travailleurs, quels modèles Codex leur propose et comment un modèle défaillant peut reculer. Il ne décide pas quand votre agent principal doit déléguer.

Choisissez le mode pour les nouvelles sessions. Les sessions existantes conservent la surface avec laquelle elles ont commencé.

Mode Ce que Codex obtient Qui devrait le choisir
v1 Outils classiques avec espace de noms spawn_agent, send_input, resume_agent et close_agent. Un spawn peut sélectionner directement un autre modèle. Les débutants qui ont besoin d’une délégation fiable entre différents fournisseurs, en particulier les enfants natifs vers routés.
base (par défaut) Paramètres de modèle en amont : GPT-5.6 Sol/Terra utilisent la v2, Luna utilise la v1, et les modèles non définis explicitement suivent l’indicateur de fonctionnalité multi_agent_v2 de Codex. La plupart des utilisateurs. Ce mode respecte la surface prévue par Codex pour chaque modèle, sans en imposer une globalement.
v2 Outils plats spawn_agent, send_message, followup_task, interrupt_agent et liste d’agents, avec sessions simultanées. Utilisateurs souhaitant utiliser le flux de travail simultané le plus récent et comprenant l’héritage de modèle et la limitation des tâches chiffrées ci-dessous.

En v2, l’option facultative Garder ChatGPT sur v1 (keepNativeChatGptOnV1) laisse Sol/Terra sur la surface v1 afin qu’ils puissent encore lancer Grok ou Claude. Les parents natifs ChatGPT chiffrent les corps NEW_TASK v2 ; les modèles routés ne peuvent pas les lire. Les parents routés restent sur v2, où les tâches enfants sont en texte clair. C’est un interrupteur à l’intérieur de v2, pas un quatrième mode de catalogue. CLI : ocx v2 mode v2 puis ocx v2 keep-native-v1 on.

Le mode sélectionné contrôle le champ multi_agent_version dans chaque entrée de catalogue Codex lit :

  • v1 inscrit multi_agent_version = "v1" sur chaque modèle.
  • base restaure les paramètres en amont. Les entrées sans valeur explicite suivent l’indicateur de fonctionnalité natif multi_agent_v2.
  • v2 inscrit multi_agent_version = "v2" sur chaque modèle, sauf lorsque Garder ChatGPT sur v1 est activé : les lignes natives ChatGPT restent "v1" et les lignes routées ou combo restent "v2".

opencodex applique cela comme passe finale à la fois au catalogue /v1/models en direct et au catalogue synchronisé sur le disque. C’est pourquoi un changement de mode affecte de manière cohérente les sessions App, CLI et TUI nouvellement créées.

Pour une liste v2, l’éligibilité a trois états : une entrée estampillée "v2", explicitement définie sur null, ou sans champ multi_agent_version est admissible. Une valeur explicite "v1" est exclue, car elle indique que le modèle appartient à l’autre surface de collaboration.

Codex liste au plus cinq modèles dans la description de l’outil spawn_agent, et il les choisit lui-même : il trie les lignes du catalogue visibles dans le sélecteur par priority croissante et garde les cinq premières. La liste de la page Subagents (subagentModels) n’agit sur cette sélection qu’en donnant à ses modèles les priorités les plus basses, dans l’ordre de la liste (0 à 4 sans sélecteurs de compte). Elle ne limite pas la sélection à ces modèles.

Si vous mettez en avant un à quatre modèles, Codex complète les emplacements restants avec les lignes suivantes par priorité. Vous n’avez pas choisi ces lignes, et le tableau de bord n’indique pas lesquelles sont retenues. Elles dépendent du catalogue :

Catalogue Lignes qui complètent les emplacements restants
Sans sélecteurs de compte Codex Les autres lignes routées provider/model. Elles partagent toutes la priorité 5 et apparaissent donc par nom de fournisseur, puis par identifiant de modèle, dans l’ordre alphabétique. Les lignes GPT natives non mises en avant ont une priorité d’au moins 100 plus le nombre d’identifiants mis en avant ; elles viennent donc après.
Avec sélecteurs de compte Codex Les lignes natives qualifiées par compte (<selector>/<native-model>), placées juste après les lignes mises en avant. Les lignes routées non mises en avant passent à la priorité 1005 et viennent après elles.

Par exemple, sans sélecteurs de compte et avec cette liste :

{ "subagentModels": ["xai/grok-4.5", "anthropic/claude-sonnet-5"] }
Emplacement Modèle Priorité Raison
1 xai/grok-4.5 0 Première entrée de la liste
2 anthropic/claude-sonnet-5 1 Deuxième entrée de la liste
3 deepseek/deepseek-v4-flash 5 Première ligne routée restante dans l’ordre alphabétique
4 google/gemini-3-pro 5 Ligne routée suivante
5 moonshot/kimi-k3 5 Ligne routée suivante
6+ zai/glm-5.2, puis les lignes GPT natives 5, puis 102 + sourcePriority Hors des cinq

Avec une liste vide, opencodex ne fixe aucune priorité et les cinq suivent les priorités normales du catalogue.

Les emplacements complétés sont des annonces ordinaires : l’agent principal peut choisir l’un de ces modèles. La liste n’est pas non plus une liste d’autorisation : Codex accepte un modèle du catalogue hors des cinq lorsque l’agent principal le nomme exactement. Pour contrôler ce que Codex annonce :

  • Mettez cinq modèles en avant. Une liste complète ne laisse aucun emplacement à compléter.
  • Désactivez un modèle que vous ne voulez jamais voir proposé, ou retirez-le des selectedModels de son fournisseur. Un modèle désactivé ou non sélectionné quitte le sélecteur et ne peut pas compléter un emplacement.
  • modelPickerOrder modifie les priorités que Codex utilise pour trier. Une liste uniquement routée déplace les lignes listées non mises en avant à 1000 et au-delà ; les lignes routées non listées complètent donc les emplacements en premier. Une liste qui contient un identifiant natif nu ordonne tout le sélecteur, lignes mises en avant comprises : les lignes listées passent en premier et occupent les emplacements annoncés avant toute ligne non listée. Voir Model ordering.

En v2, Codex écarte les lignes épinglées "disabled" avant de prendre les cinq ; le reste fonctionne de la même façon. La liste des consignes v2 d’opencodex ({{roster}}) ne nomme que les modèles configurés présents parmi les cinq : les modèles de complément apparaissent dans la description de l’outil Codex, jamais dans les consignes d’opencodex. Codex lit le catalogue au démarrage d’une session ; une modification de la liste s’applique donc aux nouvelles sessions.

La délégation de sous-agent du tableau de bord contrôle trois paramètres associés :

  • injectionModel est le modèle de travailleur préféré nommé dans le guide opencodex.
  • injectionEffort est le reasoning_effort optionnel à demander pour ce modèle.
  • injectionPrompt remplace le texte d’orientation intégré de la v2.

multiAgentGuidanceEnabled est activé par défaut et constitue le réglage principal des directives produites par opencodex sur les deux surfaces. Sa désactivation supprime à la fois le bloc de désignation v2 et le texte proactif v1.

Pour les requêtes Responses sans état dont l’entrée est un tableau, opencodex place les instructions générées après les premières métadonnées système et développeur, y compris additional_tools côté développeur, et avant l’entrée conversationnelle. Les continuations avec état utilisant previous_response_id ne réutilisent les directives balisées que si elles correspondent au dernier élément balisé de leur préfixe de relecture fiable. Les autres directives générées sont réutilisées lorsqu’un élément développeur généré à l’identique figure dans ce préfixe. Lorsque les directives changent, le protocole de l’outil principal reste en première position et les nouvelles directives sont insérées avant l’entrée conversationnelle actuelle.

Ce sont des instructions destinées à l’agent principal, et non à un routeur de génération côté proxy. Sur la v2, un fork avec historique complet hérite du modèle parent et rejette les remplacements de modèle ou d’effort. Le guidage indique donc à Codex de utilisez fork_turns: "none" (ou un compte de tour partiel positif tel que "3") lorsque vous dépassez model ou reasoning_effort, et de rendre le message de tâche autonome.

Le texte personnalisé de injectionPrompt peut utiliser les quatre espaces réservés suivants :

Espace réservé Remplacé par
{{model}} Le modèle préféré effectif pour cette requête. Un injectionModel natif non qualifié n’est qualifié par un compte que si la requête cible elle-même un sélecteur de compte explicite. Une valeur non qualifiée, non résolue ou ambiguë devient une chaîne vide ; un identifiant explicite qualifié par un compte ou un routage, même non résolu, reste inchangé
{{effort}} Le injectionEffort configuré, ou une chaîne vide
{{roster}} La liste résolue, visible par le sélecteur et compatible avec la surface
{{fallback}} Les conseils de repli globaux configurés

Le guide v2 intégré dispose d’un budget de 700 caractères. S’il devait dépasser ce budget, opencodex réduit la liste d’abord plutôt que de tronquer les instructions d’apparition principales. Le guidage intégré déclenche uniquement lorsqu’un modèle préféré, une liste éligible ou une chaîne de secours est résolu. Un injectionModel configuré est suffisant pour afficher une invite personnalisée ; si une valeur non qualifiée ne peut pas être résolue de manière unique, {{model}} se développe en une chaîne vide.

Sur la v1, opencodex injecte le même texte de délégation proactive que le préréglage recommandé de la v2, uniquement aux niveaux d’effort max ou ultra. Seule la condition de déclenchement change : aucune demande de délégation distincte n’est nécessaire ; les instructions de l’utilisateur, les autorisations, le périmètre de la tâche et les règles des outils de collaboration restent applicables. Il n’ajoute aucun modèle préféré, aucune liste, aucune chaîne de repli ni aucune invite personnalisée en v1.

L’option syncCodexSubagentDefaults désactivée par défaut est distincte du guidage. Quand opencodex possède le routage Codex actif, la synchronisation ou le redémarrage peut écrire les valeurs sélectionnées en tant que propriété du marqueur entrées [agents] default_subagent_model et default_subagent_reasoning_effort dans Codex TOML. opencodex met à jour ou supprime uniquement les champs portant ses marqueurs. Si l’un des champs cibles appartient à l’utilisateur, la paire reste inchangée plutôt que partiellement écrite ; ambigu TOML est rejeté sans un écriture. Les gestionnaires de fournisseurs externes et le routage racine appartenant à l’utilisateur conservent également leur autorité.

Pour un travailleur généré, opencodex construit cet ordre de priorité :

  1. Le modèle primaire demandé.
  2. Une chaîne par modèle de subagentModelFallbackByModel dans opencodex config, saisie par le modèle primaire demandé.
  3. La liste subagentModelFallback globale dans opencodex config.

Les chaînes de secours par rôle appartiennent à opencodex config, pas à $CODEX_HOME/agents/*.toml. Codex 0.146+ désérialise strictement les fichiers de rôles d’agent et rejette model_fallback comme champ inconnu, ce qui ignore toute la définition du rôle (#1190). opencodex peut toujours lire une ligne model_fallback héritée du TOML pour compatibilité ascendante, mais ocx doctor en avertit et Codex lui-même ignorera le rôle concerné.

Les identifiants de modèle en double sont supprimés tout en préservant la première occurrence. Lors de la sélection, opencodex ignore les candidats désactivés, non routables, soutenus par un fournisseur désactivé, marqués en mauvais état, pendant un temps de recharge, il manque un compte Codex poolé utilisable ou au-delà du seuil de quota configuré. Les sondes de disponibilité sont mises en cache pendant subagentModelFallbackPollMs (60 secondes par défaut).

La solution de secours ne rend pas lisibles les tâches chiffrées incompatibles. Lorsque la tâche enfant est chiffrée pour ChatGPT, la sélection est restreinte aux cibles ChatGPT natives canoniques et aux routes Responses directes avec authentification par clé explicitement approuvées via allowEncryptedV2AgentTasks: true, même si un autre modèle externe apparaît plus tôt dans la chaîne. Les combos restent limités aux cibles natives canoniques.

Codex peut envoyer une tâche enfant v2 native vers routé uniquement sous forme encrypted_content chiffrée par le backend. Cette charge utile peut être lue par le backend natif ChatGPT, mais pas par un fournisseur externe. C’est la limitation connue #92.

opencodex échoue en toute sécurité au lieu de transférer une tâche vide ou illisible :

  • Une route directe non native inéligible renvoie HTTP 400 avec error.code = "unreadable_encrypted_agent_task" et ne fait pas écho au texte chiffré. Un fournisseur Responses direct à authentification par clé qui active explicitement allowEncryptedV2AgentTasks: true reçoit à la place le texte chiffré opaque et évite cette erreur.
  • Un combo considère uniquement les cibles ChatGPT natives canoniques pour cette tâche, y compris les tentatives. Si aucun est disponible, il renvoie la même erreur 400.
  • Une tâche lisible en texte clair conserve la route normale et le comportement de repli.

Les options de récupération consistent à sélectionner un enfant ChatGPT natif, à approuver explicitement un relais Responses direct à authentification par clé capable de consommer la charge utile opaque, à ajouter une cible ChatGPT native au combo, à utiliser v1 pour la délégation de fournisseurs hétérogènes, ou à renvoyer la tâche comme contenu agent_message v2 en texte brut lorsque vous contrôlez l’appelant.

L’option expérimentale agentTaskRecovery, désactivée par défaut, peut récupérer cette forme précise de tâche native envoyée vers une route externe. Elle utilise un transfert Responses brut vers le point de terminaison ChatGPT /responses fixe et la forme d’identification entrante du fournisseur canonique openai configuré avec authMode: "forward".

Cette récupération est disponible uniquement lorsque le proxy écoute sur l’interface de bouclage. Elle ne substitue jamais une autre clé API, l’identifiant d’un autre fournisseur ou un autre compte Codex. Seuls les en-têtes authorization, chatgpt-account-id correspondant, originator, ainsi que les métadonnées facultatives openai-beta et user-agent, sont transmis. content-type et accept sont générés localement ; aucun autre en-tête de l’appelant ne franchit cette frontière.

Cette opération consomme du quota, ajoute de la latence, conserve brièvement le texte récupéré dans un cache mémoire borné et dépend d’un comportement non documenté du service ChatGPT. Comme un modèle renvoie le texte récupéré, la fidélité octet par octet n’est pas garantie. Les appelants génériques ou authentifiés par clé API sont rejetés, et tout échec conserve l’erreur unreadable_encrypted_agent_task. Consultez Configuration de l’agent : récupération de tâche chiffrée v2 pour la limite de confiance complète et la configuration. Le routage des combinaisons reste inchangé et continue de considérer uniquement les cibles ChatGPT natives canoniques pour les tâches chiffrées.

  • Tableau de bord → première cellule statistique : choisissez v1, base ou v2.
  • Modèles → contrôle segmenté de la rangée supérieure : choisissez le même mode global.
  • Modèles → Garder ChatGPT sur v1 : activez cette option uniquement lorsque le mode global est v2. Elle est ignorée en v1 et base.
  • Tableau de bord → Délégation de sous-agent : définissez les conseils model/effort et l’activation explicite natif par défaut.
  • Sous-agents : choisissez et ordonnez la liste, puis configurez la chaîne de repli globale.

Utilisez ocx v2 pour les paramètres de la surface de collaboration et des fonctionnalités natives :

Terminal window
ocx v2 status
ocx v2 mode v1
ocx v2 mode default
ocx v2 mode v2
ocx v2 keep-native-v1 on
ocx v2 keep-native-v1 off
ocx v2 threads 8

Utilisez ocx agent pour les paramètres de délégation, de liste, de plafond d’effort et de secours :

Terminal window
ocx agent status
ocx agent injection set --model anthropic/claude-sonnet-5 --effort xhigh
ocx agent subagents set gpt-5.6-sol,anthropic/claude-sonnet-5
ocx agent fallback set gpt-5.6-luna,xai/grok-4.5 --poll-ms 60000
ocx agent effort set --subagent max

Passez - pour effacer une valeur ocx agent injection nullable, ou utilisez l’action clear appropriée pour un liste ou chaîne de repli. Consultez la référence CLI pour toutes les familles de commandes.

La gestion API expose les points de terminaison correspondants GET et PUT :

Point de terminaison Gère
/api/v2 Mode Surface, indicateur de fonctionnalité native et paramètres de thread
/api/injection-model Modèle préféré, effort, invite personnalisée, conseils et synchronisation native par défaut
/api/effort-caps Plafonds d’effort des agents principaux et des sous-agents
/api/subagent-models Liste commandée de cinq modèles maximum
/api/subagent-model-fallback Ordre de repli global et intervalle d’interrogation

Par exemple :

Terminal window
curl -X PUT http://localhost:10100/api/v2 \
-H 'Content-Type: application/json' \
-d '{"multiAgentMode":"v2"}'
curl -X PUT http://localhost:10100/api/injection-model \
-H 'Content-Type: application/json' \
-d '{"model":"anthropic/claude-sonnet-5","effort":"xhigh"}'

Le choix d’un modèle de délégation oblige-t-il Codex à le générer ?

Section intitulée « Le choix d’un modèle de délégation oblige-t-il Codex à le générer ? »

Non. Les directives peuvent recommander un modèle et la synchronisation native des valeurs par défaut peut fournir une valeur par défaut à Codex, mais l’agent principal décide toujours s’il doit déléguer.

Pourquoi mon enfant v2 a-t-il utilisé le modèle parent ?

Section intitulée « Pourquoi mon enfant v2 a-t-il utilisé le modèle parent ? »

Un fork v2 à historique complet hérite du modèle parent. Utilisez un spawn qui définit fork_turns sur "none" ou un décompte partiel positif avant de passer un dépassement de modèle ou d’effort.

Pourquoi un modèle configuré manque-t-il dans la liste v2 ?

Section intitulée « Pourquoi un modèle configuré manque-t-il dans la liste v2 ? »

Il peut être masqué par le sélecteur, en dehors de la limite d’affichage de cinq modèles, absent du catalogue ou épinglé à la v1. Une valeur de surface "v2", null ou absente est admissible ; une valeur explicite "v1" ne l’est pas.

Pourquoi spawn_agent liste-t-il des modèles que je n’ai pas mis en avant ?

Section intitulée « Pourquoi spawn_agent liste-t-il des modèles que je n’ai pas mis en avant ? »

Codex remplit jusqu’à cinq emplacements annoncés à partir du catalogue, par priorité. Avec moins de cinq modèles mis en avant, les lignes suivantes occupent les emplacements restants ; voir la section « Modèles annoncés par spawn_agent » ci-dessus.

Les changements de mode affectent-ils les sessions en cours ?

Section intitulée « Les changements de mode affectent-ils les sessions en cours ? »

Non. Démarrez une nouvelle session Codex après avoir changé de mode. Si un hôte App de longue durée affiche toujours des informations obsolètes état du catalogue, exécutez ocx sync et redémarrez cette surface Codex.

Que se passe-t-il lorsqu’opencodex ne peut pas considérer le catalogue comme fiable ?

Section intitulée « Que se passe-t-il lorsqu’opencodex ne peut pas considérer le catalogue comme fiable ? »

opencodex compare le catalogue de modèles sur disque à l’heure de démarrage de chaque Codex serveur d’applications détenu par l’utilisateur actuel, produisant l’un des quatre états suivants :

État Signification conseils v2
fresh Chaque serveur d’applications a démarré après la rédaction du catalogue Conseils complets : modèle préféré, liste, solutions de secours
not_running Aucun serveur d’application détecté Conseils complets
stale Au moins un serveur d’applications est antérieur au catalogue Aucune directive sur le modèle rédigé par opencodex
unknown La comparaison n’a pas pu être faite Aucune directive sur le modèle rédigé par opencodex

Pour stale et unknown, opencodex omet ses propres indications dérivées du disque — modèle préféré, liste, secours et conseils personnalisés - car le Codex en cours d’exécution peut ne pas être en mesure de générer ce que le disque catalogue annonce.

Il ne demande pas au modèle d’arrêter le réglage model ou reasoning_effort. Cette observation est global sur chaque serveur d’applications pour l’utilisateur, alors qu’une requête entrante ne porte aucune identité d’expéditeur, donc un processus obsolète ne peut pas être attribué à la demande dont nous sommes saisis. Interdire les dérogations à ce sujet base bloquerait les options que l’outil actif spawn_agent annonce légitimement, pour une session qui peut très bien être à jour. Le schéma de l’outil actif reste la référence.

unknown n’est pas synonyme de stale. Cela signifie que la comparaison elle-même a échoué – un catalogue illisible horodatage, une heure de début de processus illisible ou une énumération de processus ayant échoué - et cela est signalé séparément par ocx doctor. stale s’efface uniquement après chaque démarrage du serveur d’applications Codex détecté après la rédaction du catalogue final ; cela n’efface pas nécessairement unknown.

Seul un vrai changement compte. Une synchronisation dont le résultat est identique en octets au catalogue déjà sur le disque laisse le fichier intact, donc le redémarrage du proxy ou la resynchronisation d’un ensemble de modèles inchangé ne le fait pas donner un aspect obsolète à un Codex en cours d’exécution.

injectionEffort affecte uniquement le guidage des travailleurs délégués et, lorsqu’il est explicitement activé, le Codex natif valeurs par défaut du sous-agent. Cela ne change pas l’effort de la session parent. ultra est un haut orienté client niveau que Codex convertit en max ; opencodex mappe ou bloque ensuite la valeur du fournisseur sélectionné.

La limite de contexte du modèle est indépendante du mode sous-agent. Configurez-le sur la page Modèles ; natif OpenAI les modèles conservent leurs fenêtres de contexte réelles.