登录和密钥
浏览器授权弹不出来时，检查是否在无图形环境里硬跑交互模式。无图形就改用官方密钥环境变量。
密钥无效、账号未开通、地区限制，看起来都像“模型坏了”。先打开官方页面看账号状态。
不要把同事的会话目录复制过来当自己的登录。
- 分清浏览器授权和密钥。
- 核对账号是否可见该产品。
- 不要重装来修登录。
命令找不到或指错二进制
新终端、查 PATH、确认装的是官方安装页那一份。
多个版本并存时，用 which 或 Windows 上的 where 看实际路径。
WSL 与 Windows 各有一份，不要混。
- 新开终端。
- 核对可执行文件路径。
- 不要从随机镜像再装一份。
先跑 inspect 再猜
配置没加载、技能找不到、MCP 消失，inspect 比重装便宜。
看当前目录是不是仓库根。在家目录启动会让发现项全空。
把输出里的来源路径对一下：用户级还是项目级，有没有被另一份覆盖。
- 在仓库根运行。
- 对照配置、说明书、技能、插件、钩子、MCP 六项。
- 缺哪项就只修哪项。
MCP 进程和权限
服务器没出现：命令路径、工作目录、环境变量。
出现了但工具失败：超时、结果太大、权限模式拒绝。
一次只开一条，才能知道是谁吵。
- inspect 是否列出。
- 本地进程能否单独启动。
- 先关到只剩一条。
技能找不到
名字、目录、是否被 inspect 列出。重名用限定名。
/skillify 草稿若还在临时路径，不会进团队仓库。
- inspect 里有没有。
- 点名而不是盼自动。
- 检查限定名。
计划模式里改不了文件
这常常是功能，不是故障。计划门闩会挡住编辑，直到你批准。
若你已经批准仍不能写，再查权限模式、钩子拒绝和工作区只读。
- 确认自己不在未批准的计划里。
- 看钩子有没有拒绝。
- 看磁盘权限。
乱改文件或改太少
乱改：回退，收窄路径，重写计划。
改太少：验收命令可能写错，或说明书把该目录列为禁区。
不要在脏树上连续追加“再试一次”。
- 先 git diff。
- 回退后再开新一轮。
- 核对说明书禁区。
排错时更糟的做法
同时重装、换模型、加三条 MCP。
把完整 inspect 输出贴到公开论坛。
- 用非官方二进制覆盖。
- 在生产仓库试验始终批准。
- 把密钥写进 issue。
卡死时的最短路径
登录或密钥、PATH、仓库根、inspect、再单项。
- 能运行 grok。
- 在正确目录。
- inspect 能打印。
- 一次只修一类问题。
- 修完做只读自检。
排错完回到主路径
回到你卡住的那一章继续。总览页是目录。
产品行为变更时，以官方文档和开源仓库的 issue 为准。