> ## 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.

# Windows深度使用

> 系统掌握 Windows 原生终端、PowerShell、CMD 与 WSL2 下的路径、环境变量、权限、Git、代理、编码、进程诊断和安全边界。

## 本页解决什么问题

Windows 上的开发工具通常同时经过操作系统、终端、Shell、Git、编辑器和网络代理。看到同一条命令在 PowerShell、CMD 和 WSL2 中表现不同，并不一定是工具故障，常见原因是当前 Shell、当前目录、PATH、权限或编码环境不一致。
本页把这些边界放在一起说明，适用于使用 Codex CLI、Git、Node.js、Python 以及常见构建工具的 Windows 开发者。重点不是记住某一个版本的界面，而是学会先确认环境，再执行动作，最后用证据验证结果。
本文默认使用 Windows 11；Windows 10 也可参考，但系统策略、Windows Terminal、ConPTY、WSL2 和 PowerShell 版本可能不同。涉及 Codex 的具体参数，以本机 `codex --help` 和官方文档为准。

## 先建立环境模型

在 Windows 上，至少要区分四个层次：

1. **Windows 原生环境**：程序使用 Windows 文件系统、Windows 权限和 `.exe` 进程模型。
2. **PowerShell**：Windows 上功能完整的 Shell，命令、变量、管道和对象模型与 Bash 不同。
3. **CMD**：兼容性很强的传统 Shell，语法简单，但脚本能力和诊断能力有限。
4. **WSL2**：运行 Linux 内核环境的虚拟化子系统，有独立的 Linux 用户、PATH、权限和进程空间。
   “打开了终端”不是充分信息。排查问题时，必须同时记录：

* 使用的是 Windows PowerShell 5.1、PowerShell 7、CMD 还是 WSL2 Bash；
* 当前工作目录是什么；
* 命令实际解析到哪个文件；
* 当前用户和是否提升为管理员；
* 网络是否经过代理；
* 文件是由 Windows 工具还是 Linux 工具写入的。

## 一分钟环境检查

在 PowerShell 中执行：

```powershell theme={null}
$PSVersionTable
Get-Location
whoami
[Environment]::OSVersion.Version
Get-Command git,codex,node,npm,wsl -ErrorAction SilentlyContinue |
  Select-Object Name,CommandType,Source,Version
```

在 CMD 中执行：

```bat theme={null}
ver
cd
whoami
where git
where codex
where node
where npm
wsl --status
```

在 WSL2 中执行：

```bash theme={null}
uname -a
cat /etc/os-release
pwd
whoami
printf '%s\n' "$PATH"
command -v git
command -v codex
```

把结果保存到临时位置时，避免把令牌、Cookie 或完整代理密码写入日志。诊断输出中若出现用户名、内网地址或项目路径，外发前先脱敏。

## 选择原生 Windows 还是 WSL2

默认原则是：项目使用 Windows 工具链，就在原生 Windows 中工作；项目依赖 Linux 工具链，就在 WSL2 中工作。不要为了“看起来更专业”而额外引入另一套环境。

### 原生 Windows 适合这些情况

* 使用 Visual Studio、MSBuild、Windows SDK 或 `.NET` Windows 项目；
* 项目依赖 PowerShell、Windows 服务、注册表或 Windows API；
* 使用 Windows 版 Git、Node.js、Python 和 VS Code；
* 仓库位于 `C:\Users\...`，团队也主要在 Windows 上开发；
* 需要直接调用 `.exe`、`winget` 或 Windows 凭据管理器。

### WSL2 适合这些情况

* 构建脚本只在 Bash、GNU 工具或 Linux 环境下可靠；
* 依赖 Linux 包管理器、容器工具或 Linux 原生编译链；
* 项目部署目标是 Linux，开发环境需要尽量接近生产环境；
* 仓库和依赖已经位于 WSL2 的 Linux 文件系统中。

### WSL2 的文件位置

WSL2 中的 Linux 项目建议放在：

```bash theme={null}
mkdir -p ~/code
cd ~/code
```

不建议把高频读写的仓库放在 `/mnt/c/Users/...`。Windows 挂载盘在 WSL2 中通常有更高的 I/O 开销，也更容易遇到大小写、符号链接、权限和文件监听差异。
从 Windows 访问 WSL2 文件，可在资源管理器地址栏输入：

