Choisir comment exécuter Codex dans une sandbox
Le serveur d’application est le backend de l’agent pour les connexions distantes de la CLI et de l’application de bureau. Choisissez où vous souhaitez interagir avec l’agent :
La CLI rattachée utilise
cws-agent pour créer une sandbox. La CLI locale et l’application de bureau
partagent la même configuration de sandbox SSH.
Pour l’accès mobile, associez votre téléphone à l’ordinateur hôte via Remote. Le
téléphone se connecte à cet hôte, qui se connecte lui-même à la sandbox via SSH. L’ordinateur
hôte doit rester allumé, en ligne et exécuter l’application. Voir
Mobile et autre ordinateur de bureau via Remote.
L’interface utilisateur en mode terminal (TUI) locale envoie les entrées, affiche les sorties et gère
les approbations. C’est le serveur d’application qui détient la session d’agent distante : il ne se contente pas de relayer
des commandes individuelles provenant d’un agent exécuté sur votre ordinateur portable. Voir le
guide du serveur d’application OpenAI.
Le démarrage du serveur d’application n’enregistre pas ses sessions auprès de l’application de bureau ou mobile.
Ces interfaces s’appuient sur une configuration de connexion distincte, décrite dans
Utiliser les applications de bureau et mobile. La documentation
Remote d’OpenAI ne prévoit pas de rattachement depuis un site web pour cette
session auto-hébergée. L’accès via un navigateur sort du cadre de ce guide.
Le flux de travail programmatique de l’API Agents repose sur un modèle d’exécution distinct. Voir la
recette OpenAI Agents API.
Prérequis
Avant de commencer, assurez-vous de disposer des éléments suivants :- Un jeton d’accès à l’API CoreWeave disposant de l’action
SANDBOX_USER. Vous devez également disposer de capacité pour une sandbox CPU. - Un compte OpenAI pris en charge par Codex, ou une clé API OpenAI. L’exemple de serveur d’application de ce guide utilise l’authentification par clé API et la facturation à l’usage de l’API.
- L’URL d’un dépôt public. Le clonage de dépôts privés nécessite des identifiants d’authentification Git dans la sandbox.
- Une connectivité sortante vers OpenAI, les registres de paquets et votre hébergeur Git
[API-ACCESS-TOKEN] par votre jeton d’accès à l’API CoreWeave, puis chargez
l’identifiant d’authentification de la sandbox :
Exécuter Codex CLI dans une sandbox
Utilisezcws-agent pour lancer une sandbox et y rattacher votre terminal. La TUI de Codex
et le processus de l’agent s’exécutent tous deux dans la sandbox.
-
Suivez les instructions d’installation de
cws-agent. Pour une authentification par clé d’API, exportezOPENAI_API_KEYlocalement avant le lancement. L’outil la transmet à la sandbox et l’enregistre via la commande de connexion de Codex. -
Remplacez
[SANDBOX-NAME]par un nom de 1 à 40 caractères composé de lettres minuscules, de chiffres ou de traits d’union, et commençant par une lettre ou un chiffre. Remplacez[REPOSITORY-URL]par l’URL de votre dépôt public :Si une invite vous propose d’importer des skills ou des serveurs Model Context Protocol (MCP), appuyez sur Enter pour l’ignorer dans le cadre de cet exemple. Codex s’ouvre dans le répertoire du projet de la sandbox. Suivez ses invites relatives à la confiance accordée au Workspace et à l’authentification.--permission-mode nativeconserve les paramètres d’autorisation propres à Codex. À défaut, l’encapsuleur ignore par défaut les invites d’approbation. Consultez Modes d’autorisation decws-agent. -
Si vous devez vous connecter à un compte, quittez la TUI, puis authentifiez-vous dans la sandbox :
Suivez la procédure de connexion affichée par Codex. Pour la connexion par appareil en mode sans interface graphique et les restrictions liées au Workspace, consultez Authentification Codex.
-
Effectuez l’étape Vérifier la session. Pour vous reconnecter ultérieurement tant que la
sandbox est en cours d’exécution, utilisez la même commande
connect. Pour reprendre une conversation Codex enregistrée, consultez Sessionscws-agent.
Créer une sandbox accessible par SSH
Effectuez cette configuration pour la CLI locale ou pour l’application de bureau. Elle utilise le kit de développement logiciel (SDK) Sandboxes pour créer une sandbox dans laquelle Codex est installé et authentifié pour un utilisateur SSH non root. Elle ne nécessite pascws-agent.
Cette configuration s’appuie sur un point de terminaison en mode passthrough TLS (Transport Layer Security)
et sur stunnel pour faire transiter SSH par le point de terminaison. Une ProxyCommand
Python générée vérifie le certificat TLS, puis SSH
authentifie votre clé et vérifie la clé d’hôte. Le serveur d’application n’expose aucun écouteur
public. Cette approche est conforme aux recommandations d’OpenAI en matière d’exposition réseau.
Préparer le client SSH
Utilisez un ordinateur macOS ou Linux équipé de Python 3.12+, deuv et d’OpenSSH.
Pour l’accès depuis l’application de bureau, utilisez une application et un système d’exploitation pris en charge, conformément aux
instructions relatives aux hôtes SSH d’OpenAI.
Cette configuration utilise l’identifiant d’authentification de la sandbox mentionné dans Prérequis, ainsi qu’une
clé API OpenAI associée à la facturation de l’API.
Remplacez [OPENAI-API-KEY] par votre clé API OpenAI :
Créer la sandbox SSH
Enregistrez le code suivant dans le fichiercreate_codex_ssh.py. Ce script crée une sandbox d’une durée de 8 heures, installe
Codex 0.154.0 et configure un compte agent non root avec une authentification SSH
par clé publique. Il transmet la clé OpenAI à codex login via l’entrée standard (stdin)
et ne stocke pas la clé dans la configuration de création de la sandbox. Codex enregistre ses identifiants de connexion
dans la sandbox.
Le script crée également un certificat TLS valide 1 jour, puis récupère le certificat
public et la clé d’hôte SSH via le SDK Sandboxes authentifié. La configuration
client générée vérifie ces deux éléments. Conservez le répertoire de sortie pour pouvoir vous reconnecter.
Script de configuration du sandbox
Script de configuration du sandbox
create_codex_ssh.py
[REPOSITORY-URL] par l’URL d’un dépôt Git public, puis choisissez un nouveau
répertoire de sortie situé en dehors de votre dépôt :
ssh_config et laisse la
sandbox en cours d’exécution. Le répertoire de sortie contient également les fichiers sandbox-id, tls.crt
et known_hosts, ainsi que le redirecteur tls_proxy.py. Si la configuration échoue après la
création, le script tente d’arrêter la sandbox. Si l’arrêt échoue lui aussi, l’erreur
d’origine indique l’ID de la sandbox afin que vous puissiez la nettoyer manuellement.
Avant de connecter Codex, vérifiez la connexion SSH :
agent, codex-cli 0.154.0 et repository-ready.
Si la première connexion échoue, réessayez une fois que le point de terminaison et les services ont fini
de démarrer. Si les connexions échouent toujours, examinez les fichiers /var/log/codex-sshd.log et
/var/log/codex-stunnel.log à l’aide du SDK Sandboxes.
Une fois la connexion SSH vérifiée, poursuivez avec
votre CLI locale ou avec les
applications de bureau et mobiles.
Connecter votre CLI locale au serveur d’application Codex
Commencez par suivre les étapes de la section Créer une sandbox accessible par SSH. Utilisez une version LTS (support à long terme) de Node.js prise en charge pour installer localement la même version de Codex. Le paquet npm requiert au minimum Node.js 16 :-
Dans le répertoire du projet de la sandbox, démarrez le serveur d’application. Cette commande enregistre la sortie
de démarrage même si le serveur d’application s’arrête. Laissez le terminal ouvert :
L’option
-talloue un terminal distant pour que Ctrl+C parvienne à l’écouteur. -
Dans un deuxième terminal, redirigez un port local vers cet écouteur et laissez la
connexion ouverte :
-
Dans un troisième terminal, connectez la TUI locale et sélectionnez explicitement le répertoire
du projet distant :
-
Vérifiez que la TUI affiche
/workspace/project, puis suivez les étapes de la section Vérifier la session. Si la connexion échoue, examinez la sortie de démarrage conservée :
codex --remote d’origine.
Cet écouteur est distinct du serveur d’application géré par l’application de bureau.
Le partage d’une conversation entre les deux n’a pas été vérifié. Consultez la
référence d’OpenAI sur la connexion de la TUI locale.
Une fois que vous avez terminé, quittez la TUI, puis appuyez sur Ctrl+C dans le terminal de l’écouteur
et dans celui du transfert. Suivez ensuite
Se reconnecter et arrêter la sandbox SSH
pour récupérer les fichiers et arrêter les ressources de calcul.
Utiliser les applications de bureau et mobiles
Suivez d’abord la procédure Créer une sandbox accessible en SSH. Ajoutez la sandbox comme projet SSH dans l’application de bureau, puis utilisez Remote pour reprendre votre travail depuis un téléphone associé. C’est l’hôte de bureau qui maintient la connexion SSH.Connecter l’application de bureau
Ajoutez la sandbox en tant que projet distant, puis vérifiez que Codex écrit bien dans son système de fichiers.-
Dans le fichier
~/.ssh/cw-codex-session/ssh_config, copiez le blocHost cw-codexgénéré. Dans le fichier~/.ssh/config, collez-le avant les valeurs par défautHost *, le cas échéant. Si une entréeHost cw-codexexiste déjà, remplacez-la au lieu d’en créer un doublon. -
Exécutez
ssh cw-codex 'codex --version'. Corrigez les éventuelles erreurs d’authentification ou de clé d’hôte avant de poursuivre. -
Dans l’application de bureau, ouvrez Settings > Connections, puis ajoutez ou activez
l’hôte SSH
cw-codex. -
Choisissez
/workspace/projectcomme dossier de projet distant, puis enregistrez le projet. -
Ouvrez ce projet distant et démarrez une conversation. Demandez à Codex d’écrire une valeur unique
et non secrète dans le fichier
/workspace/project/sandbox-proof.txt. -
Depuis votre terminal, vérifiez le résultat de manière indépendante :
Mobile et autre ordinateur via Remote
La fonctionnalité Remote d’OpenAI relie les applications de bureau et mobiles prises en charge par l’intermédiaire d’un hôte appairé. D’après la documentation, la configuration mobile commence dans l’application de bureau ChatGPT sur un hôte Mac ou Windows, avec le même compte et le même Workspace sur les deux appareils. Les paramètres de l’organisation et la disponibilité de l’enregistrement de session peuvent restreindre l’accès. Pour travailler dans la sandbox depuis votre téléphone, connectez d’abord cet hôte de bureau au projet SSH de la sandbox. Appairez ensuite votre téléphone avec l’hôte de bureau. Dans ChatGPT sur iOS ou Android, utilisez Remote. Votre téléphone se connecte à l’hôte de bureau, qui lui-même se connecte à la sandbox. L’application de bureau doit rester ouverte, active et en ligne. Une autre application de bureau Mac ou Windows prise en charge peut se connecter au même hôte lorsque Control other devices est disponible. Suivez les instructions de configuration de Remote d’OpenAI. Une URL WebSocket de serveur d’application n’est pas une URL d’appairage mobile. De même, la connexioncodex exec-server --remote de l’API Agents ne permet pas d’appairer un appareil mobile.
Continuité des sessions et autres points d’entrée
Remote permet de poursuivre les chats d’un hôte connecté depuis des appareils associés. Cela ne garantit pas pour autant qu’une conversation démarrée avec l’exemple directcodex --remote
apparaisse dans un projet SSH de bureau configuré séparément. Considérez
ce transfert de session d’une interface à l’autre comme non vérifié pour cette configuration.
La configuration Remote publiée répertorie les clients mobiles et les clients de bureau pris en charge. Elle ne
documente pas la manière de joindre le site web de ChatGPT ou de Codex à cette session de sandbox. L’accès
via le site web n’entre pas dans le périmètre des interfaces couvertes par ce guide.
Certaines compilations de Codex proposent les commandes expérimentales codex remote-control start et
codex remote-control pair. Elles gèrent un démon de serveur d’application ainsi que l’association,
mais les instructions mobiles publiées ne décrivent aucun flux d’association pris en charge pour une sandbox Linux
sans interface graphique. Ce guide ne les considère pas comme un équivalent vérifié de
Claude Remote Control. Consultez l’aide de la CLI installée et les recommandations actuelles d’OpenAI
avant de vous y fier.
Vérifier la session
Si vous avez suivi Exécuter Codex CLI dans un sandbox ou Connecter votre CLI locale au serveur d’application Codex, vérifiez que Codex écrit bien dans le système de fichiers du sandbox. Pour un accès depuis l’application de bureau, suivez Connecter l’application de bureau. Remplacez[PROOF-VALUE] par une valeur unique et non secrète, puis envoyez le prompt suivant dans
la TUI Codex connectée :
- cws-agent
- CLI locale via SSH
Se reconnecter à la sandbox SSH et l’arrêter
Tant que la sandbox est en cours d’exécution, utilisez le même hôtecw-codex et le même projet.
La fermeture d’une connexion SSH ou de l’application de bureau n’arrête pas les ressources de calcul de la sandbox.
Avant d’arrêter la sandbox, enregistrez votre travail dans Git ou copiez les fichiers dont vous avez besoin :
Host cw-codex par la nouvelle
configuration. Chaque sandbox dispose de son propre point de terminaison, de son propre certificat TLS et de sa propre clé d’hôte SSH.
Conserver les résultats et arrêter
Pour la CLI locale et l’application de bureau, suivez Se reconnecter à la sandbox SSH et l’arrêter. Pourcws-agent, enregistrez un instantané du Workspace et arrêtez les ressources de calcul :
cws-agent down [SANDBOX-NAME] --no-snapshot.
Quitter la TUI n’arrête pas les ressources de calcul. Lorsque vous arrêtez la sandbox ou qu’elle expire,
ses processus prennent fin. Pour relancer le calcul, restaurez les fichiers enregistrés, puis redémarrez Codex.
Les instantanés ne conservent pas les processus en cours d’exécution. Lorsque vous choisissez les éléments à conserver, traitez les fichiers d’authentification
et de session Codex enregistrés comme des données sensibles.
Dépannage
Effectuez les vérifications suivantes pour résoudre les problèmes courants :- L’authentification échoue : distinguez les identifiants d’authentification utilisés pour le provisionnement de la sandbox, l’authentification au modèle Codex et les clés SSH. Chacun a un rôle différent.
- Les options du serveur d’application sont rejetées : comparez la sortie de
codex --versionen local et dans la sandbox. L’exemple de CLI locale nécessite les options WebSocket documentées. - La TUI se connecte, mais les tâches échouent : vérifiez l’accès au modèle, la facturation, la confiance accordée au Workspace et les paramètres d’approbation. Une connexion de transport établie ne garantit pas à elle seule l’accès au modèle.
- La connexion est interrompue : reconnectez-vous tant que la sandbox est en cours d’exécution. Les délais d’expiration du point de terminaison ou du transport ne prolongent pas sa durée de vie et ne garantissent pas qu’un tour de conversation en cours a abouti.
- Remote n’est pas disponible dans l’application mobile : vérifiez les exigences d’OpenAI concernant le compte, le Workspace, l’hôte et l’enregistrement de session. Le simple démarrage du serveur d’application ne suffit pas à l’activer.