故障处理
Codex 文件明明存在却看不到？文件列表、路径与实际读取验证
文件在编辑器里能打开，Codex 却看不到、提示不存在或读到旧内容？从保存状态、执行位置、文件引用到实际读取逐步排查，区分符号链接显示问题与路径、权限错误。
文件在编辑器里能打开，Codex 的列表却没有，或者它回答“找不到文件”。先确认是哪一种现象：列表没显示、引用没选中、工具读取报错，还是读到了另一份内容。 这些情况需要不同的下一步，不能只凭“看不到”就清缓存、重装或扩大权限。
本文处理 Codex 看不到工作区文件、codex file not found in workspace 和 symlink 文件看不到等问题。目标是核对同一执行位置里的同一份已保存文件，用实际读取结果验证，而不是让 Codex 口头确认“已经看过”。
先按现象分流
| 现象 | 下一步检查 |
|---|---|
| 编辑器能打开，磁盘上却找不到 | 第 1 步：保存状态与实际目录 |
| 文件列表或搜索没有结果 | 第 2 步：列表范围、筛选和文件引用 |
| 符号链接不显示，终端却能读 | 第 2、3 步：分别验证列表与读取 |
报 No such file or directory / ENOENT |
第 3 步：路径、目录层级与链接目标 |
报 Permission denied / EACCES |
第 4 步：系统访问权限与任务规则 |
| 回复的内容与编辑器不一致 | 第 5 步：保存版本、checkout 与本轮读取记录 |
如果你要找的是“Codex 改了代码，修改落到哪里”，先看 worktree 与改动定位。如果是普通文件能读，但仓库规则没加载，转到 AGENTS.md 不生效排查，不把两种问题混在一起。
1. 先核对保存状态、执行主机和真实路径
适用情况： 文件只在编辑器里可见，或不确定 Codex 与自己看的是不是同一个项目。
先保存你准备提供给 Codex 的那份文件，并从编辑器复制完整路径。若内容还不准备落盘，就明确它只是编辑器中的未保存内容，不能据此要求磁盘读取工具找到它。不要为诊断另存成多个同名文件。
再核对当前聊天使用的客户端、主机与目录：本机、WSL、容器、远程连接和云端任务分别确认。同名项目、另一份 clone 或 worktree 可以有相同的相对路径，却没有相同内容。本机文件存在，也不能证明远程执行端已经有这份文件。
在支持该命令的 CLI 聊天框里，可用 官方 /status查看当前会话信息；远程 TUI 还显示地址与服务端版本。它不代替文件读取，也不要假定它一定列出所有需要的路径。其他客户端按实际界面确认环境，再让任务中的只读工具报告当前目录。
预期结果： 能对应“编辑器文件绝对路径”和“任务实际主机、工作区、当前目录”。不一致时，回到正确项目或执行位置再检查；不要先把本机绝对路径直接当作容器或 Windows/WSL 内的路径。若是不同 worktree，按上面的工作树指南核对，不先复制覆盖文件。
2. 列表找不到，不等于不能直接读取
适用情况： 目录树、搜索或 @ 候选中没有目标，但尚未取得实际读取错误。
先确认看到的是什么列表，以及是否设置了筛选。用于显示改动的列表不能当作整个项目文件清单。记录“哪一个入口没列出什么”，不要把它改写成“文件不存在”。
按 官方 CLI 提示词说明，可以在输入框用 @ 插入工作区文件路径，或用 /mention 引用具体文件。/mention 的操作是在 CLI 聊天框输入命令与路径，再选择匹配结果。桌面和 IDE 以当前版本实际提供的引用入口为准，不照搬别的客户端快捷键。
验证： 候选里能选中时，确认引用的是预期文件，再进入下一步验证读取。候选里没有时，给出已经核实的明确路径，请工具只读检查这一个文件；这不会授予额外权限。路径、引用标记或模型一句“看到了”，都不能单独证明正文已经读取。
符号链接尤其要分开判断：openai/codex #18262 是 2026-04-17 提交的桌面应用个案，报告版本为 26.415.21839。后续反馈描述了“文件树不显示，但 @ 仍可引用”，另有 macOS 复现反馈称 agent/terminal 能读取。它说明这些入口可能表现不同，不证明当前所有版本都存在该故障，也不是所有链接都能读取的保证。
如果直接读取正确，而问题只出在列表，就按列表显示问题记录版本与最小复现；不为让列表出现而重建项目、改权限或复制敏感目标。当前入口不可用时，明确路径可以作为临时工作方式，但仍要完成下面的读取验收。
3. 对同一个普通文本文件，实际读一次并保留错误
适用情况： 已确认执行位置，需要区分路径、链接、权限与内容问题。
先选择本次任务需要、允许读取的普通小文本文件。下面的读取会输出前五行，不对密钥、私人资料、大型文件、二进制或未知设备路径照搬。占位路径要换成实际绝对路径；路径里的空格用引号保留。
macOS / Linux：Bash 或 zsh
先在同一执行主机上的正常终端检查，再请 Codex 的任务工具在相同环境、相同目录检查同一路径。不要把外部终端成功当成任务内部也成功。
pwd -P
codex_target='/绝对路径/项目/docs/示例.md'
ls -ld "$codex_target"
if [ -L "$codex_target" ]; then
readlink "$codex_target"
fi
if [ -f "$codex_target" ]; then
if sed -n '1,5p' "$codex_target"; then
codex_read_rc=0
else
codex_read_rc=$?
fi
else
codex_read_rc=1
printf '未确认目标是普通文件；先核对路径、链接目标或访问权限。\n' >&2
fi
printf '\nread_exit=%s\n' "$codex_read_rc"ls -ld 查看该路径本身；如果最后一级是符号链接，readlink 显示它记录的目标。目标为相对路径时，要相对链接所在目录解释。链接也可能在上级目录中，因此最后一级不是链接，不代表整条路径没有经过链接。必要时继续核对相关父目录与解析后的目标。
预期结果： 能看到预期的文本片段，read_exit=0。未确认目标是普通文件时，这段检查以 1 标记并跳过正文读取；实际读取失败时保留 sed 的退出状态。空文件可以成功但没有正文输出；成功只验证这一次所读的范围，不证明模型已理解整个文件。若失败，保留原始错误和检查状态，不要只转述为“文件看不到”。
Windows：PowerShell
在目标 Windows 主机的 PowerShell 中使用实际路径；WSL 内运行 Linux 命令时使用 WSL 的路径。下面的 -LiteralPath 不把路径中的方括号当通配符：
Get-Location
$codexTarget = 'C:\项目\docs\示例.md'
Get-Item -LiteralPath $codexTarget -Force -ErrorAction Stop |
Select-Object FullName, Length, Attributes, LinkType, Target
Get-Content -LiteralPath $codexTarget -TotalCount 5 -ErrorAction StopGet-Item查看对象信息，Get-Content读取指定内容。-Force 用于查看隐藏项，不绕过系统权限；对象信息可见，也不保证正文可读。出现错误就按错误处理，不把 PowerShell cmdlet 的结果用原生命令的 $LASTEXITCODE 代替。
依据结果选择下一步
| 实际结果 | 检查方向 | 验证方法 |
|---|---|---|
路径不存在 / ENOENT |
拼写、大小写、父目录、目标主机、断开的链接 | 修正已确认的路径后，读取同一目标 |
| 元数据可见，正文读取被拒 | 文件权限、目录访问权限、任务策略 | 按第 4 步核对实际拒绝来源 |
| 提示目标是目录 | 传入了文件夹而非普通文件 | 指定目录内本次需要的具体文件 |
| 外部终端成功，任务工具失败 | 两边环境与有效权限是否一致 | 保留任务中的具体错误，不能据外部结果猜根因 |
| 命令成功，内容却不同 | 另一份文件、未保存内容、期间又发生修改 | 按第 5 步重新对照 |
修正链接前先确认它为什么指向那里。不要默认删除链接、复制整个外部目录，或让任务绕过组织禁止的路径。若连 sed 等查看命令都找不到，先看 任务环境里的命令不可用，不要把命令缺失判成目标文件丢失。
4. 忽略规则和权限拒绝，要分别验证
适用情况： 实际发现过程跳过了文件，或任务中的读取工具明确报访问拒绝。
如果你使用 Git 的忽略规则排查列表结果，可在仓库根目录查看一个具体的仓库相对路径：
git check-ignore -v --no-index -- "docs/示例.md"Git 官方说明中，-v 显示规则来源，--no-index 让检查不因文件已跟踪而跳过。输出中的 ! 是否定规则，不能看到一行就判“被忽略”；本地核验中，这条带 -v 的命令命中否定规则也返回 0，因此要读具体规则，不能只看退出状态。无匹配时无输出、退出 1，致命错误另查。这只能解释 Git 的忽略判断，不能证明当前 Codex 列表一定使用同样的规则，更不能把 .gitignore 当作所有工具的读取禁令。不为让文件出现而把密钥加入版本控制。
若工具真正被拒，先核对同一用户在该执行端的系统访问权限，再看 Codex 的有效策略。当前官方文件系统权限区分 read、write、deny：只读允许读取，而 deny 可拒绝读写；路径规则还存在范围与优先级。不能仅凭“只读模式”解释为什么连正文也读不了。
先识别客户端版本与正在使用的权限机制；不要把新版 permission profile 和旧 sandbox_mode 配置混写。配置与状态不符时，继续查 config.toml 加载与覆盖。符号链接也不是绕过目标路径权限的授权。
验证与后续： 只在已有授权的必要范围内处理确认的原因，再用原任务工具读取原目标。如果组织明确禁止读取，验收结果应是准确的拒绝原因、目标范围与管理员需处理的信息，不以 Full Access、管理员启动或递归改权限强行制造成功。
5. 最后验证：读到的是当前版本，而非另一个文件
适用情况： 工具能读，回复却仍像旧内容，或还没有可核验的实际读取记录。
在已保存、短时间内没有其他程序修改的普通文本文件上做一次最小验证。把下面的占位路径替换为核实后的实际路径，再发到当前任务；这是正常 Codex 请求，会使用当前账号额度：
这一轮仅排查文件读取，不修改、生成、暂存或删除文件。
目标是我已保存并确认允许读取的普通小文本文件：<实际绝对路径>。
请先确认当前执行位置，再用实际读取工具检查这一个文件。
成功时报告读取路径，并返回前五行中可公开的必要片段，供我与磁盘文件对照；
若遇到敏感内容则不要回显，改为说明需要安全的验证样本。
失败时保留工具的原始错误与发生阶段，不猜测正文，不改权限或清缓存。
不要把只列出路径、引用成功或以前聊天里的内容当成本轮读取结果。成功标准： 活动记录里有本轮实际读取，路径与执行位置正确，返回的必要片段与当前磁盘内容对应；若任务需要其他行，还应检查对应范围。仅核对前五行不能证明后面所有内容一致；文件在验证期间又变动时，应先确认最终保存版本，再重新读取相关范围。
如果本轮工具返回正确而回答仍引用旧内容，要求它明确依据这次读取的结果重新分析；这时不能继续报告为“文件不存在”。没有实际读取记录时，记录“尚未验证”，不宣称已经修复。没有当前官方或可复现证据，不把缓存、索引或云同步当成已确定根因，也不默认删除它们。
完成后应能说清三件事：看不到发生在哪个入口；任务实际能否读取；读取结果是否属于预期的当前文件。 仅列表异常时记录客户端版本与最小复现；真实读取失败时保留执行端、脱敏路径、链接目标与原始错误，再按对应分支求助。路径和错误可能包含用户名、项目名，分享前先脱敏。
本文于 2026-10-17 核对官方资料，并在独立目录验证 Bash/zsh 对普通文件、有效与断开链接、忽略文件及读取拒绝的检查。没有修改用户 Codex 配置、调用真实模型或复现桌面文件树故障；PowerShell 示例按 Microsoft 文档核对，未在 Windows 实机执行。历史 issue 用于说明现象边界，不作为当前版本故障结论。