> ## Documentation Index
> Fetch the complete documentation index at: https://aicoding.cscitech.top/llms.txt
> Use this file to discover all available pages before exploring further.

# 02-平台与环境准备

> 为 Codex 准备可定位、可回滚的 Windows、WSL、macOS 或 Linux 工作环境，检查 shell、路径、Git、网络、编码与最小权限。

## 本页解决什么问题

安装页解决“有没有装上、能不能登录”。本页解决的是另一件事：**Codex 启动后，是否在正确的终端、正确的项目目录、正确的权限和正确的网络环境中工作**。

环境没有准备好时，常见现象包括：命令找不到、同一个命令在不同终端表现不同、Git 把整份文件标成已修改、脚本没有执行权限、代理只对浏览器生效、沙箱读不到目录，或者任务误触碰了不该碰的文件。

本页不重复安装包、账号套餐和首次登录流程。安装或登录失败，请先回看[安装与登录](/02-第一次使用/01-安装与登录)。项目目录的初始化和工作区组织，见[准备项目与工作区](/02-第一次使用/03-准备项目与工作区)。

完成本页后，你应该能够回答：

* 我现在使用的是 Windows 原生、PowerShell、WSL2、macOS 还是 Linux shell？
* `codex`、`git` 和项目脚本究竟从哪个路径被找到？
* 当前目录是不是目标仓库，分支和工作区是否干净？
* 文件的换行、编码、执行权限和大小写行为是否符合项目约定？
* 代理是否同时覆盖安装、Git、包管理器和 Codex 运行时？
* Codex 能否只在一个临时项目中完成一次最小读写验证？

## 先建立安全边界

准备环境时不要从生产目录开始。选择一个没有密钥、客户数据和真实部署凭据的练习仓库；任务结束后可以删除这个练习目录。若必须处理真实仓库，先确认已有修改的来源，避免把同事的未提交改动当成环境噪音。

建议先写下本次任务的非目标：不提交、不推送、不删除目录、不访问生产服务、不读取家目录中的私密文件。代理能运行命令不等于应该获得整台机器的访问权；沙箱和审批是边界，项目约定和人工确认是第二道防线。

日常开发优先使用工作区可写、网络默认关闭、需要出界时询问的权限组合。`danger-full-access` 或等价的完全访问模式只适合一次性的、隔离的、你完全理解的环境。不要为了绕过一个路径错误就永久放开权限。

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

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

### Windows PowerShell

在 PowerShell 运行：

```powershell theme={null}
$PSVersionTable.PSVersion
$env:OS
(Get-Location).Path
[System.Environment]::Is64BitOperatingSystem
```

预期结果：第一行显示 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 运行：

```bat theme={null}
ver
cd
where codex
git --version
```

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

### WSL2 Linux shell

在 WSL 中运行：

```bash theme={null}
uname -a
printf 'shell=%s\n' "$SHELL"
pwd
cat /etc/os-release
```

预期结果包含 `Linux`、当前 shell 路径、类似 `/home/you/project` 的 Linux 路径和发行版信息。再确认 WSL 版本，命令在管理员 PowerShell 中运行：

```powershell theme={null}
wsl --status
wsl --list --verbose
```

预期发行版的 `VERSION` 为 `2`。若是 `1`，不要继续用它做 Codex 的 Linux 工作环境；先按团队策略升级或重新安装 WSL2。WSL2 里的 Codex、Git、Node 和 Python 与 Windows 中的同名程序是两套环境，必须分别检查。

### macOS 与 Linux shell

在 macOS 或 Linux 中运行：

```bash theme={null}
uname -srm
printf 'shell=%s\n' "$SHELL"
printf 'user=%s\n' "$USER"
pwd
```

