6.19 日志系统

Claude Code 提供完善的日志记录系统，帮助您追踪、调试和分析代理的运行情况。了解日志系统的配置和使用对于故障排除和性能优化至关重要。

概述

Claude Code 通过 JSONL 格式记录大量日志信息。这些日志包含用户发出的所有请求以及其他信息（如工具调用）。虽然日志有时较难直接阅读，但它们为调试和分析提供了宝贵的数据。

日志文件位置

Claude Code 项目日志存储在以下目录：

# 日志目录
~/.claude/projects/

# 该目录包含：
# - 合并的会话记录
# - 单独的会话文件

详细模式（Verbose Mode）

当您在命令中添加 --verbose 标志时，系统会激活多个组件的详细日志记录：

# 启用详细日志模式
claude --verbose

# 详细模式输出内容包括：
# - 参数解析过程
# - 验证检查
# - 初始配置加载
# - 项目结构扫描
# - 上下文窗口构建
# - 文件优先级信息

详细输出解析

详细输出首先显示 Claude Code 如何解释您的命令：

• 参数解析 - 显示命令参数的处理过程
• 验证检查 - 显示验证步骤和结果
• 配置加载 - 显示初始配置的加载过程

这有助于在命令语法问题或缺少参数导致失败之前识别问题。

上下文和项目扫描

Claude Code 的详细模式会显示它如何扫描项目结构。您将看到：

• 识别了哪些文件
• 如何构建上下文窗口
• 哪些信息被优先处理

MCP 调试标志

在使用 MCP（模型上下文协议）时，可以使用 --mcp-debug 标志启动 Claude 来帮助识别配置问题：

# 启用 MCP 调试模式
claude --mcp-debug

# 调试集成问题时
# 详细输出会显示：
# - 认证流程
# - 连接尝试
# - 协议级通信

日志记录命令示例

以下是一些常用的日志记录命令：

# 基本用法，完整提示可见性
npm run dev -- start --verbose

# 带调试信息
npm run dev -- start --debug

# 记录到文件
npm run dev -- start 2>&1 | tee claude-session-$(date +%Y%m%d-%H%M%S).log

HTTP/HTTPS 代理调试

HTTPS_PROXY/HTTP_PROXY 可用于调试，允许用户检查原始流量以查看 Claude 发送的确切提示：

# 设置代理进行流量检查
export HTTPS_PROXY=http://localhost:8080

# 对于后台代理，这也是细粒度网络沙盒的强大工具

安全日志记录

Claude Code 2.1.0 之前的版本会在调试日志中暴露 OAuth 令牌、API 密钥和密码，这是一个已被修复的关键安全问题。现在敏感信息会被正确过滤。

审计日志

Claude Code 的钩子系统支持审计日志记录功能：

• PreToolUse 钩子 - 工具使用前的日志记录
• PostToolUse 钩子 - 工具使用后的日志记录
• Stop 钩子 - 会话停止时的日志记录

这为开发人员提供了对状态管理、工具约束和审计日志记录的细粒度控制，减少了意外行为并使代理操作更容易调试和重现。

后台代理日志

后台代理进程的日志记录对于调试或监控长时间运行的任务（如 Python 脚本的日志输出）非常有帮助。

# 后台代理提供全面的任务活动可见性
# 跟踪执行历史
# 记录安全相关事件以满足合规要求

配置文件位置参考

文件	用途
~/.claude/settings.json	用户设置（权限、钩子、模型覆盖）
.claude/settings.json	项目设置（提交到源代码控制）
.claude/settings.local.json	本地项目设置（不提交）
~/.claude.json	全局状态（主题、OAuth、MCP 服务器）