Codex CLI WSL环境OAuth登录失败? AI智能体应用开发工程师必看

做AI智能体开发的老玩家都知道，Codex CLI是咱们高效开发的神器，不管是写代码、做测试还是自动化工作流，用起来都顺手。但只要涉及跨环境使用，尤其是在WSL（Windows子系统）里操作，新手很容易栽在OAuth登录上。

我见过太多刚接触的朋友，在Windows上装好了Codex CLI，切换到WSL终端执行codex login，要么弹出“OAuth callback failed”，要么提示“Unable to start local server”，折腾半天进不去，最后只能放弃WSL，回到Windows终端操作，既麻烦又影响开发效率。

其实这不是Codex CLI本身的问题，也不是你操作失误，核心原因就两个：一是WSL和Windows之间的端口转发没配置好，导致OAuth回调无法正常通信；二是Windows防火墙拦截了WSL的本地服务器，或者浏览器无法访问WSL的本地地址。今天就手把手教大家解决这个问题，每一步都实测可执行，新手跟着走就能搞定，再也不用为登录发愁。

先跟大家说下前提：你的WSL已经安装完成（不管是WSL1还是WSL2都适用），Codex CLI也已经通过npm install -g @openai/codex安装到位，只是执行codex login时出现OAuth登录失败。如果还没安装Codex CLI，先执行安装命令，安装完成后再跟着下面的步骤操作，避免步骤混乱。

另外提醒一句，这个问题看似是小故障，但其实是Codex CLI跨环境部署的基础知识点，也是咱们做AI智能体开发常遇到的场景。很多人解决不了，本质是对环境配置和CLI工具的细节掌握不到位，要是想系统吃透这类知识点，避免后续踩坑，其实可以考虑系统学习相关课程，拿到权威认证，后续不管是求职还是提升自身能力，都更有优势。

下面开始具体操作步骤，全程分3种方案，从简单到复杂，大家可以根据自己的情况选择，优先推荐方案2，操作最简单，成功率最高。

方案一：配置WSL端口转发（适用于有管理员权限的情况）

这种方法的核心是让Windows系统把OAuth需要的端口转发到WSL，解决回调通信问题，步骤如下：

打开Windows PowerShell（必须以管理员身份运行，不然没有端口转发权限），方法：按下Win+X，选择“Windows终端（管理员）”，如果没有这个选项，就选“Windows PowerShell（管理员）”。

执行端口转发命令，复制下面的命令直接粘贴，无需修改，按下回车即可： netsh interface portproxy add v4tov4 listenport=8765 listenaddress=0.0.0.0 connectport=8765 connectaddress=$(wsl hostname -I) 这里解释一下：8765是Codex CLI OAuth登录默认使用的端口，listenaddress=0.0.0.0表示允许所有地址访问，connectaddress=$(wsl hostname -I)会自动获取WSL的IP地址，无需手动查询。

验证端口转发是否成功，执行以下命令： netsh interface portproxy show all 如果输出结果中，有一行包含“8765”和你的WSL IP地址，说明端口转发配置成功。

关闭Windows防火墙（临时关闭，测试完成后可重新开启），方法：Win+R输入control，打开控制面板，找到“Windows Defender防火墙”，点击“关闭或打开Windows Defender防火墙”，选择“关闭Windows Defender防火墙”，点击确定。

切换到WSL终端，重新执行codex login，此时会弹出浏览器，正常登录授权即可，登录成功后，终端会提示“Login successful”。

实用建议：端口转发配置后，重启电脑不会失效，后续再用WSL登录Codex CLI，无需重复配置。如果后续登录又失败，大概率是防火墙重新开启了，再次临时关闭即可。

方案二：使用设备码登录（无需管理员权限，优先推荐）

如果你的电脑没有管理员权限，无法配置端口转发，或者方案一操作后仍失败，就用这个方法，无需配置端口和关闭防火墙，步骤更简单：

打开WSL终端，直接执行以下命令，启用设备码登录模式： codex login --device-code