```text theme={null}
\\wsl$\Ubuntu\home\<用户名>\code
```

不要直接操作 WSL2 的虚拟磁盘文件，也不要用 Windows 工具修改发行版内部的系统目录。

### 安装和检查 WSL2

使用管理员 PowerShell：

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

目标是看到发行版的 `VERSION` 为 `2`。已有发行版需要转换时，先备份，再执行类似命令：

```powershell theme={null}
wsl --set-version Ubuntu 2
```

WSL2 内的 Codex、Git、Node.js 等工具需要在 Linux 环境中单独安装。Windows PATH 中的同名程序不等于 WSL2 内已安装。

## PowerShell、CMD 和 WSL2 的命令差异

下面是最常用的对应关系：

| 目的                                                                       | PowerShell              | CMD              | WSL2 Bash           |
| ------------------------------------------------------------------------ | ----------------------- | ---------------- | ------------------- |
| 查看目录                                                                     | `Get-ChildItem` 或 `dir` | `dir`            | `ls -la`            |
| 进入目录                                                                     | `Set-Location` 或 `cd`   | `cd`             | `cd`                |
| 当前目录                                                                     | `Get-Location`          | `cd`             | `pwd`               |
| 查找命令                                                                     | `Get-Command`           | `where`          | `command -v`        |
| 复制                                                                       | `Copy-Item`             | `copy`           | `cp`                |
| 移动                                                                       | `Move-Item`             | `move`           | `mv`                |
| 删除文件                                                                     | `Remove-Item`           | `del`            | `rm`                |
| 查看文本                                                                     | `Get-Content`           | `type`           | `cat`               |
| 设置变量                                                                     | `$env:NAME = 'value'`   | `set NAME=value` | `export NAME=value` |
| 清屏                                                                       | `Clear-Host`            | `cls`            | `clear`             |
| 查看进程                                                                     | `Get-Process`           | `tasklist`       | `ps`                |
| 结束进程                                                                     | `Stop-Process`          | `taskkill`       | `kill`              |
| PowerShell 的管道传递的是对象，CMD 和 Bash 的管道通常传递文本。因此下面这条 PowerShell 命令可以直接按属性筛选： |                         |                  |                     |

```powershell theme={null}
Get-Process | Where-Object CPU -gt 100 | Sort-Object CPU -Descending
```

在不确定命令属于哪个 Shell 时，先看提示符。`PS C:\>` 通常是 PowerShell，`C:\>` 通常是 CMD，`user@host:~$` 通常是 WSL2 Bash。

## 路径规则

### Windows 原生路径

Windows 常见绝对路径如下：

```text theme={null}
C:\Users\alice\code\demo
D:\work\project
```

PowerShell 的单引号适合包裹原样路径：

```powershell theme={null}
Set-Location -LiteralPath 'C:\Users\alice\code\demo'
Get-ChildItem -LiteralPath 'D:\work\project'
```

路径包含空格时必须加引号：

```powershell theme={null}
Set-Location 'C:\Users\alice\My Projects\demo'
```

### PowerShell 中的反斜杠

