Instalación y solución de problemas de Codex en Windows: PowerShell nativo, WSL, permisos de zona de pruebas y problemas de ruta

Los problemas más comunes con Codex en Windows a menudo no son las capacidades del modelo, sino el entorno de ejecución: si el comando está instalado en Windows o WSL, a qué sistema de archivos pertenece la ruta del repositorio, qué conjunto de credenciales usa Git, qué variables de entorno hereda el terminal y dónde permite escribir el entorno de pruebas. Tanto PowerShell nativo como WSL se pueden usar como puntos de entrada, pero no mezcle dos conjuntos de Node, Git, Python y rutas en la misma tarea. Este artículo primero lo ayuda a elegir una ruta y luego completa la instalación, el inicio de sesión, la verificación del repositorio y la ubicación de fallas. El método de instalación, el modelo y la interfaz de aprobación específica del Codex podrán seguir actualizándose. Los principios de diagnóstico de este artículo se pueden reutilizar durante mucho tiempo y los comandos de instalación deben verificarse con la página actual del documento oficial del Codex OpenAI.

Elija primero Windows nativo o WSL

PowerShell nativo es más adecuado:

El proyecto está originalmente en un directorio de Windows como C:\Work;
Depende de Visual Studio, MSBuild, PowerShell o Windows SDK;
Las pruebas deben llamar a programas de Windows;
Los comandos del equipo y los scripts de implementación son principalmente PowerShell. WSL es más adecuado para:
El entorno de producción del proyecto es Linux;
Depende de Bash, herramientas GNU, flujo de trabajo de Docker Linux;
Contiene código que distingue entre mayúsculas y minúsculas, bits de permiso o enlaces simbólicos;
Team README Proporciona principalmente comandos de Linux. El principio de selección es simple: mantener Codex en el mismo entorno que la cadena de herramientas principal del proyecto. No mezcle el repositorio de Windows, el nodo de Windows y WSL Git en una tarea solo porque un determinado comando es más corto en WSL.

Inventario de los dos entornos existentes en el equipo

Verificar en PowerShell:

1
2
3
4
5
6


Get-Command codex -ErrorAction SilentlyContinue
Get-Command node -ErrorAction SilentlyContinue
Get-Command git -ErrorAction SilentlyContinue
codex --version
node --version
git --version

Ingresar WSL:

1
2
3


wsl --status
wsl --list --verbose
wsl

Ejecutar dentro de WSL:

1
2
3
4
5
6


command -v codex
command -v node
command -v git
codex --version
node --version
git --version

No es un error si la salida de los dos lados es diferente, son entornos inherentemente independientes. El problema es que los usuarios piensan que uno está actualizado, pero el otro en realidad se está ejecutando.

Preparación antes de la instalación nativa de PowerShell

Primero confirme que PowerShell y Node de 64 bits estén disponibles:

1
2
3
4


$PSVersionTable
[Environment]::Is64BitProcess
node --version
npm --version

Si usa npm para instalar Codex, ejecute el comando oficial de instalación actual. La forma común es:

1

npm install -g @openai/codex

Después de la instalación:

1
2
3


Get-Command codex
codex --version
codex --help

Si se ha proporcionado el instalador oficial de Windows u otros métodos recomendados, primero se utilizarán las instrucciones oficiales más recientes. No instale tres copias de Codex al mismo tiempo utilizando npm, binarios independientes y múltiples administradores de paquetes. Ver la ruta real resuelta por el comando:

1
2


(Get-Command codex).Source
npm config get prefix

Inicio de sesión y credenciales nativas

Iniciar inicio de sesión:

1

codex login

Una vez completado el inicio de sesión del navegador, regrese a la verificación del terminal del mismo usuario de Windows. No inicie sesión con un administrador de PowerShell y luego ejecútelo como un usuario normal; los directorios de usuarios y las credenciales pueden ser diferentes. Si utiliza la clave API, configúrela según el método de soporte oficial. Las variables de entorno temporales solo tienen efecto en el proceso actual y sus subprocesos:

1
2


$env:OPENAI_API_KEY = '<temporary-key>'
codex

