Skip to main content

​
本页解决什么问题

安装页解决“有没有装上、能不能登录”。本页解决的是另一件事：Codex 启动后，是否在正确的终端、正确的项目目录、正确的权限和正确的网络环境中工作。 环境没有准备好时，常见现象包括：命令找不到、同一个命令在不同终端表现不同、Git 把整份文件标成已修改、脚本没有执行权限、代理只对浏览器生效、沙箱读不到目录，或者任务误触碰了不该碰的文件。 本页不重复安装包、账号套餐和首次登录流程。安装或登录失败，请先回看安装与登录。项目目录的初始化和工作区组织，见准备项目与工作区。 完成本页后，你应该能够回答：
  • 我现在使用的是 Windows 原生、PowerShell、WSL2、macOS 还是 Linux shell？
  • codex、git 和项目脚本究竟从哪个路径被找到？
  • 当前目录是不是目标仓库，分支和工作区是否干净？
  • 文件的换行、编码、执行权限和大小写行为是否符合项目约定？
  • 代理是否同时覆盖安装、Git、包管理器和 Codex 运行时？
  • Codex 能否只在一个临时项目中完成一次最小读写验证？

​
先建立安全边界

准备环境时不要从生产目录开始。选择一个没有密钥、客户数据和真实部署凭据的练习仓库；任务结束后可以删除这个练习目录。若必须处理真实仓库，先确认已有修改的来源，避免把同事的未提交改动当成环境噪音。 建议先写下本次任务的非目标：不提交、不推送、不删除目录、不访问生产服务、不读取家目录中的私密文件。代理能运行命令不等于应该获得整台机器的访问权；沙箱和审批是边界，项目约定和人工确认是第二道防线。 日常开发优先使用工作区可写、网络默认关闭、需要出界时询问的权限组合。danger-full-access 或等价的完全访问模式只适合一次性的、隔离的、你完全理解的环境。不要为了绕过一个路径错误就永久放开权限。

​
第一步：识别当前平台与 shell

同一台 Windows 电脑可能同时有 PowerShell、命令提示符、Git Bash 和 WSL2。命令语法、路径格式、环境变量和权限模型都不同。先识别，不要凭窗口外观猜测。

​
Windows PowerShell

在 PowerShell 运行：
预期结果：第一行显示 PowerShell 版本，通常是 5.1 或 7.x；$env:OS 通常包含 Windows_NT；当前位置是类似 C:\Users\you\project 的 Windows 路径；最后一行通常为 True。 PowerShell 7 的可执行文件一般叫 pwsh，Windows PowerShell 5.1 一般叫 powershell。版本差异会影响 UTF-8、管道和脚本行为。项目若要求 PowerShell 7，应使用 pwsh --version 验证，不要只看系统里同时存在的旧版本。

​
命令提示符 CMD

在 CMD 运行：
预期结果是 Windows 版本、当前目录、可执行文件路径和 Git 版本。CMD 不支持 Get-ChildItem、$env:PATH、irm 等 PowerShell 写法。看到“irm 不是内部或外部命令”时，通常不是网络问题，而是把 PowerShell 命令粘到了 CMD。

​
WSL2 Linux shell

在 WSL 中运行：
预期结果包含 Linux、当前 shell 路径、类似 /home/you/project 的 Linux 路径和发行版信息。再确认 WSL 版本，命令在管理员 PowerShell 中运行：
预期发行版的 VERSION 为 2。若是 1，不要继续用它做 Codex 的 Linux 工作环境；先按团队策略升级或重新安装 WSL2。WSL2 里的 Codex、Git、Node 和 Python 与 Windows 中的同名程序是两套环境，必须分别检查。

​
macOS 与 Linux shell

在 macOS 或 Linux 中运行：
预期系统名为 Darwin 或 Linux，并显示当前用户和目录。默认 shell 可能是 macOS 的 zsh、Linux 的 bash，也可能是 fish；不要把 ~/.zshrc 的配置盲目写进 ~/.bashrc。