PowerShell 不把反斜杠当作转义字符，但反引号 `` ` `` 才是 PowerShell 的转义符。下面的路径可以直接使用：

```powershell theme={null}
$project = 'C:\Users\alice\code\demo'
```

要拼接路径，优先使用 `Join-Path`，不要手工堆叠斜杠：

```powershell theme={null}
$project = Join-Path $HOME 'code\demo'
$src = Join-Path $project 'src'
```

验证路径是否存在：

```powershell theme={null}
Test-Path -LiteralPath $project
Resolve-Path -LiteralPath $project
```

`-LiteralPath` 会把 `[`、`]`、`*` 等字符按普通字符处理；处理用户提供的路径时优先使用它。

### CMD 中的路径

CMD 使用双引号包裹含空格的路径：

```bat theme={null}
cd /d "C:\Users\alice\My Projects\demo"
```

`cd /d` 可同时切换盘符和目录。只写 `cd C:\...` 时，在某些 CMD 会话中不会切换当前盘符。

### WSL2 路径映射

Windows 盘符通常映射为 `/mnt/<盘符小写>`：

```bash theme={null}
cd /mnt/c/Users/alice/code/demo
```

Windows 路径 `C:\Users\alice\code` 与 WSL2 路径 `/mnt/c/Users/alice/code` 指向同一位置，但它们不是同一个 Shell 的字符串格式。需要转换时可使用：

```bash theme={null}
wslpath 'C:\Users\alice\code\demo'
wslpath -w /home/alice/code/demo
```

不要把 `/mnt/c/...` 直接当成 Linux 原生路径使用，也不要在 PowerShell 中照抄 `/home/alice/...`。

### 特殊路径和大小写

Windows 文件名通常不区分大小写，Linux 通常区分大小写。一个在 Windows 上可用的 `Readme.md`，在 WSL2 中可能与 `README.md` 被视为两个文件。提交前检查真实名称：

```powershell theme={null}
git ls-files | Sort-Object
```

```bash theme={null}
git ls-files | sort
```

Windows 还保留一批设备名，例如 `CON`、`PRN`、`AUX`、`NUL`、`COM1` 和 `LPT1`，不要用它们作为普通文件名。过长路径、尾随空格和尾随句点也可能在不同工具中产生不一致行为。

### 当前目录是安全边界

运行 Codex 或脚本前，先打印当前目录：

```powershell theme={null}
Get-Location
Get-ChildItem -Force
```

确认目录无误后再执行会写入、删除、安装或提交的命令。不要在 `C:\`、用户根目录、系统目录或生产挂载目录中直接实验。

## PATH 和命令解析

PATH 是一组目录，Shell 会按顺序在其中寻找可执行文件。常见问题不是程序没安装，而是当前终端没有看到正确的 PATH，或 PATH 中有多个同名版本。

### 查看 PATH

PowerShell：

```powershell theme={null}
$env:Path -split [IO.Path]::PathSeparator
```

CMD：

```bat theme={null}
echo %PATH%
```

WSL2：

```bash theme={null}
printf '%s\n' "$PATH" | tr ':' '\n'
```

### 查找实际命令

PowerShell：

```powershell theme={null}
Get-Command codex -All
Get-Command node -All
```

CMD：

```bat theme={null}
where codex
where node
```

WSL2：

```bash theme={null}
type -a codex
command -v node
```

PowerShell 的 `Get-Command` 可能显示别名、函数、脚本和应用程序；检查 `CommandType` 与 `Source`，不要只看命令名称。

### 临时修改 PATH

只对当前 PowerShell 进程有效：

```powershell theme={null}
$env:Path = 'C:\Tools\bin;' + $env:Path
```

只对当前 CMD 进程有效：

```bat theme={null}
set "PATH=C:\Tools\bin;%PATH%"
```

只对当前 WSL2 Shell 有效：

```bash theme={null}
export PATH="$HOME/.local/bin:$PATH"
```

临时修改适合验证，不适合作为永久配置。永久修改用户 PATH 时，优先使用 Windows 的“环境变量”设置界面或 .NET API，并先备份原值：

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

修改后必须重新打开终端、IDE 或编辑器。已经运行的进程不会自动读取新的环境变量。

### 避免 PATH 污染

不要把当前目录 `.`、下载目录或不可信的可写目录放到 PATH 前面。PATH 中同名的 `git.exe`、`node.exe` 或脚本可能导致运行了错误版本，甚至执行恶意文件。
发现多个版本时，先记录路径和版本，再决定保留哪一个：

```powershell theme={null}
Get-Command git -All | Format-List *
git --version
```

不要随意删除系统目录中的程序。通过包管理器安装的工具，使用对应包管理器卸载；手工安装的工具，先确认没有其他项目依赖它。

## 安装 Codex 与验证

Windows 原生安装优先使用官方安装方式。执行远程脚本前，应确认来源、网络和组织政策，不能把“网上复制的一行命令”当作天然安全。
PowerShell 安装命令示例：

```powershell theme={null}
powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"
```

`ByPass` 只作用于该次 PowerShell 进程，不等于永久关闭执行策略；`irm` 是 `Invoke-RestMethod` 的别名，`iex` 是 `Invoke-Expression` 的别名。更严格的做法是先下载并审阅脚本，再执行本地文件：

```powershell theme={null}
$installer = Join-Path $env:TEMP 'codex-install.ps1'
Invoke-WebRequest -Uri 'https://chatgpt.com/codex/install.ps1' -OutFile $installer
Get-Content -LiteralPath $installer
powershell -ExecutionPolicy ByPass -File $installer
```

安装后打开新 PowerShell：

```powershell theme={null}
codex --version
codex --help
```

若使用 npm：

```powershell theme={null}
npm install -g @openai/codex
```

不要在权限不明时直接使用管理员身份运行 `npm`。先检查：

```powershell theme={null}
node --version
npm --version
npm config get prefix
Get-Command codex -All
```

同一台机器上同时通过官方安装器和 npm 安装，可能存在多个 `codex`。先用 `Get-Command codex -All` 找出实际来源，再按安装方式清理多余版本。

## 登录、凭据和项目边界

启动 CLI 前进入实际项目目录：

```powershell theme={null}
Set-Location 'C:\Users\alice\code\demo'
codex
```

登录方式、设备码登录和可用功能会随版本变化，以本机帮助和官方说明为准。远程或无浏览器环境通常需要设备码或其他官方支持的登录方式。
认证缓存应当视为密码。不要把 `auth.json`、API key、`.env`、SSH 私钥、浏览器 Cookie 或调试输出提交到 Git。检查仓库状态：

```powershell theme={null}
git status --short --ignored
```

让代理读取或修改文件前，先确认工作目录和授权范围。敏感目录不应通过宽泛的读目录授权暴露给工具。任务描述中明确：允许修改哪些目录、禁止访问哪些目录、是否允许联网、是否允许安装依赖。

## Windows 权限模型

Windows 权限至少涉及三个概念：用户账户、管理员令牌和文件系统 ACL。打开“管理员 PowerShell”只解决一部分权限问题，不能自动赋予网络、企业策略、服务控制或其他用户目录的访问权。
查看当前身份：

```powershell theme={null}
whoami
whoami /groups
net session
```

`net session` 需要管理员权限；失败不代表所有文件访问都失败，只表示当前令牌不能执行该查询。
查看文件 ACL：

```powershell theme={null}
Get-Acl -LiteralPath 'C:\Users\alice\code\demo' |
  Format-List Owner,Access