No escriba la clave real en el perfil de PowerShell, el script del repositorio o el historial de comandos. Una vez completada la prueba, cierre el terminal y revoque la clave si es necesario. Cuando falla el inicio de sesión, primero confirme la hora del sistema, la devolución de llamada del navegador, el firewall y el proxy, y no elimine todo el directorio de configuración repetidamente.

Abrir el repositorio en Windows nativo

Usar ruta absoluta:

1
2
3
4


Set-Location -LiteralPath 'C:\Work\my-project'
git rev-parse --show-toplevel
git status --short
codex

Cuando la ruta contiene espacios, -LiteralPath es más confiable que el escape manual. Después de comenzar, deje que Codex realice una verificación de solo lectura:

1

报告当前工作目录、Git 分支和未提交文件，不要修改文件。

La ruta que informa debe ser coherente con git rev-parse --show-toplevel. Si hay un error, salga de la sesión y reinicie en el directorio correcto.

Ubicación correcta para la instalación de WSL

Ingrese la distribución especificada en PowerShell:

1

wsl -d Ubuntu

Instalar Node y Codex en WSL. No llame a /mnt/c/Program Files/nodejs/npm.cmd para pretender completar la instalación de Linux. Verifique que todos los comandos provengan de la ruta de Linux:

1
2
3
4


which node
which npm
which codex
file "$(which codex)"

Ejecute el comando de instalación oficial e inicie sesión:

1
2


npm install -g @openai/codex
codex login

El estado de inicio de sesión de WSL suele estar separado del estado nativo de Windows. Incluso si la autorización se completa con la misma cuenta del navegador, se debe verificar por separado en el entorno de destino.

Si el repositorio WSL está ubicado en /home o /mnt/c

Los proyectos de la cadena de herramientas de Linux se priorizan en el propio sistema de archivos de WSL, por ejemplo:

1
2
3
4
5


mkdir -p ~/src
cd ~/src
git clone https://github.com/example/project.git
cd project
codex

/mnt/c/Work/project es conveniente para que los programas de Windows accedan directamente, pero una gran cantidad de archivos pequeños, bits de permiso, enlaces simbólicos, la escucha de archivos y el comportamiento de los casos pueden diferir. Si el proyecto debe ser utilizado tanto por Visual Studio como por WSL, puede permanecer en el disco de Windows, pero debe probar:

velocidad de instalación npm/pnpm;
Cambios en permisos de archivos Git;
Watcher filtra eventos;
Si el enlace simbólico se creó correctamente;
Pruebe si depende del caso;
Rendimiento del montaje de enlace de Docker. No ejecute dos formateadores simultáneamente desde Windows y WSL para modificar el mismo árbol de trabajo.

Ruta de Windows e intercambio de ruta WSL

Ruta de PowerShell:

1

C:\Work\my-project

Generalmente corresponde en WSL:

1

/mnt/c/Work/my-project

Usar la conversión wslpath es más confiable que el reemplazo de cadenas:

1
2


wslpath 'C:\Work\my-project'
wslpath -w /home/user/src/project

No poner Pase la ruta C:\... directamente al comando nativo de Linux. No pase /home/... a un programa normal de Windows y espere que lo reconozca automáticamente. La ruta en la llamada a la herramienta Codex debe pertenecer al entorno en el que se inicia.

¿Por qué las credenciales de Git se pueden extraer de un lado pero no del otro?

Git de PowerShell puede usar Git Credential Manager; WSL Git puede usar el Agente SSH, el Repositorio de credenciales de Linux o no hay ningún asistente configurado. Verificación de Windows:

1
2


git config --show-origin --get-all credential.helper
git remote -v

Verificación de WSL:

1
2
3


git config --show-origin --get-all credential.helper
git remote -v
ssh -T [email protected]

No escriba el token de acceso personal en la URL remota para corregir la falla de extracción de WSL. Aparecerá en .git/config, registros y parámetros de proceso. Un enfoque más seguro es configurar la CLI de GitHub, la clave SSH o un asistente de credenciales compatible en el entorno seleccionado.

CRLF y “Todos los archivos han sido modificados”

