Claude Code

常见问题

Claude Code 接入 Passion8 排错:鉴权、Base URL、模型、settings、MCP、Hooks、权限、缓存和 safe mode。

排错原则:先确认请求真的走到 Passion8,再排模型、配置、MCP、Hooks 和权限。不要一上来改一堆 settings。

安装、PATH、登录和 OAuth 问题先看安装与登录排错。运行时 HTTP/API 错误、500、529、限流、请求过大和模型错误看错误参考。settings、Hooks、MCP 和记忆未生效看配置调试与 .claude 目录。

#快速排错表

现象	优先检查	处理
`401` 或 unauthorized	`ANTHROPIC_AUTH_TOKEN`	确认 Key 完整、未禁用、余额正常,细节见错误参考
连不上或路径异常	`ANTHROPIC_BASE_URL`	应为 `https://passion8.cc`,不带 `/v1`
model not found	模型名	用 `/model` 选择 Passion8 控制台可用 Claude 模型,细节见错误参考
command not found	CLI 是否安装、PATH	`node -v`, `npm -v`, `claude --version`,细节见安装与登录排错
settings 不生效	写错文件或 JSON 无效	用 `claude doctor` 和 `/config`,细节见配置调试与 .claude 目录
Hooks 不触发	matcher 或位置错误	用 `/hooks` 看实际加载
MCP 不连接	scope、信任、OAuth、timeout	用 `/mcp` 和 `claude mcp list`
权限反复问	allow/ask/deny 冲突	用 `/permissions` 看来源
第一轮很慢	缓存 miss	检查模型、effort、MCP、升级
`429`、`529` 或 request too large	限流、容量或请求体过大	降并发、拆任务、保持模型/effort 不变,细节见错误参考

Base URL 最高频错误:Claude Code 使用 https://passion8.cc,不是 https://passion8.cc/v1。

#最小连通性测试

先在一个干净目录里跑:

ANTHROPIC_BASE_URL="https://passion8.cc" \
ANTHROPIC_AUTH_TOKEN="sk-你的 Passion8 API Key" \
claude -p "只回答 ok"

如果这里能通,说明 Passion8 Key 和网络基本正常。再回到项目里排 .claude/、MCP、Hooks、permissions。

#干净配置目录

怀疑本机配置污染时:

mkdir -p /tmp/claude-clean
CLAUDE_CONFIG_DIR=/tmp/claude-clean \
ANTHROPIC_BASE_URL="https://passion8.cc" \
ANTHROPIC_AUTH_TOKEN="sk-你的 Passion8 API Key" \
claude -p "测试干净配置"

如果干净配置能通,原配置里常见问题是:

~/.claude/settings.json 写错
.claude/settings.json 有无效 JSON
Hook 命令失败
MCP server 卡住或需要 OAuth
permissions deny 过宽
插件改变了工具或系统提示

#Safe mode

--safe-mode 会禁用大多数自定义项,用于确认是不是配置导致问题:

claude --safe-mode

它会禁用:

CLAUDE.md
skills、plugins
hooks
MCP servers
custom commands、agents
output styles、workflows
custom themes、status line、file suggestion

认证、模型、内置工具和权限仍然正常。Managed policy 仍可能生效。

#配置不生效

检查	命令
安装/登录/配置自检	`claude doctor`
当前会话状态	`/status`
settings UI	`/config`
当前上下文加载内容	`/context all`
Hooks 实际状态	`/hooks`
MCP 实际状态	`/mcp`
权限规则来源	`/permissions`
输出风格不生效	改完 `outputStyle` 后 `/clear` 或新会话
状态栏卡顿	检查 `statusLine.command` 是否太慢
OTel 没数据	检查 `CLAUDE_CODE_ENABLE_TELEMETRY`、exporter、endpoint 和 headers

常见文件位置:

内容	位置
用户 settings	`~/.claude/settings.json`
项目 settings	`.claude/settings.json`
本地 settings	`.claude/settings.local.json`
MCP local/user	`~/.claude.json`
MCP project	`.mcp.json`
项目记忆	`CLAUDE.md` 或 `.claude/CLAUDE.md`

#MCP 排错

claude mcp list
claude mcp get <name>
claude mcp login <name>

现象	可能原因
`Pending approval`	`.mcp.json` 需要 workspace trust
OAuth 失败	远程 server 需要重新 `claude mcp login`
stdio 启动失败	命令不存在、环境变量缺失、缺少 `--`
工具输出太长	调整查询,或设置 `MAX_MCP_OUTPUT_TOKENS`
自定义网关下工具不可用	`ENABLE_TOOL_SEARCH` 或网关字段转发问题

#Hooks 排错

现象	检查
完全不触发	`/hooks` 是否加载了对应 settings
只对部分文件不触发	matcher 是否写成 `Edit 和 Write` 这类多工具匹配或正确 regex
命令找不到	用绝对路径或 `${CLAUDE_PROJECT_DIR}`
阻止逻辑无效	`permissionDecision` 是否写在 `hookSpecificOutput`
运行太慢	加 `if` 缩小触发范围

Hook 的空输出不等于批准,只表示继续正常权限流程。

#权限排错

现象	原因
allow 后仍然询问	有 ask 或 deny 命中,它们优先级更高
broad deny 后 allow 不生效	deny 永远优先
Bash 复合命令仍询问	子命令没有全部通过
Read 路径没匹配	`/path` 是 settings 来源相对路径,不是文件系统根
MCP 规则没匹配	工具名应为 `mcp__server__tool`

详见权限与模式。

#缓存和成本异常

现象	解释
换模型后一轮很慢	模型是 cache key
换 `/effort` 后变慢	effort 是 cache key
MCP 连接变化后变慢	工具定义可能进了 system prompt
`/compact` 后 cache creation 增加	conversation 被摘要替换
`cache_read_input_tokens` 总是 0	prompt 太短、前缀变动、provider 或网关不支持