​
第二步：选择 Windows 原生还是 WSL2

选择标准只有一个：项目和主要工具链在哪里，就把 Codex 放在哪里。项目在 Windows 文件系统、主要使用 PowerShell、Visual Studio 或 Windows 版工具时，优先原生 PowerShell。项目依赖 Linux shell、Linux 二进制、bash 脚本或容器工具时，优先 WSL2。 不要在一个任务中来回切换目录环境。Windows 中的 C:\work\app 在 WSL 中通常是 /mnt/c/work/app，但它们不是两个独立副本；一边运行构建、一边从另一边改文件，容易产生锁文件、权限和换行混乱。 WSL 仓库应放在 Linux 文件系统，例如 ~/code/app，而不是长期放在 /mnt/c/...。跨文件系统访问会增加 I/O 延迟，也可能放大符号链接、文件监听和权限差异。需要用 Windows 编辑器打开时，可从资源管理器访问 \\wsl$\发行版\home\用户名\code\app。 检查 WSL 中仓库位置：
预期工作目录位于 /home 等 Linux 路径，文件系统通常不是 drvfs。若输出指向 /mnt/c 或 drvfs，先决定是否应把仓库迁移到 ~/code，不要仅靠调高权限补救性能问题。

​
第三步：确认 PATH 与实际程序来源

PATH 是系统查找命令的目录列表。安装成功但“命令找不到”，通常是 PATH 没刷新；命令版本不对，通常是 PATH 中有多个副本。

​
PowerShell 检查 PATH

预期 Get-Command 显示实际 Source 或 Path。若出现多个 codex，先记录全部路径，再按团队安装方式保留一个；不要直接删除未知目录。修改用户 PATH 后必须打开新终端，旧进程不会自动读取新的环境变量。 也可以检查用户级 PATH：
常见错误是把路径写进 Machine PATH，导致需要管理员权限，或把带引号的整段错误地作为路径项。普通开发工具优先放用户 PATH；只有 IT 明确管理的系统工具才放机器级 PATH。

​
POSIX shell 检查 PATH

预期 command -v 指向你预期的安装位置。若 type -a codex 列出多个结果，先用绝对路径运行并比较版本：
不要用 sudo 解决普通用户的 PATH 问题。用用户目录安装的工具应写入正确的 shell 初始化文件，然后重新加载：
使用 zsh 时检查 ~/.zprofile 或 ~/.zshrc，使用 bash 时检查 ~/.profile 或 ~/.bashrc。不要把同一个目录重复追加几十次；先搜索配置：

​
PATH 故障速查

​
第四步：确认 Git、仓库和文件状态

Codex 的改动应落在一个可观察、可回滚的 Git 工作区。先检查 Git 身份与版本，不要一上来执行 git add -A。 在所有 shell 中都可以运行：
预期：Git 版本可用；仓库根目录是你预期的项目；分支名称正确；状态输出中没有被忽略的关键改动。git rev-parse --show-toplevel 报“不是 Git 仓库”时，说明你尚未进入项目根目录，或当前目录不是目标项目，不要立即初始化一个新仓库。 查看远端但不要推送：
预期远端和最近提交符合任务上下文。若远端包含内部地址，不要把完整输出贴到公开聊天或工单。 开始任务前，至少建立一个可识别的检查点：已有仓库可以记录当前提交号；练习目录可以先 git init 并提交最小文件。工作区已经有未提交改动时，先保存补丁或让负责人确认，不要覆盖它。 查看未跟踪文件和忽略规则：
预期 .env、认证缓存和构建产物按项目规则被忽略，但“被忽略”不是“安全”：Codex 仍可能在允许的工作区内读取它们。敏感文件应放在项目之外，或在任务环境中使用脱敏副本。

​
第五步：路径、大小写与符号链接