预期系统名为 `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 项目、`.exe` 工具、PowerShell 脚本 | Windows 原生    | 路径和进程模型一致     |
| Linux 项目、bash、GNU 工具链              | WSL2          | 避免跨平台兼容层      |
| 仓库长期位于 WSL2                        | WSL2          | Git、权限和链接行为一致 |
| 只想快速检查 Windows 文件                  | 原生 PowerShell | 不必增加 WSL 层    |

不要在一个任务中来回切换目录环境。Windows 中的 `C:\work\app` 在 WSL 中通常是 `/mnt/c/work/app`，但它们不是两个独立副本；一边运行构建、一边从另一边改文件，容易产生锁文件、权限和换行混乱。

WSL 仓库应放在 Linux 文件系统，例如 `~/code/app`，而不是长期放在 `/mnt/c/...`。跨文件系统访问会增加 I/O 延迟，也可能放大符号链接、文件监听和权限差异。需要用 Windows 编辑器打开时，可从资源管理器访问 `\\wsl$\发行版\home\用户名\code\app`。

检查 WSL 中仓库位置：

```bash theme={null}
pwd
findmnt -T . -o TARGET,FSTYPE,OPTIONS
```

预期工作目录位于 `/home` 等 Linux 路径，文件系统通常不是 `drvfs`。若输出指向 `/mnt/c` 或 `drvfs`，先决定是否应把仓库迁移到 `~/code`，不要仅靠调高权限补救性能问题。

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

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

### PowerShell 检查 PATH

```powershell theme={null}
$env:PATH -split ';'
Get-Command codex -All
Get-Command git -All
Get-Command node -All
```

预期 `Get-Command` 显示实际 `Source` 或 `Path`。若出现多个 `codex`，先记录全部路径，再按团队安装方式保留一个；不要直接删除未知目录。修改用户 PATH 后必须打开新终端，旧进程不会自动读取新的环境变量。

也可以检查用户级 PATH：

```powershell theme={null}
[Environment]::GetEnvironmentVariable('Path', 'User')
[Environment]::GetEnvironmentVariable('Path', 'Machine')
```

常见错误是把路径写进 Machine PATH，导致需要管理员权限，或把带引号的整段错误地作为路径项。普通开发工具优先放用户 PATH；只有 IT 明确管理的系统工具才放机器级 PATH。

### POSIX shell 检查 PATH

```bash theme={null}
printf '%s\n' "$PATH" | tr ':' '\n'
command -v codex
command -v git
command -v node
type -a codex
```

预期 `command -v` 指向你预期的安装位置。若 `type -a codex` 列出多个结果，先用绝对路径运行并比较版本：

```bash theme={null}
"$(command -v codex)" --version
```

不要用 `sudo` 解决普通用户的 PATH 问题。用用户目录安装的工具应写入正确的 shell 初始化文件，然后重新加载：

```bash theme={null}
printf '%s\n' "$PATH"
. ~/.profile
```

使用 zsh 时检查 `~/.zprofile` 或 `~/.zshrc`，使用 bash 时检查 `~/.profile` 或 `~/.bashrc`。不要把同一个目录重复追加几十次；先搜索配置：

```bash theme={null}
rg -n 'local/bin|codex|PATH=' ~/.profile ~/.bashrc ~/.zprofile ~/.zshrc 2>/dev/null
```

### PATH 故障速查

| 现象                         | 判断                          | 修复                                        |
| -------------------------- | --------------------------- | ----------------------------------------- |
| `codex: command not found` | 当前 shell 找不到命令              | 查安装输出和 `command -v`，补用户 PATH，重开终端         |
| Windows 提示不是命令             | PowerShell PATH 未刷新或命令在另一环境 | 重开 PowerShell，运行 `Get-Command codex -All` |
| 版本与预期不同                    | 多个安装副本                      | 用 `type -a` 或 `Get-Command -All` 清理优先级    |
| WSL 能用、PowerShell 不能       | 两套环境独立                      | 在对应环境单独安装或配置 PATH                         |
| 改了配置仍无效                    | shell 初始化文件未被读取             | 检查 `$SHELL`、启动方式和文件语法                     |

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

Codex 的改动应落在一个可观察、可回滚的 Git 工作区。先检查 Git 身份与版本，不要一上来执行 `git add -A`。

在所有 shell 中都可以运行：

```bash theme={null}
git --version
git rev-parse --show-toplevel
git branch --show-current
git status --short --branch
git config --get core.autocrlf || true
git config --get core.filemode || true
```

预期：Git 版本可用；仓库根目录是你预期的项目；分支名称正确；状态输出中没有被忽略的关键改动。`git rev-parse --show-toplevel` 报“不是 Git 仓库”时，说明你尚未进入项目根目录，或当前目录不是目标项目，不要立即初始化一个新仓库。

查看远端但不要推送：

```bash theme={null}
git remote -v
git log -1 --oneline
```

预期远端和最近提交符合任务上下文。若远端包含内部地址，不要把完整输出贴到公开聊天或工单。

开始任务前，至少建立一个可识别的检查点：已有仓库可以记录当前提交号；练习目录可以先 `git init` 并提交最小文件。工作区已经有未提交改动时，先保存补丁或让负责人确认，不要覆盖它。

查看未跟踪文件和忽略规则：

```bash theme={null}
git status --short
git check-ignore -v .env 2>/dev/null || true
git ls-files --others --exclude-standard
```

预期 `.env`、认证缓存和构建产物按项目规则被忽略，但“被忽略”不是“安全”：Codex 仍可能在允许的工作区内读取它们。敏感文件应放在项目之外，或在任务环境中使用脱敏副本。

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

在 PowerShell 中，路径通常写成 `C:\work\app`；在 POSIX shell 中写成 `/home/you/app`。脚本参数优先使用引号包裹的绝对路径或当前目录的相对路径，路径含空格时必须引用：

```powershell theme={null}
Get-ChildItem -LiteralPath 'C:\work\my app'
```

```bash theme={null}
ls -la -- '/home/you/my app'
```

不要把 PowerShell 的 `C:\...` 直接粘给 WSL 命令，也不要把 `/mnt/c/...` 当作 Windows 原生程序的通用参数。需要转换时，在 WSL 用 `wslpath`：

```bash theme={null}
wslpath -w "$PWD"
wslpath -u 'C:\work\app'
```

检查当前目录和关键文件是否真的存在：

```bash theme={null}
pwd
ls -ld .
```

PowerShell 对大小写通常不敏感，Linux 通常区分大小写。`Config.json` 与 `config.json` 在 WSL/Linux 中可能是两个文件，但在 Windows 工作区中可能发生冲突。跨平台项目的文件名统一使用小写和稳定的 ASCII 字符，避免仅靠大小写区分文件。

符号链接也有平台差异。检查链接：

```bash theme={null}
find . -maxdepth 2 -type l -ls
```

PowerShell 可用：

```powershell theme={null}
Get-ChildItem -Force | Select-Object Name,Mode,LinkType,Target
```

如果 Codex 报无法读取链接目标，先确认目标是否在允许的工作区内，再调整目录结构或给出一次性、最小范围的读取批准；不要直接启用全盘访问。

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

Windows 原生常见 `CRLF`，macOS/Linux 常见 `LF`。团队应以仓库的 `.gitattributes` 为准，而不是让每个人的全局 Git 设置决定提交内容。先检查：

```bash theme={null}
test -f .gitattributes && sed -n '1,120p' .gitattributes || true
git config --show-origin --get core.autocrlf || true
```

适合多数跨平台代码仓库的约定示例：

```text theme={null}
* text=auto eol=lf
*.bat text eol=crlf
*.cmd text eol=crlf
```

不要在没有团队确认时随意提交 `.gitattributes` 或修改全局 `core.autocrlf`。如果一次小改动导致整份文件变化，先执行：

```bash theme={null}
git diff --stat
git diff --ignore-space-at-eol --stat
git diff --check
```

差异只在忽略行尾空白后恢复正常，通常是换行策略不一致。先还原工作区到可确认状态，再按项目规则重新检出；不要用“全局关闭转换”掩盖仓库本身缺少约定的问题。

中文乱码可能来自终端代码页、文件编码或程序输出编码三个不同层面。PowerShell 检查输出编码：

```powershell theme={null}
[Console]::InputEncoding
[Console]::OutputEncoding
chcp
```

PowerShell 7 建议使用 UTF-8；PowerShell 5.1 的 `Out-File -Encoding utf8` 可能写入 BOM。创建或修改中文文件前，遵循项目编辑器和格式化工具的编码约定，不要用一次管道重写整份文件。

POSIX shell 可检查文件类型：

```bash theme={null}
file -bi path/to/file
```

预期代码文件通常显示 `charset=utf-8`。出现 `unknown-8bit`、UTF-16 或 BOM 时，先确认项目是否确实需要该编码；配置文件、脚本和源代码一般统一 UTF-8。

终端显示乱码但文件内容正常时，先用 `git diff --word-diff=plain`、编辑器或 `file` 交叉验证，不要因为屏幕乱码就让 Codex 批量转换所有文件。

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

macOS/Linux 的权限由用户、组和其他用户三组读写执行位组成。查看项目权限：

```bash theme={null}
id
umask
find . -maxdepth 2 -type f -printf '%M %u:%g %p\n' 2>/dev/null | head -40
```

预期当前用户拥有项目文件，普通源文件通常没有不必要的执行位。脚本需要执行时，先确认来源可信，再使用：

```bash theme={null}
chmod u+x ./scripts/check.sh
./scripts/check.sh
```

不要对整个仓库执行 `chmod -R 777`。这会让所有用户可写，破坏安全边界，也会制造巨大的 Git mode diff。若 Git 报文件模式变化，检查：

```bash theme={null}
git diff --summary
git config --get core.filemode
```

Windows 没有完全相同的 Unix mode 模型，重点检查 NTFS ACL 和共享目录权限。PowerShell 可查看：

```powershell theme={null}
Get-Acl -LiteralPath . | Format-List Owner,Access
icacls .
```

出现“Everyone 可写”或项目目录继承了过宽 ACL 的警告时，不要把权限警告当成普通提示。先把仓库移到个人开发目录，或请管理员按组织策略收紧 ACL；不要在不了解继承关系时递归修改系统目录。

检查关键私密目录权限：

```bash theme={null}
stat -c '%A %a %n' ~/.codex ~/.codex/auth.json 2>/dev/null || true
```

认证缓存应由当前用户控制，绝不提交到 Git。排查时只分享脱敏日志，不分享认证文件、密钥目录或完整环境变量。

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

“浏览器能打开”不代表终端能联网。安装脚本、Codex、Git、npm、pip 和系统包管理器可能读取不同的代理设置。先检查是否存在代理变量，但不要把带用户名、密码或令牌的值粘贴出来：

```bash theme={null}
printf 'HTTPS_PROXY=%s\n' "${HTTPS_PROXY:+<set>}"
printf 'HTTP_PROXY=%s\n' "${HTTP_PROXY:+<set>}"
printf 'NO_PROXY=%s\n' "${NO_PROXY:+<set>}"
```

PowerShell：

```powershell theme={null}
'HTTPS_PROXY','HTTP_PROXY','NO_PROXY' | ForEach-Object {
  "$_=" + ($(if (Test-Path "Env:$_") { '<set>' } else { '<unset>' }))
}
```

用不带凭据的目标做连通性测试：

```bash theme={null}
curl -I --connect-timeout 10 https://chatgpt.com
```

PowerShell：

```powershell theme={null}
Test-NetConnection chatgpt.com -Port 443
```

预期是收到 HTTP 响应头，或至少 TCP `TcpTestSucceeded : True`。403、407、超时和 DNS 失败代表不同问题：403 是服务端拒绝，407 通常是代理要求认证，超时可能是代理未生效或网络策略阻断，DNS 失败应检查解析和企业网络配置。

Git 单独检查代理：

```bash theme={null}
git config --show-origin --get-regexp 'http\..*proxy' || true
git ls-remote origin HEAD
```

若 Git 代理配置过期，先让管理员或网络负责人提供正确配置；不要把代理密码写进远端 URL、脚本或仓库配置。一次性测试代理优先使用进程级环境变量，任务结束关闭终端即可：

```powershell theme={null}
$env:HTTPS_PROXY='http://127.0.0.1:7897'
```

```bash theme={null}
HTTPS_PROXY=http://127.0.0.1:7897 curl -I --connect-timeout 10 https://chatgpt.com
```

企业网络可能需要将 `NO_PROXY` 配置为内部域名；配置过大则可能让本应走代理的外部请求绕过代理。不要复制网上的“关闭证书验证”方案。`curl -k`、Git `sslVerify=false` 和忽略代理证书错误只能掩盖问题，并会削弱传输安全。

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

新建一个专用练习目录，避免从家目录、桌面或下载目录启动 Codex：

PowerShell：

```powershell theme={null}
$demo = Join-Path $HOME 'codex-sandbox-check'
New-Item -ItemType Directory -Force -Path $demo | Out-Null
Set-Location $demo
Get-Location
```

macOS/Linux/WSL：

```bash theme={null}
mkdir -p "$HOME/codex-sandbox-check"
cd "$HOME/codex-sandbox-check"
pwd
```

创建无敏感内容的测试文件：

```bash theme={null}
printf 'hello\n' > README.txt
printf '*.log\n' > .gitignore
git init
git add README.txt .gitignore
git commit -m 'environment check point'
```

PowerShell 可用：

```powershell theme={null}
Set-Content -Path README.txt -Value 'hello' -Encoding utf8
Set-Content -Path .gitignore -Value '*.log' -Encoding utf8
git init
git add README.txt .gitignore
git commit -m 'environment check point'
```

检查提交和工作区：

```bash theme={null}
git status --short --branch
git log -1 --oneline
```

预期工作区干净，只显示当前分支和最近提交。若提交因 Git 身份缺失失败，配置个人级 `user.name` 与 `user.email`，不要把公司共享身份或访问令牌写入项目文件。

在 Codex 会话中，先使用只读或工作区可写模式；确认它的工作目录就是该练习目录。若需要读取工作区之外的目录，先问自己是否真的需要，再按当前版本的权限界面或帮助信息授予单个已存在目录，不要直接授权整个用户目录。

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

启动 Codex 前，保存下面这组环境证据。它们不包含密钥，但路径可能含内部项目名，公开分享前仍应脱敏：

```bash theme={null}
printf 'cwd: '; pwd
git rev-parse --show-toplevel
git status --short --branch
command -v codex
a=$(codex --version 2>&1); printf '%s\n' "$a"
```

PowerShell：

```powershell theme={null}
(Get-Location).Path
 git rev-parse --show-toplevel
