【免费下载链接】claude-sneakpeek
Get a parallel build of Claude code that unlocks feature-flagged capabilities like swarm mode.
claude-sneakpeek doctor是 Claude Code 变体管理器内置的健康检查命令，专门用来快速定位环境变量、PATH 路径和认证凭据三大类问题。当你运行某个变体命令（比如zai或mclaude）却发现打不开、报找不到命令、或一直卡在登录界面时，别急着重装——先跑一次doctor，用这份 7 点诊断清单逐一排查，绝大多数故障都能 5 分钟内锁定根因。
一、doctor 命令到底查什么
doctor会扫描你创建的所有变体（variant），对每一个检查 4 个硬性条件，只要有一项不满足就会标记为 ✗：
npx claude-sneakpeek doctor典型输出长这样：
✓ mclaude ✓ zai ✗ minimax binary: missing wrapper: /home/you/.local/bin/minimax它的判断逻辑非常直接——变体「健康」当且仅当：元信息存在 + 二进制文件存在 + wrapper 命令存在 + （Windows 下）.mjs脚本存在。核心代码在 doctor，输出格式由 printDoctor 负责，测试用例可参考 doctor.test.ts。理解这 4 个条件，就理解了后面所有排查要点的骨架。
二、先看两个默认路径，别在错误目录里找
doctor依赖两个路径参数，默认值定义在 constants：
| 参数 | 含义 | 默认值（Linux / macOS） | 默认值（Windows） |
|---|---|---|---|
--root | 变体根目录（存放各variant.json） | ~/.claude-sneakpeek | ~/.claude-sneakpeek |
--bin-dir | wrapper 命令安装目录（决定 PATH 生效位置） | ~/.local/bin | ~/.claude-sneakpeek/bin |
⚠️ 关键区别：Linux/macOS 的 wrapper 默认装在
~/.local/bin，而 Windows 装在变体根目录下的bin。如果你换了--bin-dir，必须让 shell 能访问这个目录，否则 wrapper 命令一定找不到——这是 PATH 类问题的头号来源。
三、7 个诊断要点逐一排查
要点 1：变体是否被「发现」
doctor通过扫描--root目录下含variant.json的子目录来列出变体（见 listVariants）。如果输出是No variants found.，说明：
- 路径给错了，变体其实在别的
--root里； - 或目录被误删 /
variant.json丢失。
动作：ls ~/.claude-sneakpeek/*/variant.json确认元文件仍在。
要点 2：二进制文件是否存在（binary: missing）
报告中binary: missing表示meta.binaryPath指向的 Claude Code 本体不见了。它通常由 npm 安装（包名@anthropic-ai/claude-code，见 DEFAULT_NPM_PACKAGE），删除、断网安装失败、或目录迁移都会导致它丢失。
动作：对应变体执行npx claude-sneakpeek update <name>重新安装本体。
要点 3：wrapper 命令是否就位（PATH 问题核心）
wrapper 是让claude-sneakpeek变体「一键可用」的入口脚本，由 writeWrapper 生成，路径解析在 getWrapperPath。如果doctor报 wrapper 路径但你的终端输入命令时提示command not found，几乎都是PATH 没有包含--bin-dir。
动作：确认echo $PATH含~/.local/bin，必要时在~/.bashrc/~/.zshrc追加：
export PATH="$HOME/.local/bin:$PATH"要点 4：Windows 下的.mjs脚本完整性
在 Windows 上，wrapper 是一个.cmd外壳 + 同名.mjs脚本的两段式结构（见 getWrapperScriptPath）。doctor会额外检查.mjs是否存在（scriptOk条件）。若.cmd在、.mjs缺失，命令会启动即崩溃。
动作：update <name>重建 wrapper，或检查~/.claude-sneakpeek/bin/下两文件是否成对。
要点 5：环境变量注入链
每个变体启动时，wrapper 会注入两组关键变量：CLAUDE_CONFIG_DIR（指向该变体的settings.json）和TWEAKCC_CONFIG_DIR（定制目录），随后从settings.json的env字段加载其余变量（如ANTHROPIC_BASE_URL、ANTHROPIC_API_KEY）。这条注入链在 wrapper.ts 中实现。
排查点：
- 手动
export的变量可能被 wrapper 覆盖，改错地方等于白改； settings.json里env字段若 JSON 格式破损，会被静默忽略，导致 base-url 不生效。
动作：检查对应变体settings.json的env是否为合法 JSON，且ANTHROPIC_BASE_URL指向正确的网关。
要点 6：认证凭据是否就位
认证失败常表现为「命令能打开、但一直要登录」。凭据来源分两类：
- Anthropic 系：
ANTHROPIC_API_KEY（写在settings.json）或ANTHROPIC_AUTH_TOKEN（写在 shell 环境）。注意 wrapper 支持CLAUDE_SNEAKPEEK_UNSET_AUTH_TOKEN=1来主动清除ANTHROPIC_AUTH_TOKEN，避免旧令牌干扰； - Z.ai 系：
Z_AI_API_KEY。当它没被手动设置时，工具会尝试自动写入 shell 配置，逻辑见 ensureZaiShellEnv。
动作：确认settings.json里的 key 不是占位符<API_KEY>（占位符会被判定为「未设置」）。
要点 7：shell 环境与source是否真正生效
shell-env步骤会把你当前 shell（zsh→~/.zshrc，bash→~/.bashrc/~/.bash_profile）写入一段带标记的export块，见 resolveShellProfile。写入成功 ≠ 已生效——必须source当前配置文件或新开终端才会加载。
动作：
source ~/.zshrc # 或 ~/.bashrc source ~/.bash_profile # bash 登录 shell然后重跑doctor与目标命令验证。
四、常见报错速查表
| 症状 | 大概率原因 | 对应要点 |
|---|---|---|
No variants found. | --root指错目录 | 要点 1 |
binary: missing | npm 本体缺失 | 要点 2 |
终端command not found | PATH 未含--bin-dir | 要点 3 |
| Windows 启动即闪退 | .mjs脚本缺失 | 要点 4 |
| base-url / 模型不生效 | settings.json的env破损 | 要点 5 |
| 一直卡在登录界面 | API Key 是占位符 / 令牌冲突 | 要点 6 |
| 改完环境变量仍无效 | 未source配置文件 | 要点 7 |
五、从诊断到修复：三条命令收尾
排查完doctor定位的坏变体，用下面这套组合拳即可恢复，无需重建：
npx claude-sneakpeek doctor # 1. 复跑诊断，确认状态 npx claude-sneakpeek update <name> # 2. 重装本体并重建 wrapper source ~/.zshrc # 3. 刷新 shell 环境💡 小贴士：图形化用户也可以在 TUI 主菜单的Diagnostics入口查看同样的健康检查结果，其实现见 DiagnosticsScreen。若多个变体同时坏掉，优先怀疑「PATH」与「shell 环境」这类全局问题，而非逐个变体本身。
按这份清单从「路径 → 文件 → 变量 → 凭据 → shell 生效」的顺序往下走，claude-sneakpeek doctor报出的每一个 ✗ 都能找到明确归属。把它当成排错的第一道关口，能帮你把「盲改半天」变成「按图索骥」。
【免费下载链接】claude-sneakpeek
Get a parallel build of Claude code that unlocks feature-flagged capabilities like swarm mode.
相关推荐
环境装不好怎么办？applypilot doctor 一键诊断你的自动求职配置（附排查清单）
环境装不好怎么办？applypilot doctor 一键诊断你的自动求职配置（附排查清单） ApplyPilot 是一个自动求职 AI Agent：它自动抓取
进阶调优清单：opencode-claude-auth 10个环境变量参数全解析
进阶调优清单：opencode claude auth 10个环境变量参数全解析 opencode claude auth 是一款 OpenCode 插件，直接
SenseNova-Skills 环境诊断指南：sn-image-doctor 技能从入门到排查
SenseNova Skills 环境诊断指南：sn image doctor 技能从入门到排查 本指南以 SenseNova Skills 仓库中的 sn i
AI 技能人工智能深度研究数据分析媒体生成
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
