--verbose 参数

概述

--verbose 标志启用详细的日志记录，显示 Claude Code 执行过程中的详细信息。这对于调试、问题排查和理解系统行为非常有用。

标志语法

claude --verbose

日志级别

级别	描述	使用场景
默认	只显示必要的信息	正常使用
`--verbose`	显示详细日志	调试和问题排查
`--verbose --verbose`	显示更详细的日志	深度调试

使用场景

调试工具调用

# 查看工具调用的详细信息
claude --verbose -p "读取项目中的所有 Python 文件"

# 输出会显示：
# - 哪些工具被调用
# - 工具调用的参数
# - 工具调用的结果

问题排查

# 当遇到问题时，使用详细日志
claude --verbose -p "生成代码"
# 可以看到：
# - 请求的详细信息
# - 响应的状态
# - 错误信息（如果有）

性能分析

# 分析性能瓶颈
claude --verbose -p "处理大量数据"

# 可以看到：
# - 每个操作的耗时
# - 数据传输的大小
# - 系统资源使用情况

理解系统行为

# 了解 Claude Code 的工作原理
claude --verbose -p "解释这段代码"
# 可以看到：
# - 如何解析请求
# - 如何选择工具
# - 如何生成响应

高级用法

与其他标志组合

# 详细日志 + JSON 输出
claude --verbose --output-format json -p "分析代码"

# 详细日志 + 限制工具
claude --verbose --allowedTools "Read" "Grep" -p "搜索代码"

# 详细日志 + 自定义系统提示
claude --verbose --system-prompt "你是一位 Python 专家" -p "编写代码"

保存详细日志

# 将详细日志保存到文件
claude --verbose -p "生成代码" 2>&1 | tee verbose.log
# 只保存错误日志
claude --verbose -p "生成代码" 2> error.log

过滤日志

# 只显示错误日志
claude --verbose -p "生成代码" 2>&1 | grep -i "error"

# 只显示工具调用
claude --verbose -p "生成代码" 2>&1 | grep "tool"

# 只显示时间戳
claude --verbose -p "生成代码" 2>&1 | grep -E "^[0-9]{4}-[0-9]{2}-[0-9]{2}"

实时监控

# 实时监控日志输出
claude --verbose -p "生成代码" | tee -a monitor.log
# 使用 tail 实时查看日志
claude --verbose -p "生成代码" > log.txt &
tail -f log.txt

实际应用示例

示例 1: 调试脚本

#!/bin/bash
# debug-script.sh

echo "开始调试..."
echo "详细日志将保存到 debug.log"

# 运行命令并保存详细日志
claude --verbose -p "生成代码" 2>&1 | tee debug.log

# 分析日志
echo "分析日志..."
grep -i "error" debug.log
grep "tool" debug.log | wc -l

echo "调试完成"

示例 2: 性能分析

#!/bin/bash
# performance-analysis.sh
echo "开始性能分析..."
# 记录开始时间
START_TIME=$(date +%s)
# 运行命令并保存详细日志
claude --verbose -p "处理大量数据" 2>&1 | tee performance.log
# 记录结束时间
END_TIME=$(date +%s)
# 计算总耗时
DURATION=$((END_TIME - START_TIME))
echo "总耗时: $DURATION 秒"
# 分析性能日志
echo "工具调用次数:"
grep "tool" performance.log | wc -l
echo "数据传输量:"
grep "bytes" performance.log | awk '{sum+=$2} END {print sum " bytes"}'

示例 3: 错误追踪

#!/bin/bash
# error-tracker.sh

echo "开始追踪错误..."

# 运行命令并保存详细日志
claude --verbose -p "生成代码" 2>&1 | tee error.log

# 提取错误信息
echo "发现的错误:"
grep -i "error" error.log | nl

# 提取警告信息
echo "发现的警告:"
grep -i "warning" error.log | nl

# 统计错误和警告数量
ERROR_COUNT=$(grep -ic "error" error.log)
WARNING_COUNT=$(grep -ic "warning" error.log)

echo "错误总数: $ERROR_COUNT"
echo "警告总数: $WARNING_COUNT"

示例 4: 日志分析工具

#!/bin/bash
# log-analyzer.sh
LOG_FILE=$1
if [ -z "$LOG_FILE" ]; then
  echo "用法: $0 <日志文件>"
  exit 1
