# Claude Code 常见问题

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

URL: https://docs.passion8.cc/docs/claude-code/troubleshooting
Language: zh-CN
Publisher: Passion8

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

安装、PATH、登录和 OAuth 问题先看 [安装与登录排错](https://docs.passion8.cc/docs/claude-code/install-troubleshooting)。运行时 HTTP/API 错误、500、529、限流、请求过大和模型错误看 [错误参考](https://docs.passion8.cc/docs/claude-code/error-reference)。settings、Hooks、MCP 和记忆未生效看 [配置调试与 .claude 目录](https://docs.passion8.cc/docs/claude-code/configuration-debugging)。

## 快速排错表

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




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




## 最小连通性测试

先在一个干净目录里跑:

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

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

## 干净配置目录

怀疑本机配置污染时:

```bash
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` 会禁用大多数自定义项,用于确认是不是配置导致问题:

```bash
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 排错

```bash
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` |

详见 [权限与模式](https://docs.passion8.cc/docs/claude-code/permissions)。

## 缓存和成本异常

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

详见 [Prompt 缓存](https://docs.passion8.cc/docs/claude-code/prompt-caching)。

## 官方参考

- [Debug your configuration](https://code.claude.com/docs/en/debug-your-config.md)
- [Troubleshoot installation and login](https://code.claude.com/docs/en/troubleshoot-install.md)
- [Troubleshooting](https://code.claude.com/docs/en/troubleshooting.md)

## 相关页面



- [安装与登录排错](https://docs.passion8.cc/docs/claude-code/install-troubleshooting): 处理 CLI 安装、PATH、代理/TLS、Windows/WSL、Docker 和 OAuth 登录问题。
- [错误参考](https://docs.passion8.cc/docs/claude-code/error-reference): 按错误类型定位 500、529、429、认证、网络、请求过大和模型配置问题。
- [配置调试与 .claude 目录](https://docs.passion8.cc/docs/claude-code/configuration-debugging): 确认 settings、Hooks、MCP、Skills、权限和本地数据实际加载情况。