codex-auto

codex-auto 是一个面向 Windows 的 Codex CLI 代理与自动化助手。它会自动发现 Clash/Mihomo 当前可用的 HTTP 或 mixed 代理端口，临时配置代理环境，再启动交互式 Codex 或把参数转发给 codex exec。

这里的 auto 指自动探测代理和准备运行环境，不代表绕过 Codex 的 sandbox、审批策略或其他安全控制。

解决的问题

Clash/Mihomo 的代理端口可能因客户端、配置或运行模式而变化，导致直接启动Codex（CLI）时出现反复连接或MCP失败；为此用户常需要在每次打开Codex时手工查看端口并重复设置 HTTP、HTTPS 和 WebSocket 代理变量。

codex-auto 会：

1. 检查 Clash/Mihomo 是否正在运行。
2. 查找这些进程拥有的本地监听端口。
3. 通过候选端口访问 https://chatgpt.com，找出可用代理。
4. 仅在 Codex 运行期间设置代理变量。
5. 从当前目录启动 Codex，并原样转发其他 Codex 参数。
6. Codex 退出或启动失败后恢复原有环境。

系统要求

• Windows 10/11
• Windows PowerShell 5.1 或 PowerShell 7+
• 已安装并登录的 Codex CLI
• 正在运行的 Clash 或 Mihomo
• curl.exe，以及 Get-NetTCPConnection 或 Windows 自带的 netstat.exe

直接运行

powershell -NoProfile -ExecutionPolicy Bypass -File .\Codex-Auto.ps1

指定工作目录：

powershell -NoProfile -ExecutionPolicy Bypass -File .\Codex-Auto.ps1 `
  -WorkingDirectory C:\src\my-project

只检测代理，不启动 Codex：

powershell -NoProfile -ExecutionPolicy Bypass -File .\Codex-Auto.ps1 -DetectOnly

安装 codex-auto 命令

powershell -NoProfile -ExecutionPolicy Bypass -File .\Install-CodexAuto.ps1

安装器会把主脚本复制到 %LOCALAPPDATA%\STANKAL\codex-auto，并在 PowerShell Profile 中添加一个带有明确边界标记的托管代码块。修改现有 Profile 前会自动创建备份。

如果 Profile 已经包含手写的 codex-auto 函数，安装器会停止。确认允许新安装版本覆盖命令解析顺序时，可使用：

powershell -NoProfile -ExecutionPolicy Bypass -File .\Install-CodexAuto.ps1 -Force

重启 PowerShell 后运行：

codex-auto

卸载：

powershell -NoProfile -ExecutionPolicy Bypass -File .\Install-CodexAuto.ps1 -Uninstall

卸载器只删除自己的托管代码块和安装副本，不会删除 Profile 中的其他内容。

交互与自动化示例

启动交互式 Codex：

codex-auto

从指定目录启动：

codex-auto -WorkingDirectory C:\src\my-project

使用 Codex 的非交互模式：

codex-auto exec --sandbox read-only "Summarize this repository"

输出 JSONL：

codex-auto exec --json "List the five highest-risk areas"

Codex 官方将 codex exec 定义为脚本和 CI 中的非交互入口。权限与 sandbox 仍由传给 Codex 的参数和用户配置决定：Non-interactive mode。

参数

• -WorkingDirectory <path>：覆盖默认的当前目录。
• -TestUrl <url>：覆盖代理连通性测试地址。
• -DetectOnly：只显示检测结果，不启动 Codex。
• 其他参数：原样转发给 Codex CLI。

如果已经把 Codex 的 -C 或 --cd 放在透传参数中，脚本不会再次添加目录。不要同时使用 -WorkingDirectory 与 -C/--cd。

安全与隐私

• 不修改 Codex 的审批策略、sandbox、模型或登录状态。
• 不读取、记录或上传 Codex 凭据。
• 不写入 ~/.codex/.env 或 config.toml。
• 连通性检查只通过本机代理向测试 URL 发出无认证的 HTTP HEAD 请求。
• 代理变量仅临时存在，并在 Codex 退出后恢复。

OpenAI 官方文档将环境变量定位为 shell 范围的覆盖方式：Environment variables。

故障排查

Clash/Mihomo is not running

先启动 Clash/Mihomo，再运行 codex-auto。

No local listening ports were found

确认客户端启用了 HTTP 或 mixed 代理端口。工具会优先使用 Get-NetTCPConnection；如果普通用户没有权限，则自动回退到 netstat.exe。某些服务模式仍可能把代理端口归属到名称不含 Clash/Mihomo 的其他进程。

No usable HTTP or mixed proxy port was found

确认代理节点可访问 https://chatgpt.com。也可以更换探测地址：

codex-auto -TestUrl https://example.com -DetectOnly

PowerShell 执行策略阻止脚本

直接运行时使用 README 中的 -ExecutionPolicy Bypass 命令，或根据组织策略调整签名与执行方式。

测试

测试不会访问网络、修改 Profile 或启动真实 Codex：

powershell -NoProfile -ExecutionPolicy Bypass -File .\tests\Run-Tests.ps1

English summary

codex-auto is a Windows PowerShell launcher that detects a working Clash/Mihomo HTTP proxy, applies proxy variables only for the lifetime of Codex, and forwards arguments to either interactive Codex CLI or codex exec. It does not weaken Codex approvals or sandbox settings.

许可证

Copyright (C) 2026 STANKAL

本项目基于 GNU General Public License v3.0 发布。