```

使用 `icacls` 查看更完整的继承信息：

```powershell theme={null}
icacls 'C:\Users\alice\code\demo'
```

不要为了绕过“拒绝访问”而把目录设置为 `Everyone:F`。这会把写权限扩大到不必要的账户，可能让恶意程序或其他用户篡改源码、脚本和配置。

### 权限问题的处理顺序

1. 确认当前路径和目标文件确实是你要操作的对象。
2. 确认文件是否被其他进程占用、是否位于受保护目录。
3. 查看 ACL 和文件属性，不要直接修改所有权。
4. 尝试在用户目录建立最小复现。
5. 只有明确知道影响范围时，才请求管理员批准。
6. 修改权限后记录原始 ACL，并验证普通用户仍不能访问不该访问的内容。
   文件被标记为只读时，可先查看属性：

```powershell theme={null}
Get-Item -LiteralPath '.\config.json' | Select-Object FullName,Attributes
```

确认后再移除只读属性：

```powershell theme={null}
attrib -R '.\config.json'
```

不要对整个磁盘递归修改属性或 ACL。递归权限命令一旦目标路径错误，恢复成本很高。

## Codex Windows 沙箱的边界

Codex 的沙箱模式、审批模式和配置键以当前版本为准。Windows 原生环境通常需要在更严格的权限边界中运行命令；某些初始化动作可能需要管理员批准。不要因为一次命令失败就永久关闭保护。
若看到“目录可被 Everyone 写入”之类警告，应把它当作权限审计提示。先定位具体目录，再缩小写权限，或改用专门的用户目录。不要通过把整个项目开放给所有用户来消除警告。
遇到 Windows 沙箱初始化错误时，先收集：

```powershell theme={null}
codex --version
$PSVersionTable.PSVersion
Get-ComputerInfo | Select-Object WindowsProductName,WindowsVersion,OsBuildNumber
Get-Location
```

还要记录完整错误码和时间，不要上传包含密钥的 `.sandbox-secrets` 等目录。公司设备上的登录权限、组策略、防火墙规则可能由 IT 管理，普通用户不应自行绕过。

## Git 在 Windows 上的基础检查

进入仓库后先检查：

```powershell theme={null}
git rev-parse --show-toplevel
git status --short --branch
git branch --show-current
git remote -v
git config --show-origin --get core.autocrlf
git config --show-origin --get core.filemode
```

确认远端、分支和工作区之后，再让工具修改文件。需要保留当前改动时，不要执行 `git reset --hard`、`git clean -fd` 或不加确认的覆盖操作。

### 换行符

Windows 文本文件常见 `CRLF`，Linux 项目通常约定 `LF`。团队应在仓库中使用 `.gitattributes` 明确规则，例如：

```text theme={null}
* text=auto eol=lf
*.bat text eol=crlf
*.cmd text eol=crlf
*.ps1 text eol=crlf
*.png binary
*.jpg binary
```

先查看现有项目约定，不要未经讨论修改全局行为。检查文件是否被整篇改写：

```powershell theme={null}
git diff --stat
git diff --check
git diff -- . ':!package-lock.json'
```

`core.autocrlf` 常见取值包括 `true`、`input` 和 `false`。应该服从项目规范；如果没有规范，优先在 `.gitattributes` 中固定仓库行为，再谨慎调整本机配置。

### 编码和 BOM

Windows PowerShell 5.1 的 `Out-File -Encoding utf8` 通常会写入 UTF-8 BOM；PowerShell 7 的编码默认行为不同。脚本、JSON、Markdown 和源码是否允许 BOM，要看项目工具链。
PowerShell 7 中写入 UTF-8 无 BOM 的示例：

```powershell theme={null}
'你好，Windows' | Set-Content -LiteralPath '.\utf8.txt' -Encoding utf8NoBOM
```

读取文本时明确编码，避免把中文显示成乱码：

```powershell theme={null}
Get-Content -LiteralPath '.\utf8.txt' -Encoding utf8
```

查看文件开头的字节：

```powershell theme={null}
Format-Hex -LiteralPath '.\utf8.txt' -Count 16
```

CMD 的 `chcp` 查看或切换代码页：

```bat theme={null}
chcp
chcp 65001
```

`chcp 65001` 只影响当前 CMD 会话，不能修复文件本身的编码。乱码时分别检查文件编码、终端字体、Shell 代码页和程序自身的输入输出设置。

### Git 的用户名和提交边界

查看提交身份：

```powershell theme={null}
git config --get user.name
git config --get user.email
```

不要为了修复身份问题把访问令牌写进远端 URL。使用 Git Credential Manager 或组织批准的凭据存储。提交前检查：

```powershell theme={null}
git diff --check
git diff --cached --check
git status --short
```

用户明确要求“不提交、不推送”时，只做工作区检查，不运行 `git commit`、`git push` 或发布命令。

## 网络、代理和证书

安装、登录、拉取依赖和访问 API 可能需要代理。代理至少有三层：Windows 系统代理、WinHTTP 代理以及应用自己的环境变量。配置一层不代表所有程序都会使用它。
查看 PowerShell 当前进程的代理变量：

```powershell theme={null}
Get-ChildItem Env: | Where-Object Name -Match '^(HTTP|HTTPS|ALL|NO)_PROXY$'
```

临时设置代理示例：

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

CMD：

```bat theme={null}
set "HTTP_PROXY=http://127.0.0.1:7897"
set "HTTPS_PROXY=http://127.0.0.1:7897"
set "NO_PROXY=localhost,127.0.0.1"
```

WSL2：

```bash theme={null}
export HTTP_PROXY=http://127.0.0.1:7897
export HTTPS_PROXY=http://127.0.0.1:7897
export NO_PROXY=localhost,127.0.0.1
```

代理地址、端口和协议必须以实际客户端为准。不要把带用户名和密码的代理 URL 写入脚本、Git 配置或终端历史。
检查连通性：

```powershell theme={null}
Test-NetConnection 127.0.0.1 -Port 7897
Resolve-DnsName chatgpt.com
Invoke-WebRequest -Method Head -Uri 'https://chatgpt.com' -UseBasicParsing
```

检查 Git 是否有独立代理：

```powershell theme={null}
git config --show-origin --get-regexp '(^|\.)http\..*proxy$'
```

如果 Git 代理配置过期，优先按仓库和用户范围定位，不要盲目删除全部 Git 配置。证书错误不要直接使用 `-k` 或关闭 TLS 校验；先检查系统时间、根证书、企业中间人证书和代理配置。

## 进程和端口诊断

### PowerShell 查看进程

```powershell theme={null}
Get-Process | Sort-Object CPU -Descending | Select-Object -First 20
Get-Process -Name node,pwsh,Code -ErrorAction SilentlyContinue
```

查看进程启动路径和命令行：

```powershell theme={null}
Get-CimInstance Win32_Process |
  Where-Object Name -Match 'node|codex|python' |
  Select-Object ProcessId,ParentProcessId,Name,ExecutablePath,CommandLine
