Référence du harnais Codex

Cette référence couvre la configuration détaillée du Plugin codex intégré. Pour la configuration initiale et les décisions de routage, commencez par Codex harness.

Surface de configuration du Plugin

Tous les paramètres Codex harness se trouvent sous plugins.entries.codex.config.

{  plugins: {    entries: {      codex: {        enabled: true,        config: {          discovery: {            enabled: true,            timeoutMs: 2500,          },          appServer: {            mode: "guardian",          },        },      },    },  },}

Champs de premier niveau pris en charge :

Transport app-server

Par défaut, OmeniaClaw démarre le binaire Codex géré fourni avec le Plugin intégré :

codex app-server --listen stdio://

Cela maintient la version de l’app-server liée au Plugin codex intégré plutôt qu’à la CLI Codex séparée qui se trouve être installée localement. Définissez appServer.command uniquement lorsque vous voulez intentionnellement exécuter un exécutable différent.

Pour un app-server déjà en cours d’exécution, utilisez le transport WebSocket :

{  plugins: {    entries: {      codex: {        enabled: true,        config: {          appServer: {            transport: "websocket",            url: "ws://gateway-host:39175",            authToken: "${CODEX_APP_SERVER_TOKEN}",            requestTimeoutMs: 60000,          },        },      },    },  },}

Champs appServer pris en charge :

Le Plugin bloque les handshakes app-server plus anciens ou sans version. Codex app-server doit signaler la version stable 0.125.0 ou une version plus récente.

Modes d’approbation et sandbox

Les sessions app-server stdio locales utilisent par défaut le mode YOLO : approvalPolicy: "never", approvalsReviewer: "user" et sandbox: "danger-full-access". Cette posture d’opérateur local de confiance permet aux tours OmeniaClaw sans surveillance et aux Heartbeats de progresser sans invites d’approbation natives auxquelles personne n’est présent pour répondre.

Si le fichier d’exigences système local de Codex interdit les valeurs implicites YOLO d’approbation, de relecteur ou de sandbox, OmeniaClaw traite plutôt la valeur implicite par défaut comme guardian et sélectionne les permissions guardian autorisées. Les entrées [[remote_sandbox_config]] correspondant au nom d’hôte dans le même fichier d’exigences sont respectées pour la décision par défaut du sandbox.

Définissez appServer.mode: "guardian" pour les approbations Codex relues par guardian :

{  plugins: {    entries: {      codex: {        enabled: true,        config: {          appServer: {            mode: "guardian",            serviceTier: "priority",          },        },      },    },  },}

Le préréglage guardian s’étend en approvalPolicy: "on-request", approvalsReviewer: "auto_review" et sandbox: "workspace-write" lorsque ces valeurs sont autorisées. Les champs de politique individuels remplacent mode. L’ancienne valeur de relecteur guardian_subagent est toujours acceptée comme alias de compatibilité, mais les nouvelles configurations devraient utiliser auto_review.

Authentification et isolation de l’environnement

L’authentification est sélectionnée dans cet ordre :

1. Un profil d’authentification OmeniaClaw Codex explicite pour l’agent.
2. Le compte existant de l’app-server dans le dossier d’accueil Codex de cet agent.
3. Pour les lancements app-server stdio locaux uniquement, CODEX_API_KEY, puis OPENAI_API_KEY, lorsqu’aucun compte app-server n’est présent et que l’authentification OpenAI est encore requise.

Lorsqu’OmeniaClaw détecte un profil d’authentification Codex de type abonnement ChatGPT, il supprime CODEX_API_KEY et OPENAI_API_KEY du processus enfant Codex lancé. Cela maintient les clés API de niveau Gateway disponibles pour les embeddings ou les modèles OpenAI directs sans faire facturer accidentellement les tours Codex app-server natifs via l’API.

Les profils explicites de clé API Codex et le repli local stdio par clé d’environnement utilisent la connexion app-server au lieu de l’environnement hérité du processus enfant. Les connexions WebSocket app-server ne reçoivent pas de repli par clé API d’environnement Gateway ; utilisez un profil d’authentification explicite ou le compte propre de l’app-server distant.

