# 第八阶段 · 模块八 · 第二节：调试模式详解
Claude Code 有哪些调试模式？--verbose 和 --debug 有什么区别？如何使用调试信息排查问题？
Claude Code 全局架构
┌─────────────────────────────────────────────────────────────────────┐
│ 调试与日志 │
│ │
│ 调试模式详解 ← 本节 │
│ ├── --verbose ──> 详细输出 │
│ ├── --debug ──> 调试模式 │
│ └── 日志文件 ──> ~/.claude/debug/latest │
└─────────────────────────────────────────────────────────────────────┘
源码位置：`src/main.tsx` 第 976 行
# 方式 1：--verbose
# 显示详细的操作日志
claude --verbose
# 方式 2：--debug
# 显示调试信息和堆栈跟踪
claude --debug
# 方式 3：环境变量
export CLAUDE_CODE_DEBUG=1
claude
| 标志 | 输出级别 | API 日志 | 工具调用 | 堆栈跟踪 |
| 默认 | 最小 | ✗ | ✗ | ✗ |
| --verbose | 详细 | ✓ | ✓ | ✗ |
| --debug | 调试 | ✓ | ✓ | ✓ |
问 1：--verbose 和 --debug 的区别？
// --verbose：详细输出
// - 显示所有调试信息
// - 包括 API 请求/响应摘要
// - 包括工具调用详情
// --debug：调试模式
// - 最详细的信息
// - 包括完整的堆栈跟踪
// - 适合深度排查问题
# 调试日志位置
~/.claude/debug/latest
# 错误日志位置
~/.claude/logs/errors/
# 会话日志位置
~/.claude/logs/sessions/
# 查看实时调试日志
tail -f ~/.claude/debug/latest
# 查看错误日志
tail -f ~/.claude/logs/errors/latest
# 搜索特定错误
grep -i "error" ~/.claude/debug/latest
[DEBUG] 2026-04-02T10:30:00.000Z
Tool call: Read
Input: { "file_path": "a.txt" }
Duration: 45ms
[DEBUG] 2026-04-02T10:30:01.000Z
API Request:
Model: claude-opus-4-5
Messages: 15
Tokens: 3200/200000
[DEBUG] 2026-04-02T10:30:02.000Z
API Response:
Status: 200
Stop reason: tool_use
问 1：日志包含哪些信息？
// 调试日志包含：
// 1. 时间戳
timestamp: '2026-04-02T10:30:00.000Z'
// 2. 操作类型
operation: 'tool_call'
// 3. 操作详情
details: {
tool: 'Read',
input: { file_path: 'a.txt' },
duration: 45,
}
// 4. 结果
result: {
success: true,
output: 'file content...'
}
[DEBUG] API Request
URL: https://api.anthropic.com/v1/messages
Method: POST
Headers:
Authorization: Bearer sk-***
Content-Type: application/json
Body:
model: claude-opus-4-5
max_tokens: 4096
messages: [...]
system: [...]
[DEBUG] API Response
Status: 200
Headers:
x-request-id: abc123
Body:
id: msg_***
model: claude-opus-4-5
stop_reason: tool_use
usage:
input_tokens: 3200
output_tokens: 800
total_tokens: 4000
问 1：Token 使用如何计算？
// 日志中的 usage 字段：
usage:
input_tokens: 3200 // 输入 token 数
output_tokens: 800 // 输出 token 数
total_tokens: 4000 // 总计
// 成本计算
cost = input_tokens * input_price + output_tokens * output_price
[DEBUG] Tool Call
Name: Read
Input: {
"file_path": "src/main.ts",
"limit": 100
}
[DEBUG] Tool Result
Name: Read
Duration: 23ms
Success: true
Output: "file content (truncated to 100 lines)"
[DEBUG] Tool Error
Name: Write
Input: {
"file_path": "protected/file.txt",
"content": "..."
}
Error: Permission denied
Stack:
at Write.execute() line 45
at ToolUseContext.call() line 123
at QueryEngine.process() line 456
问 1：如何过滤日志？
# 只查看特定工具
grep "Tool Call.*Read" ~/.claude/debug/latest
# 排除特定工具
grep -v "Tool Call.*Write" ~/.claude/debug/latest
# 查找错误
grep "Error" ~/.claude/debug/latest
# 按时间过滤
grep "10:30" ~/.claude/debug/latest
[DEBUG] Performance
Tool Execution:
Read: 45ms (avg: 32ms, min: 12ms, max: 120ms)
Write: 120ms (avg: 98ms, min: 45ms, max: 300ms)
Grep: 230ms (avg: 201ms, min: 80ms, max: 500ms)
API Latency:
avg: 450ms
p50: 380ms
p95: 890ms
p99: 1200ms
// 超过阈值的操作会被标记
const SLOW_THRESHOLD = {
tool_call: 5000, // 5秒
api_request: 10000, // 10秒
file_operation: 1000, // 1秒
}
// 日志示例
[WARN] Slow tool call detected
Tool: Grep
Duration: 12000ms (threshold: 5000ms)
问 1：如何诊断慢操作？
# 1. 查看慢操作日志
grep "Slow" ~/.claude/debug/latest
# 2. 查看详细时间
grep "duration" ~/.claude/debug/latest | sort -k2 -n
# 3. 使用 profile
claude --profile
# 查看 MCP 连接日志
grep "MCP" ~/.claude/debug/latest
# 查看连接错误
grep -i "connect.*error" ~/.claude/debug/latest
[DEBUG] Auth
Method: OAuth
Token: sk-***...1234 (valid)
Expires: 2026-04-02T12:00:00Z
[ERROR] Auth failed
Error: Token expired
Solution: Run `claude auth refresh`
[DEBUG] Permission check
Tool: Write
Input: { "file_path": "/etc/passwd" }
Result: Denied
Reason: Protected system file
[DEBUG] Permission check
Tool: Bash
Input: { "command": "rm -rf /" }
Result: Denied
Reason: Dangerous command
答案：
// 会，但可接受
// 性能开销：
// - 日志写入：约 1-5%
// - 日志传输：约 1-2%
// - 堆栈跟踪（--debug）：额外 5-10%
// 建议：
// - 正常使用时关闭调试模式
// - 排查问题时启用
// - 排查完成后及时关闭
答案：
# 保存调试日志到文件
claude --verbose 2>&1 | tee debug.log
# 或重定向到文件
claude --verbose > debug.log 2>&1
# 按时间保存
claude --verbose 2>&1 | gzip > debug-$(date +%Y%m%d-%H%M%S).log.gz
# 使用 --debug-file 指定日志文件
claude --debug --debug-file ./my-debug.log
答案：
# 1. 设置远程日志服务器
export CLAUDE_DEBUG_SERVER=wss://debug.example.com
# 2. 启用远程调试
claude --verbose
# 3. 在远程查看
# 打开 https://debug.example.com/view/<session-id>
| 资源 | 说明 |
| Debugging Guide | https://docs.anthropic.com/claude-code/debugging |
| 日志分析工具 | 内置 `claude logs analyze` |
下一节我们将进入 第九阶段：高级主题：
- 多模态能力
- 思维链提示
- 代码库索引
*- 第一轮：□ 事实准确性*
*- 第二轮：□ 深度与洞见*
*- 第三轮：□ 可读性与价值*