执行命令后，终端会输出一串设备码（通常是6位数字）和一个验证URL，比如：“Device code: ABC123，Visit https://auth.codex.com/activate to activate”。

打开任意浏览器（Windows或WSL里的浏览器都可以），输入终端提示的验证URL，然后输入设备码，点击“激活”。

在浏览器中完成Codex账号登录（如果已经登录，会直接跳转激活成功页面），激活成功后，回到WSL终端，会自动提示“Login successful”，此时就登录完成了。

实用建议：设备码的有效期通常是10分钟，执行命令后尽快完成激活，避免设备码过期。这种方法适用于所有WSL版本，而且不会影响系统配置，新手首选。

方案三：手动设置Token（适用于前两种方案均失败的情况）

如果前两种方案都不行，大概率是你的WSL环境有特殊配置，此时可以手动获取Token，直接设置到Codex CLI中，步骤如下：

打开Windows浏览器，访问Codex官方登录页面（https://auth.codex.com/login），登录你的Codex账号。

登录成功后，按F12打开开发者工具，切换到“Application”（应用）选项卡，在左侧找到“Local Storage”，点击展开，找到“https://auth.codex.com”对应的存储项。

在存储项中，找到名为“access_token”的字段，复制它的值（注意不要复制多余的空格和符号）。

切换到WSL终端，执行以下命令，将复制的Token设置到Codex CLI配置中： codex config set access_token "你的access_token值" 注意：把“你的access_token值”替换成刚才复制的内容，引号保留，避免出现格式错误。

设置完成后，执行以下命令验证是否成功： codex auth test 如果输出“✓ API key is valid”，说明Token设置成功，此时无需再执行codex login，直接使用Codex CLI的所有功能即可。

实用建议：Token的有效期通常是30天，过期后需要重新获取并设置。如果经常使用，建议定期检查Token有效性，避免影响使用。

常见问题与最佳实践

1. 执行codex login --device-code后，终端提示“Device code invalid”？

解决方法：大概率是设备码过期了，重新执行codex login --device-code，获取新的设备码，尽快完成激活即可。

2. 方案一配置端口转发后，仍提示“callback failed”？

解决方法：检查WSL的IP地址是否变化，WSL重启后IP可能会变，重新执行方案一中的端口转发命令，更新connectaddress即可。

3. 手动设置Token后，执行codex auth test提示“Invalid token”？

解决方法：检查Token是否复制完整，有没有多复制空格或符号，重新复制access_token的值，再次执行设置命令即可。

另外跟大家说个最佳实践，不管用哪种方法登录，登录成功后，建议执行以下三条命令，做个简单测试，确保Codex CLI能正常使用：

codex --version

codex --help

codex run "say hello in chinese"

如果三条命令都能正常输出，说明登录成功，后续可以正常使用Codex CLI进行开发工作了。

其实这类Codex CLI的实操问题，在AI智能体开发中很常见，不仅是WSL环境登录，还有配置文件错误、API密钥失效等问题，都是新手容易踩的坑。如果想系统掌握这些技巧，避免每次遇到问题都到处查资料，不妨了解一下AI智能体应用开发工程师证书的课程。

这个证书的课程由中国电子学会颁发，权威有保障，课程涵盖了Codex CLI、Coze等主流智能体工具的实操的，从基础安装配置到复杂报错解决，再到实战应用，都有详细讲解，而且0基础可学，初级课程只要1980元，包含63节课，学习周期1-2个月，每月都有考试，配备模拟考试系统，主讲大圣老师经验丰富，线上录播课可以随时学习，适合党政机关职员、新媒体从业者、在校生以及想转型AI智能体开发的工作人员。报名可以通过百度搜索AIGCTM培训管理中心，里面还有更多AI相关的认证课程，大家可以根据自己的需求选择。

最后再提醒一句，Codex CLI的使用核心在于细节，很多报错看似复杂，其实只要找对原因，一步就能解决。大家平时使用时，多留意终端的报错信息，结合今天讲的方法，大部分登录问题都能轻松搞定。如果遇到其他Codex CLI的使用问题，也可以留言，我会陆续给大家分享解决方案。