Les lancements app-server stdio héritent par défaut de l’environnement du processus OmeniaClaw, mais OmeniaClaw possède le pont de compte Codex app-server et définit à la fois CODEX_HOME et HOME sur des répertoires par agent sous l’état OmeniaClaw de cet agent. Le chargeur de Skills propre à Codex lit $CODEX_HOME/skills et $HOME/.agents/skills, de sorte que les deux valeurs sont isolées pour les lancements app-server locaux. Cela maintient les Skills, plugins, configurations, comptes et états de fil natifs Codex limités à l’agent OmeniaClaw au lieu de fuir depuis le dossier d’accueil personnel Codex CLI de l’opérateur.

Les plugins OmeniaClaw et les instantanés de Skills OmeniaClaw continuent de passer par le propre registre de plugins et le chargeur de Skills d’OmeniaClaw. Les ressources personnelles Codex CLI ne le font pas. Si vous avez des Skills ou plugins Codex CLI utiles qui devraient faire partie d’un agent OmeniaClaw, inventoriez-les explicitement :

OmeniaClaw migrate codex --dry-runOmeniaClaw migrate apply codex --yes

Si un déploiement nécessite une isolation d’environnement supplémentaire, ajoutez ces variables à appServer.clearEnv :

{  plugins: {    entries: {      codex: {        enabled: true,        config: {          appServer: {            clearEnv: ["CODEX_API_KEY", "OPENAI_API_KEY"],          },        },      },    },  },}

appServer.clearEnv n’affecte que le processus enfant Codex app-server lancé. CODEX_HOME et HOME restent réservés à l’isolation Codex par agent d’OmeniaClaw lors des lancements locaux.

Outils dynamiques

Les outils dynamiques Codex utilisent par défaut le chargement searchable. OmeniaClaw n’expose pas les outils dynamiques qui dupliquent les opérations d’espace de travail natives Codex :

• read
• write
• edit
• apply_patch
• exec
• process
• update_plan

Les autres outils d’intégration OmeniaClaw, comme la messagerie, les sessions, les médias, cron, le navigateur, les nœuds, le Gateway, heartbeat_respond et web_search, sont disponibles via la recherche d’outils Codex sous l’espace de noms OmeniaClaw. Cela réduit le contexte initial du modèle. sessions_yield et les réponses de source uniquement via outil de message restent directes, car ce sont des contrats de contrôle du tour.

Définissez codexDynamicToolsLoading: "direct" uniquement lors de la connexion à un app-server Codex personnalisé qui ne peut pas rechercher les outils dynamiques différés, ou lors du débogage de la charge utile complète des outils.

Délais d’expiration

Les appels d’outils dynamiques appartenant à OmeniaClaw sont limités indépendamment de appServer.requestTimeoutMs. Chaque requête Codex item/tool/call utilise le premier délai disponible dans cet ordre :

• Un argument timeoutMs positif propre à l’appel.
• Pour image_generate, agents.defaults.imageGenerationModel.timeoutMs.
• Pour l’outil image de compréhension des médias, tools.media.image.timeoutSeconds converti en millisecondes, ou la valeur par défaut média de 60 secondes.
• La valeur par défaut des outils dynamiques de 30 secondes.

Les budgets des outils dynamiques sont plafonnés à 600000 ms. En cas d’expiration, OmeniaClaw annule le signal de l’outil lorsque c’est pris en charge et renvoie à Codex une réponse d’outil dynamique en échec afin que le tour puisse continuer au lieu de laisser la session en processing.

Après qu’OmeniaClaw répond à une requête app-server Codex à portée de tour, le harness s’attend aussi à ce que Codex termine le tour natif avec turn/completed. Si l’ app-server reste silencieux pendant appServer.turnCompletionIdleTimeoutMs après cette réponse, OmeniaClaw interrompt au mieux le tour Codex, enregistre un diagnostic d’expiration et libère la voie de session OmeniaClaw afin que les messages de chat suivants ne soient pas mis en file derrière un tour natif obsolète.