CRLF se usa comúnmente en Windows y LF se usa comúnmente en Linux. Si .gitattributes no está claro, cambiar entre entornos puede hacer que Git piense que una gran cantidad de archivos han cambiado. Mire primero:

1
2
3


git status --short
git diff --numstat
git config --show-origin --get core.autocrlf

El repositorio debe declarar la política a través de .gitattributes, por ejemplo:

1
2
3


* text=auto
*.sh text eol=lf
*.ps1 text eol=crlf

Las reglas reales deben ser consistentes con las del equipo. No ejecute comandos de renormalización masiva cuando ningún usuario haya confirmado cambios. Si ve cientos de cambios tan pronto como se inicia Codex, primero deje de escribir y confirme si se trata de una nueva línea, un bit de permiso o un archivo generado, en lugar de dejar que el Agente continúe “reparando”.

Las comillas de PowerShell son diferentes de las de Bash

Las comillas simples en PowerShell no expanden las variables, las comillas dobles sí lo hacen:

1
2
3


$name = 'demo'
Write-Output '$name'
Write-Output "$name"

Las reglas de Bash son similares pero no idénticas, y el modelo de objetos de canalización es diferente. El contenido propenso a errores incluye:

Comillas dobles en JSON;
$ en expresiones regulares;
comillas invertidas en mensajes de confirmación de Git;
Ruta con espacios;
Parámetros de comando nativos vinculados a parámetros de PowerShell;
curl puede ser un alias en el antiguo PowerShell. Haga que Codex especifique el shell de destino al escribir comandos, como “Ejecutar en PowerShell 7”, no diga simplemente “comando de Windows”.

El entorno limitado y la aprobación no son UAC de Windows

El entorno limitado de Codex determina lo que el Agente puede leer, escribir o ejecutar esta vez; Windows UAC y NTFS ACL determinan los permisos a nivel del sistema operativo. Los dos están en diferentes niveles. Incluso si el programa se ejecuta como administrador, Codex aún puede denegar ciertas escrituras debido a la política de espacio aislado. Por el contrario, el sandbox permite ejecutar comandos que no pueden violar los permisos NTFS. Confirme antes de comenzar la tarea:

Si el directorio raíz del espacio de trabajo es correcto;
Si solo se permite escribir en el repositorio;
Si es necesario el acceso a la red;
Si se requiere la ejecución del comando aprobación;
Si el directorio de configuración del usuario está fuera del alcance;
Si tocará otros discos de montaje. No utilice el modo de privilegio más alto de forma permanente sólo para evitar un aviso. La alta autoridad debe corresponder a tareas claras y objetivos verificables.

Solución de problemas en capas de “Acceso denegado”

Primero obtenga la ruta de error completa, no lea solo la última oración. Compruebe los atributos del archivo y la ACL:

1
2


Get-Item -LiteralPath '.\target-file'
Get-Acl -LiteralPath '.\target-file' | Format-List

Compruebe si está ocupado por otros procesos:

1

Get-Process | Where-Object { $_.ProcessName -match 'node|python|dotnet|code' }

Luego juzgue:

Alcance de la zona de pruebas del Codex;
Permisos de archivos de Windows;
Atributo de solo lectura del archivo;
Interceptación del software antivirus;
Bloqueo de archivos;
La ruta es demasiado larga o problema de caracteres;
Asignación de permisos de montaje WSL. No apague Defender directamente ni dé a todos control total sobre todo el disco.

Conflictos de nodo, Python y administrador de paquetes

Windows puede tener Winget Node, nvm-windows, Volta y herramientas dentro del proyecto al mismo tiempo; WSL también tiene un conjunto de nvm o system Node. Registre la ruta de análisis real:

1

Get-Command node,pnpm,python,pip | Select-Object Name,Source

WSL:

1

type -a node pnpm python3 pip3

Antes de permitir que Codex instale dependencias, lea el archivo de bloqueo packageManager, .nvmrc, .python-version o la herramienta del repositorio. Cuando aparezcan package-lock.json, pnpm-lock.yaml y yarn.lock al mismo tiempo, no permita que el Agente adivine el administrador de paquetes. Primero debes consultar la documentación del proyecto y el historial de Git.

Docker Desktop y WSL