git status --short --branch
(Get-Command codex).Source
codex --version
```

然后在测试目录启动 Codex，提出一个明确且无副作用的请求，例如“读取 README.txt，告诉我第一行内容，不要修改文件”。预期它能定位文件并回答 `hello`，Git 状态保持不变。

第二次请求可以让它在工作区内创建一个无敏感内容的 `result.txt`，先观察它显示的动作和审批，再决定是否批准。完成后在外部终端检查：

```bash theme={null}
cat result.txt
git status --short
git diff --check
```

预期只有你明确批准的测试文件发生变化，没有访问工作区外目录的行为，没有网络请求要求，也没有换行和编码噪音。发现异常时先退出会话，保留终端输出和 Git 状态，再定位问题。

## 常见错误与修复路径

| 错误或现象                               | 优先判断             | 修复方式                                             |
| ----------------------------------- | ---------------- | ------------------------------------------------ |
| `codex` 找不到                         | PATH 或环境不一致      | 用 `Get-Command -All`、`type -a` 查来源，重开对应终端        |
| `git rev-parse` 失败                  | 不在仓库中            | `pwd` 或 `Get-Location` 后进入正确项目根目录                |
| WSL 中命令可用，Windows 中不可用              | 两套环境分离           | 在目标环境独立安装并检查 PATH                                |
| Git diff 整文件变化                      | CRLF、编码或 BOM     | 检查 `.gitattributes`、`core.autocrlf`、文件类型，再小范围重检出 |
| `Permission denied`                 | 文件无执行位、ACL 或目录只读 | 检查 `ls -l`、`Get-Acl`，只修正目标文件权限                   |
| `Everyone` 可写警告                     | Windows ACL 过宽   | 移到个人目录或请 IT 收紧继承权限                               |
| WSL 运行缓慢                            | 仓库位于 `/mnt/c`    | 迁移到 `~/code`，在同一环境运行 Git 和工具                     |
| `curl` 超时                           | 代理、DNS 或网络策略     | 分别测试 443、代理变量和 Git 代理，不关闭证书校验                    |
| `407 Proxy Authentication Required` | 代理需要认证           | 使用组织批准的代理配置，不把凭据写入命令历史                           |
| 中文输出乱码                              | 终端或文件编码不一致       | 检查 `chcp`、PowerShell 编码和 `file -bi`，按项目统一 UTF-8  |
| 脚本在 Linux 可执行、Windows 失败            | shell、路径或换行不兼容   | 在目标 shell 执行，确认脚本解释器和换行约定                        |
| 同名文件在不同系统冲突                         | 大小写规则不同          | 统一文件名大小写，避免仅大小写区分                                |
| 沙箱读不到外部目录                           | 目录不在工作区边界        | 确认需求后只授予单个目录，任务结束恢复边界                            |

## 出现问题时的收集顺序

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` 通过，改动范围只包含本次测试明确产生的文件。

环境准备的目标不是让所有机器看起来完全一样，而是让每个行为都能解释、每个权限都有限、每个改动都能回退。完成这些检查后，再进入[准备项目与工作区](/02-第一次使用/03-准备项目与工作区)安排真实任务；安装、登录和版本问题回到[安装与登录](/02-第一次使用/01-安装与登录)。

参考资料：`参考/codex/03-install.md`、`参考/codex/33-windows.md`、`参考/codex/02-core-concepts.md`。具体命令、权限名称和默认行为以本机 `codex --help` 与官方文档为准。