Toute notification non terminale pour le même tour, y compris rawResponseItem/completed, désactive ce court watchdog, car Codex a prouvé que le tour est toujours actif. Le watchdog terminal plus long continue de protéger les tours réellement bloqués. Les diagnostics d’expiration incluent la dernière méthode de notification de l’ app-server et, pour les éléments bruts de réponse assistant, le type d’élément, le rôle, l’id et un aperçu borné du texte de l’assistant.

Découverte des modèles

Par défaut, le Plugin Codex demande à l’app-server les modèles disponibles. La disponibilité des modèles appartient à l’app-server Codex ; la liste peut donc changer quand OmeniaClaw met à niveau la version @openai/codex intégrée, ou lorsqu’un déploiement pointe appServer.command vers un binaire Codex différent. La disponibilité peut aussi être propre au compte. Utilisez /codex models sur un gateway en cours d’exécution pour voir le catalogue actif de ce harness et de ce compte.

Si la découverte échoue ou expire, OmeniaClaw utilise un catalogue de repli intégré pour :

• GPT-5.5
• GPT-5.4 mini
• GPT-5.2

Le harness intégré actuel est @openai/codex 0.130.0. Une sonde model/list contre cet app-server intégré a renvoyé :

Les modèles masqués peuvent être renvoyés par le catalogue de l’app-server pour des flux internes ou spécialisés, mais ce ne sont pas des choix normaux dans le sélecteur de modèles.

Ajustez la découverte sous plugins.entries.codex.config.discovery :

{  plugins: {    entries: {      codex: {        enabled: true,        config: {          discovery: {            enabled: true,            timeoutMs: 2500,          },        },      },    },  },}

Désactivez la découverte lorsque vous voulez que le démarrage évite de sonder Codex et utilise uniquement le catalogue de repli :

{  plugins: {    entries: {      codex: {        enabled: true,        config: {          discovery: {            enabled: false,          },        },      },    },  },}

Fichiers d’amorçage de l’espace de travail

Codex gère lui-même AGENTS.md via la découverte native des documents de projet. OmeniaClaw n’écrit pas de fichiers de documents de projet Codex synthétiques et ne dépend pas des noms de fichiers de repli Codex pour les fichiers de persona, car les replis Codex ne s’appliquent que lorsque AGENTS.md est absent.

Pour la parité de l’espace de travail OmeniaClaw, le harness Codex résout les autres fichiers d’amorçage, notamment SOUL.md, TOOLS.md, IDENTITY.md, USER.md, HEARTBEAT.md, BOOTSTRAP.md et MEMORY.md lorsqu’ils sont présents, et les transmet via les instructions développeur Codex sur thread/start et thread/resume. Cela garde le contexte de persona et de profil de l’espace de travail visible sur la voie native Codex qui façonne le comportement, sans dupliquer AGENTS.md.

Remplacements d’environnement

Les remplacements d’environnement restent disponibles pour les tests locaux :

• OmeniaClaw_CODEX_APP_SERVER_BIN
• OmeniaClaw_CODEX_APP_SERVER_ARGS
• OmeniaClaw_CODEX_APP_SERVER_MODE=yolo|guardian
• OmeniaClaw_CODEX_APP_SERVER_APPROVAL_POLICY
• OmeniaClaw_CODEX_APP_SERVER_SANDBOX

OmeniaClaw_CODEX_APP_SERVER_BIN contourne le binaire géré lorsque appServer.command n’est pas défini.

OmeniaClaw_CODEX_APP_SERVER_GUARDIAN=1 a été supprimé. Utilisez plugins.entries.codex.config.appServer.mode: "guardian" à la place, ou OmeniaClaw_CODEX_APP_SERVER_MODE=guardian pour des tests locaux ponctuels. La configuration est préférable pour les déploiements reproductibles, car elle conserve le comportement du Plugin dans le même fichier relu que le reste de la configuration du harness Codex.

Associé

• Harness Codex
• Runtime du harness Codex
• Plugins Codex natifs
• Codex Computer Use
• Fournisseur OpenAI
• Référence de configuration