```

命令行可能包含令牌或个人路径。外发前先脱敏。

### 查看端口占用

```powershell theme={null}
Get-NetTCPConnection -State Listen |
  Sort-Object LocalPort |
  Select-Object LocalAddress,LocalPort,OwningProcess
```

根据 PID 查进程：

```powershell theme={null}
Get-Process -Id 12345
```

结束进程前先确认 PID 和命令行：

```powershell theme={null}
Stop-Process -Id 12345 -WhatIf
Stop-Process -Id 12345
```

CMD 的替代命令：

```bat theme={null}
netstat -ano | findstr LISTENING
tasklist /FI "PID eq 12345"
taskkill /PID 12345 /T
```

`/T` 会连同子进程结束，开发服务器、测试运行器和终端复用器可能因此一起退出。优先使用应用自己的停止命令；不得为了释放端口而批量结束所有 `node.exe`。

### WSL2 进程

```bash theme={null}
ps aux | grep -E 'codex|node|python'
ss -ltnp
pgrep -af node
kill -TERM 12345
```

Windows 与 WSL2 的进程空间虽然可以互操作，但服务、环境变量和端口转发仍有边界。先判断端口由 Windows 进程还是 WSL2 进程监听。

## 常见错误速查

| 现象                         | 首要检查                     | 常见处理                    |
| -------------------------- | ------------------------ | ----------------------- |
| `codex is not recognized`  | `Get-Command codex -All` | 修正 PATH，重开终端            |
| `irm is not recognized`    | 当前是否为 CMD                | 改在 PowerShell 执行        |
| `Access is denied`         | 路径、ACL、占用进程              | 先缩小复现，不要直接提权            |
| `Path too long`            | 路径层级和依赖目录                | 缩短仓库路径，检查长路径策略          |
| `git diff` 整篇变化            | 换行、编码、过滤器                | 检查 `.gitattributes` 和编码 |
| 中文变成问号                     | 文件编码和代码页                 | 统一 UTF-8，重新打开终端         |
| WSL2 中 `command not found` | Linux PATH 和安装位置         | 在 WSL2 内安装并配置 PATH      |
| WSL2 访问项目很慢                | 是否在 `/mnt/c`             | 将仓库放到 `~/code`          |
| 端口已被占用                     | `Get-NetTCPConnection`   | 查 PID 后有选择地停止           |
| 下载超时                       | DNS、代理、证书                | 分层测试，不关闭 TLS 校验         |
| Git 认证失败                   | 远端和凭据来源                  | 使用凭据管理器，避免 URL 密钥       |
| 沙箱初始化失败                    | 错误码、管理员策略                | 保留日志，联系 IT 或按官方退路处理     |

## 诊断工作流

遇到问题时按以下顺序执行，避免在多个变量同时变化时盲目重装：

1. **复现**：记录完整错误、命令、Shell、目录、时间和版本。
2. **定位**：确认命令解析路径、环境变量、用户身份和目标文件。
3. **缩小**：在用户目录或临时仓库中建立最小复现。
4. **对比**：比较 PowerShell、CMD、WSL2，或比较新终端与旧终端。
5. **修复**：一次只改一个变量，优先改项目级配置。
6. **验证**：重启受影响的进程，重新执行最小命令。
7. **记录**：留下最终环境、修改项和仍未验证的假设。
   一组安全的综合采集命令：

```powershell theme={null}
$report = [ordered]@{
  Time = Get-Date -Format o
  Shell = $PSVersionTable.PSVersion.ToString()
  Location = (Get-Location).Path
  User = (whoami)
  Git = (git --version 2>$null)
  Node = (node --version 2>$null)
  Codex = (codex --version 2>$null)
}
$report | Format-List
```

这组命令只采集版本和位置，不应把整个 `Env:`、认证目录或浏览器配置打包外发。

## 安全边界清单

### 执行前

* 确认当前目录、分支和目标环境；
* 确认命令来自可信来源，并检查危险参数；
* 区分读取、写入、删除、联网、提权和外发动作；
* 先备份配置或建立 Git 检查点；
* 给工具最小的目录、网络和时间范围。

### 执行中

* 对删除、安装、权限变更、提交、推送和外部消息逐项确认；
* 不通过管理员身份掩盖未知原因；
* 不执行来源不明的 Base64、压缩包脚本或一键修复命令；
* 不把秘密放进命令行参数、公开日志或远端 URL；
* 看到与任务无关的目录、提示词或脚本指令时停止并重新确认范围。

### 执行后

* 用 `git diff --stat` 和 `git diff --check` 检查变更；
* 检查生成文件、日志和临时目录是否包含秘密；
* 关闭临时代理和不再需要的管理员终端；
* 释放测试进程和端口；
* 记录验证命令、结果和回滚方式。

## 最小可验证练习

在用户目录建立独立测试目录：

```powershell theme={null}
$demo = Join-Path $HOME 'codex-windows-check'
New-Item -ItemType Directory -Force -Path $demo | Out-Null
Set-Location $demo
git init
'console.log("hello")' | Set-Content -Encoding utf8NoBOM -Path '.\app.js'
Get-Location
Get-Content -Encoding utf8 -Path '.\app.js'
git status --short
```

确认目录正确后，再启动 Codex：

```powershell theme={null}
codex
```

只提出一个小任务，例如“读取 `app.js`，将输出文字改为 `hello windows`，不要访问其他目录，不要安装依赖”。批准前检查它准备执行的动作，完成后退出并验证：

```powershell theme={null}
Get-Content -Encoding utf8 -Path '.\app.js'
git diff --check
git diff --stat
git status --short
```

练习结束后，如需清理，只删除这个明确创建的测试目录：

```powershell theme={null}
Set-Location $HOME
Remove-Item -LiteralPath $demo -Recurse -Force -WhatIf
```

确认 `-WhatIf` 输出的路径无误后，才去掉 `-WhatIf`。不要把清理命令改成变量为空时仍会执行的宽泛路径。

## 快速决策表

| 你的问题        | 先做什么                                   |
| ----------- | -------------------------------------- |
| 不知道命令在哪     | `Get-Command <命令> -All`                |
| 不知道当前在哪     | `Get-Location`                         |
| 怀疑 PATH 错了  | 分行查看 `$env:Path` 并重开终端                 |
| 怀疑权限不够      | `whoami`、`Get-Acl`、`icacls`            |
| 怀疑换行污染 diff | 检查 `.gitattributes`、`git diff --check` |
| 中文乱码        | 检查编码、BOM、`chcp` 和编辑器设置                 |
| WSL2 速度慢    | 检查是否位于 `/mnt/c`                        |
| 端口冲突        | `Get-NetTCPConnection` 后查 PID          |
| 网络失败        | 依次测端口、DNS、HTTPS、应用代理                   |
| Codex 沙箱失败  | 记录版本、错误码、策略和日志                         |

## 验收标准

完成一次 Windows 环境配置后，至少应满足：

* 能明确说出当前使用的 Shell 和运行环境；
* `codex --version`、`git --version` 等命令解析到预期位置；
* 项目路径、换行和编码符合仓库约定；
* 普通用户权限可以完成日常工作，不依赖无理由的管理员终端；
* 代理只在需要的进程范围内启用，证书校验保持开启；
* 能定位占用端口的 PID，并避免误杀无关进程；
* 变更前后都有 Git 状态和 diff 证据；
* 凭据、个人数据、日志和临时文件没有进入仓库或外发渠道；
* 失败时能通过最小复现和可回滚步骤继续处理。
  Windows 的稳定使用依赖边界清晰：Windows 原生工具和 WSL2 不混用工作目录，PowerShell、CMD 和 Bash 不混抄语法，PATH、权限、代理和编码不靠猜。每次先确认环境，再做最小动作，最后用命令输出和 Git diff 验收，绝大多数问题都能快速归类。
  参考资料：参考/codex/33-windows.md、参考/codex/03-install.md。动态安装参数、沙箱选项和登录行为以本机 `--help` 与官方文档为准。