fi
echo "分析日志文件: $LOG_FILE"
echo "---"
# 统计工具调用
echo "工具调用统计:"
grep "tool" "$LOG_FILE" | awk '{print $2}' | sort | uniq -c | sort -rn
echo "---"
# 统计错误
echo "错误统计:"
grep -i "error" "$LOG_FILE" | wc -l
echo "---"
# 统计警告
echo "警告统计:"
grep -i "warning" "$LOG_FILE" | wc -l
echo "---"
# 显示时间范围
echo "时间范围:"
grep -E "^[0-9]{4}-[0-9]{2}-[0-9]{2}" "$LOG_FILE" | head -1
grep -E "^[0-9]{4}-[0-9]{2}-[0-9]{2}" "$LOG_FILE" | tail -1

日志内容说明

1. 请求日志

[2024-01-15 10:30:00] INFO: Request received
[2024-01-15 10:30:00] INFO: Query: "生成代码"
[2024-01-15 10:30:00] INFO: Model: claude-opus-4-5

2. 工具调用日志

[2024-01-15 10:30:01] INFO: Tool called: Read
[2024-01-15 10:30:01] INFO: Parameters: {"file_path": "src/main.py"}
[2024-01-15 10:30:01] INFO: Result: Success

3. 响应日志

[2024-01-15 10:30:02] INFO: Response generated
[2024-01-15 10:30:02] INFO: Tokens: 150
[2024-01-15 10:30:02] INFO: Duration: 1.5s

4. 错误日志

[2024-01-15 10:30:03] ERROR: Tool failed: Write
[2024-01-15 10:30:03] ERROR: Error: Permission denied

最佳实践

1. 选择合适的日志级别

# 正常使用：不需要详细日志
claude -p "生成代码"

# 调试问题：使用详细日志
claude --verbose -p "生成代码"

# 深度调试：使用更详细的日志
claude --verbose --verbose -p "生成代码"

2. 保存日志以便分析

# 为每次运行创建单独的日志文件
LOG_FILE="claude-$(date +%Y%m%d-%H%M%S).log"
claude --verbose -p "生成代码" 2>&1 | tee "$LOG_FILE"

3. 定期清理日志

# 清理 7 天前的日志
find . -name "claude-*.log" -mtime +7 -delete

4. 使用日志分析工具

# 使用 grep 过滤日志
claude --verbose -p "生成代码" 2>&1 | grep "ERROR"
# 使用 awk 分析日志
claude --verbose -p "生成代码" 2>&1 | awk '{print $1, $2, $5}'
# 使用 sed 格式化日志
claude --verbose -p "生成代码" 2>&1 | sed 's/INFO:/\x1b[32mINFO:\x1b[0m/g'

常见问题

问题	答案
详细日志会影响性能吗？	会有轻微的性能影响，因为需要记录更多的信息。但对于大多数应用场景来说，影响可以忽略不计。
如何只查看特定类型的日志？	使用 grep 过滤日志输出：`claude --verbose -p "生成代码" 2>&1 \| grep "ERROR"`
日志文件会变得很大吗？	会。建议定期清理旧日志，或者使用日志轮转工具。
可以自定义日志格式吗？	不可以直接自定义。但可以使用 sed、awk 等工具格式化日志输出。
如何在日志中添加自定义信息？	可以在命令中添加 echo 语句：`echo "开始处理..." \| tee -a log.txt && claude --verbose -p "生成代码" 2>&1 \| tee -a log.txt && echo "处理完成" \| tee -a log.txt`

与其他工具的集成

1. 与 grep 集成

# 过滤错误日志
claude --verbose -p "生成代码" 2>&1 | grep -i "error"

# 过滤工具调用
claude --verbose -p "生成代码" 2>&1 | grep "tool"

2. 与 awk 集成

# 提取特定字段
claude --verbose -p "生成代码" 2>&1 | awk '{print $1, $5}'
# 统计工具调用次数
claude --verbose -p "生成代码" 2>&1 | awk '/tool/ {count++} END {print count}'

3. 与 sed 集成

# 高亮显示错误
claude --verbose -p "生成代码" 2>&1 | sed 's/ERROR:/\x1b[31mERROR:\x1b[0m/g'

# 格式化时间戳
claude --verbose -p "生成代码" 2>&1 | sed 's/\[//g' | sed 's/\]//g'

4. 与日志管理工具集成

# 使用 logrotate 管理日志
# /etc/logrotate.d/claude
/path/to/claude-*.log {
  daily
  rotate 7
  compress
  missingok
  notifempty
}

--verbose 参数

On this page