新手问题排查

返回 Codex 教学总目录

目标与使用方式

示意图的 01 是记录症状，02 是依表选一个最小检查，03 是修正原因后重做原操作。不是遇到错误就立即重试；先保留输入、状态及原本可用的环境，再缩小问题。

第一步：记录现象与最后成功的动作

先记录时间、平台、应用程式／CLI 版本、目前资料夹、完整命令或操作、预期结果及错误原文。只分享和问题有关的讯息，遮蔽帐号、私有路径与金钥。若是安装成功后才找不到指令，保留安装结果；若是另一个任务仍在跑，保留任务名称与主机。不要把错误截成只剩红字，因为上一行命令与工作目录通常决定下一步。

# Troubleshooting record
- Time and timezone:
- Surface: desktop / CLI / IDE / mobile / web
- OS and app or CLI version:
- Working folder or execution host (redacted if shared):
- Exact command or UI action:
- Expected result:
- Actual error and exit status:
- Last successful action:
- One change attempted:
- Result after that change:
- Files or settings to restore:

安装、登入与平台入口

codex 找不到或不是内外部命令: CLI 安装

PowerShell 阻挡脚本: Windows CLI

macOS／Linux 安装位置不同: macOS · Linux／WSL

登入后还是未授权: 帐号与额度

找不到桌面或手机的某按钮: 平台选择

同一台电脑上的 Windows、WSL、容器与远端主机不一定共用登入或设定；先确认出错的是哪个环境。

Windows 可以用 Get-Command codex 看找到的是哪个执行档；macOS／Linux 用 command -v codex。看到多个安装来源时先记录，不立刻删除旧版或更改全机安全政策。登入问题先分辨 ChatGPT 登入、API key 与组织限制；额度耗尽不会因重装而增加。服务可能异常时查看官方状态页，对照你的错误时间与服务项目，不把网站整体正常视为自己的网路与权限都正常。

工作目录、MD 与设定

改了程式但页面没变: 路径 · 浏览器

AGENTS.md 好像没作用: 规则层级

把 README 当成永久规则: 文件分工

config.toml 解析失败: 设定排错

续接后沿用旧结论: 工作阶段 · 交接

一次只改一个条件。设定恢复正常后保留必要改动，移走你自己加的诊断标记，不能把整份设定覆盖成网路上的范本。

可重现演练：找到真正的资料夹

在档案管理员建立全新的 path-trouble，里面有 project 与 other 两个空白资料夹。只在 project 里建立 marker.md，内容为下方一行。先从 other 开终端机，故意尝试读 marker.md；这会重现档案找不到，不需要 Codex 也不会动到正式专案。接著查目前目录与档案清单，再用明确相对路径读到 marker，最后 cd 进 project 并重做原读档命令。

# Correct folder: PATH-PRACTICE-1

Get-Content -LiteralPath .\marker.md
Get-Location
Get-ChildItem
Get-Content -LiteralPath ..\project\marker.md
Set-Location -LiteralPath ..\project
Get-Content -LiteralPath .\marker.md

cat ./marker.md
pwd
ls
cat ../project/marker.md
cd ../project
cat ./marker.md

第一个读档失败，后面两次应显示相同 PATH-PRACTICE-1；marker 内容未改，修正的是操作位置。完成后回到原本工作目录，练习资料可保留，不需要递回删除。若套用到 Codex，先请它回报目前根目录及指定档案是否存在，再决定是否开错专案。不要把桌面同名任务、另一个 worktree 或手机看到的旧内容当成同一资料夹。

如果需要记录成功状态，PowerShell 的 Get-Content 是 cmdlet，应立即保存 $?；$LASTEXITCODE 主要用于 codex、node 等原生程式。前面的路径练习结束后，终端机应在 project，以下先读不存在的 other/marker.md，再读真正的 marker。PowerShell 预期依序 False、True；shell 则先非零、后 0。不要等其他命令跑完才读状态。

Get-Content -LiteralPath ..\other\marker.md
$practiceReadOk = $?
$practiceReadOk
Get-Content -LiteralPath .\marker.md
$practiceReadOk = $?
$practiceReadOk

cat ../other/marker.md
practice_read_exit=$?
printf '%s\n' "$practice_read_exit"
cat ./marker.md
practice_read_exit=$?
printf '%s\n' "$practice_read_exit"

自动变数的精确定义见 PowerShell 官方文件。两次读档都不改 marker；若档案内容改了，另记为未预期修改并先找原因。这样交接时能把「路径错误已修正」和「档案原文保持」分开核对。

工具、远端与自动化

Skill 出现但做错: 技能验收

Plugin 已安装但无法查资料: 插件排错

MCP 设定存在但工具不可用: MCP 排错

手机读到旧版本: 远端设定 · 跨装置

子代理说完成却有冲突: 代理品质 · 平行整合

排程逾时或重复: 自动化恢复

JSON 有答案但程序失败: JSON／JSONL

依症状只处理相关层，例如已安装插件与来源帐号有权读取是不同状态。

完成排错与恢复工作

修正后重做原本会失败的操作，再加一个相邻案例确认没有破坏既有行为。例如修 Completed 后也测 Active；修改 config 后确认先前正常的设定还在；重连 MCP 后真的读一份虚构文件，而非只看绿色连线图示。把问题、原因、单一修正与验证写回 issue-notes.md，需要交给别人时提供最小可重现输入及已试过的步骤。问题未解决就写未解决，保留可用状态与下一个要查的证据。

最后撤回自己加入的测试标记与暂时设定，保留必要修正、备份及错误纪录。不要藉排错一次清空所有设定、删除工作阶段或公开敏感内容。这个索引不要求照表从头做完；从自己的症状选一列即可，读完专篇可由篇首或篇尾回到教学总目录，再用功能名、指令或 MD 档名搜寻下一步。各平台未提供的功能应记为不支援或尚未开放，与安装故障分开处理。

返回 Codex 教学总目录

阅读完整文字说明

Symptom to One check to Retry

• AI 工具
• 教程
• Codex