在 PowerShell 中，路径通常写成 C:\work\app；在 POSIX shell 中写成 /home/you/app。脚本参数优先使用引号包裹的绝对路径或当前目录的相对路径，路径含空格时必须引用：
不要把 PowerShell 的 C:\... 直接粘给 WSL 命令，也不要把 /mnt/c/... 当作 Windows 原生程序的通用参数。需要转换时，在 WSL 用 wslpath：
检查当前目录和关键文件是否真的存在：
PowerShell 对大小写通常不敏感，Linux 通常区分大小写。Config.json 与 config.json 在 WSL/Linux 中可能是两个文件，但在 Windows 工作区中可能发生冲突。跨平台项目的文件名统一使用小写和稳定的 ASCII 字符，避免仅靠大小写区分文件。 符号链接也有平台差异。检查链接：
PowerShell 可用：
如果 Codex 报无法读取链接目标，先确认目标是否在允许的工作区内，再调整目录结构或给出一次性、最小范围的读取批准；不要直接启用全盘访问。

​
第六步：Git 换行、编码与终端显示

Windows 原生常见 CRLF，macOS/Linux 常见 LF。团队应以仓库的 .gitattributes 为准，而不是让每个人的全局 Git 设置决定提交内容。先检查：
适合多数跨平台代码仓库的约定示例：
不要在没有团队确认时随意提交 .gitattributes 或修改全局 core.autocrlf。如果一次小改动导致整份文件变化，先执行：
差异只在忽略行尾空白后恢复正常，通常是换行策略不一致。先还原工作区到可确认状态，再按项目规则重新检出；不要用“全局关闭转换”掩盖仓库本身缺少约定的问题。 中文乱码可能来自终端代码页、文件编码或程序输出编码三个不同层面。PowerShell 检查输出编码：
PowerShell 7 建议使用 UTF-8；PowerShell 5.1 的 Out-File -Encoding utf8 可能写入 BOM。创建或修改中文文件前，遵循项目编辑器和格式化工具的编码约定，不要用一次管道重写整份文件。 POSIX shell 可检查文件类型：
预期代码文件通常显示 charset=utf-8。出现 unknown-8bit、UTF-16 或 BOM 时，先确认项目是否确实需要该编码；配置文件、脚本和源代码一般统一 UTF-8。 终端显示乱码但文件内容正常时，先用 git diff --word-diff=plain、编辑器或 file 交叉验证，不要因为屏幕乱码就让 Codex 批量转换所有文件。

​
第七步：文件权限与最小权限

macOS/Linux 的权限由用户、组和其他用户三组读写执行位组成。查看项目权限：
预期当前用户拥有项目文件，普通源文件通常没有不必要的执行位。脚本需要执行时，先确认来源可信，再使用：
不要对整个仓库执行 chmod -R 777。这会让所有用户可写，破坏安全边界，也会制造巨大的 Git mode diff。若 Git 报文件模式变化，检查：
Windows 没有完全相同的 Unix mode 模型，重点检查 NTFS ACL 和共享目录权限。PowerShell 可查看：
出现“Everyone 可写”或项目目录继承了过宽 ACL 的警告时，不要把权限警告当成普通提示。先把仓库移到个人开发目录，或请管理员按组织策略收紧 ACL；不要在不了解继承关系时递归修改系统目录。 检查关键私密目录权限：
认证缓存应由当前用户控制，绝不提交到 Git。排查时只分享脱敏日志，不分享认证文件、密钥目录或完整环境变量。

​
第八步：代理与网络分层检查