Tanto PowerShell nativo como WSL pueden llamar a Docker Desktop, pero los métodos de montaje de contexto y ruta son diferentes. Comprobación:

1
2
3


docker context show
docker version
docker compose version

Ejecute el mismo comando en WSL para confirmar la conexión con el motor esperado. Las rutas de Windows, las rutas WSL y los volúmenes con nombre en los archivos de Compose no son intercambiables. Cuando encuentre problemas de permisos, primero ejecute docker compose config para ver los resultados del análisis. No exponga Docker Socket a contenedores o agentes que no sean de confianza. Tener acceso a Docker Daemon generalmente significa obtener altos privilegios en la máquina host.

Errores de proxy y TLS

En la red corporativa, el hecho de que el navegador pueda iniciar sesión no significa que npm, Git y Codex CLI puedan acceder a la red externa. Variables de PowerShell View Agent:

1

Get-ChildItem Env:HTTP_PROXY,Env:HTTPS_PROXY,Env:NO_PROXY -ErrorAction SilentlyContinue

Git View Agent:

1

git config --show-origin --get-regexp 'http\..*proxy'

Las variables de entorno WSL no se sincronizan automáticamente con Windows. Configúrelos por separado y deje que NO_PROXY contenga la dirección local que realmente necesita una conexión directa. No utilices desactivar la verificación TLS como solución a largo plazo. Se debe instalar una CA empresarial o el administrador de la red debe proporcionar la configuración de proxy correcta.

Guarde la línea base antes de comenzar la tarea

No importa qué entorno utilice, ejecute primero:

1
2
3


git status --short
git branch --show-current
git rev-parse --show-toplevel

Indique a Codex qué cambios pertenecen al usuario, qué archivos se pueden modificar y qué pruebas se deben ejecutar. Después de completar, verifique al menos:

1
2
3


git status --short
git diff --stat
git diff --check

Las tareas de alto riesgo también deben ejecutar pruebas y compilaciones del proyecto. No utilice “Codex dice que está hecho” en lugar de Git diff y resultados de pruebas.

Comprobación rápida de síntomas comunes

PowerShell no puede encontrar el códice

Reinicie el terminal y verifique npm config get prefix y Get-Command codex para confirmar que no están instalados solo en WSL.

El códice en WSL apunta a .cmd

La RUTA de descripción se mezcla en el directorio global npm de Windows. Borre la RUTA e instale la versión de Linux dentro de WSL.

Después de iniciar sesión correctamente, todavía indica que no está autenticado

Confirme que el usuario y el entorno en ejecución son los mismos que cuando inició sesión. El terminal de administrador, el terminal normal, Windows y WSL pueden tener configuraciones independientes.

Git muestra todos los cambios de bits de permiso

Verifique core.fileMode, la ubicación del repositorio y el comportamiento de montaje de WSL. Primero comprenda los cambios, no se comprometa directamente.

La prueba falla en PowerShell, tiene éxito en WSL

Verifique los scripts de shell, los separadores de ruta, la sintaxis de las variables de entorno y los binarios dependientes. Elija su entorno principal en función de sus objetivos de producción, en lugar de mantener dos conjuntos de procesos que ocasionalmente están disponibles.

Codex solicita acceso a un directorio fuera del espacio de trabajo

Determine si el directorio es realmente el caché de compilación o el SDK. Si la tarea no lo requiere, rechace y permita que use el directorio temporal en el repositorio.

Combinación estable recomendada

Proyecto Windows/.NET/PowerShell: código en NTFS, usando Codex nativo, Windows Git y PowerShell 7. Servicio Linux/Nodo/Proyecto Python: El código se coloca en WSL ~/src, usando WSL Códice, Linux Git y Bash. Debe abarcar proyectos en ambos lados: especificar un entorno de escritura Git único, ejecutar solo herramientas específicas en el otro lado y corregir la estrategia de nueva línea con .gitattributes. Lo más importante no es qué ruta es “más avanzada”, sino si el comando, el sistema de archivos, las credenciales y las pruebas están en el mismo entorno interpretable. Una vez que el entorno sea estable, los costos de solución de problemas del Codex disminuirán significativamente.