“浏览器能打开”不代表终端能联网。安装脚本、Codex、Git、npm、pip 和系统包管理器可能读取不同的代理设置。先检查是否存在代理变量，但不要把带用户名、密码或令牌的值粘贴出来：
PowerShell：
用不带凭据的目标做连通性测试：
PowerShell：
预期是收到 HTTP 响应头，或至少 TCP TcpTestSucceeded : True。403、407、超时和 DNS 失败代表不同问题：403 是服务端拒绝，407 通常是代理要求认证，超时可能是代理未生效或网络策略阻断，DNS 失败应检查解析和企业网络配置。 Git 单独检查代理：
若 Git 代理配置过期，先让管理员或网络负责人提供正确配置；不要把代理密码写进远端 URL、脚本或仓库配置。一次性测试代理优先使用进程级环境变量，任务结束关闭终端即可：
企业网络可能需要将 NO_PROXY 配置为内部域名；配置过大则可能让本应走代理的外部请求绕过代理。不要复制网上的“关闭证书验证”方案。curl -k、Git sslVerify=false 和忽略代理证书错误只能掩盖问题，并会削弱传输安全。

​
第九步：准备最小权限工作区

新建一个专用练习目录，避免从家目录、桌面或下载目录启动 Codex： PowerShell：
macOS/Linux/WSL：
创建无敏感内容的测试文件：
PowerShell 可用：
检查提交和工作区：
预期工作区干净，只显示当前分支和最近提交。若提交因 Git 身份缺失失败，配置个人级 user.name 与 user.email，不要把公司共享身份或访问令牌写入项目文件。 在 Codex 会话中，先使用只读或工作区可写模式；确认它的工作目录就是该练习目录。若需要读取工作区之外的目录，先问自己是否真的需要，再按当前版本的权限界面或帮助信息授予单个已存在目录，不要直接授权整个用户目录。

​
第十步：做一次最小验收

启动 Codex 前，保存下面这组环境证据。它们不包含密钥，但路径可能含内部项目名，公开分享前仍应脱敏：
PowerShell：
然后在测试目录启动 Codex，提出一个明确且无副作用的请求，例如“读取 README.txt，告诉我第一行内容，不要修改文件”。预期它能定位文件并回答 hello，Git 状态保持不变。 第二次请求可以让它在工作区内创建一个无敏感内容的 result.txt，先观察它显示的动作和审批，再决定是否批准。完成后在外部终端检查：
预期只有你明确批准的测试文件发生变化，没有访问工作区外目录的行为，没有网络请求要求，也没有换行和编码噪音。发现异常时先退出会话，保留终端输出和 Git 状态，再定位问题。

​
常见错误与修复路径

​
出现问题时的收集顺序

  1. 记录平台、shell、版本和当前目录，不先重装。
  2. 用 Get-Command -All 或 type -a 确认实际程序来源。
  3. 用 git status --short --branch 保存工作区状态。
  4. 分开测试 DNS、TCP、HTTP、Git 和包管理器，不把“网络不通”当作单一故障。
  5. 检查文件换行、编码、执行位和 ACL，只修改确定有问题的对象。
  6. 回到最小权限的临时目录复现，再决定是否需要扩大访问范围。

​
完成标准

以下命令和检查都通过，才算环境准备完成：
  • 平台与 shell 已确认，且没有把 Windows 命令和 WSL 命令混用。
  • codex --version、git --version 能在目标终端找到预期版本。
  • 当前目录由 git rev-parse --show-toplevel 确认，分支和未提交改动已知晓。
  • 项目换行、编码、大小写和脚本权限符合仓库约定。
  • 代理与网络测试结果明确，没有使用关闭 TLS 校验的临时方案。
  • 测试目录没有密钥、认证缓存、客户数据和生产连接配置。
  • Codex 在工作区内完成了最小读写验证，越界操作会请求审批。
  • git diff --check 通过，改动范围只包含本次测试明确产生的文件。
环境准备的目标不是让所有机器看起来完全一样，而是让每个行为都能解释、每个权限都有限、每个改动都能回退。完成这些检查后，再进入准备项目与工作区安排真实任务；安装、登录和版本问题回到安装与登录。 参考资料：参考/codex/03-install.md、参考/codex/33-windows.md、参考/codex/02-core-concepts.md。具体命令、权限名称和默认行为以本机 codex --help 与官方文档为准。