它到底是什么

--debug 是 Claude Code 的 CLI 启动 flag，用来开启 debug 模式，并可选择按类别（category）过滤日志。官方 CLI reference 的原文描述：

Enable debug mode with optional category filtering, such as --debug='mcp,startup' or --debug='!1p'. The filter binds only in the = form; a space-separated filter enables debug mode without filtering

要点：

• 过滤器是可选的；不带过滤器时，只是开启 debug 模式而不做过滤。
• 过滤器用逗号分隔多个类别，前缀 ! 表示排除该类别（官方示例 --debug='!1p'）。
• 过滤器只在 = 形式下生效。 空格分隔的写法只会开启 debug 模式，不做过滤。
• 官方文档没有列出完整的类别清单，只在示例里出现了 mcp、startup、1p。api 是否为有效类别，本文的来源无法确认。

用法

# 开启 debug,不过滤
claude --debug

# 只看指定类别(官方示例)
claude --debug='mcp,startup'

# 排除某类别(官方示例)
claude --debug='!1p'

# 排查 MCP server 时(官方 debug 指南中的用法)
claude --debug=mcp

注意任务给定的示例 claude --debug "api,mcp" 是空格分隔写法。 按官方 CLI reference，这种写法只会开启 debug 模式，"api,mcp" 不会被当作过滤器。要过滤请写成 claude --debug="api,mcp"。不过 api 这个类别名本身未在官方文档中出现。

相关的 slash 命令：/debug [issue] 会在当前会话内启用 debug 日志，并让 Claude 根据日志输出和 settings 路径来诊断问题。

与其他 flag 的组合 / 互斥

官方文档没有写 --debug 与 --debug-file 同时使用时的具体交互，本文不做推断。

在 settings.json / env 的等价配置

运行约束 / 限制

经典使用场景

• 排查 MCP server:/mcp 显示 server 已连接但工具数为 0，点 Reconnect 后仍为 0，则运行 claude --debug=mcp，在 ~/.claude/debug/<session-id>.txt 中查看该 server 的 stderr。（官方 debug 指南）
• 排查 Hook 不触发：/hooks 中能看到 Hook 但不触发时，用 claude --debug 启动会话并触发对应 tool call。官方指南称日志会记录每个事件、检查过哪些 matcher，以及 Hook 的 exit code 和输出。
• 持久化日志：用 --debug-file <path> 把日志写到固定路径，便于会话结束后查看或附到问题报告里。

常见坑

• 空格写法不过滤：claude --debug "mcp" 只是开启 debug，日志里仍是全部类别。要过滤必须写 --debug=mcp。
• --debug-file 优先于 CLAUDE_CODE_DEBUG_LOGS_DIR：两者同时设置时，以 --debug-file 为准。

来源

• CLI reference - Claude Code Docs（docs.claude.com/en/docs/claude-code/cli-reference 会 301 跳转到此）
• Debug your configuration - Claude Code Docs
• Environment variables - Claude Code Docs
• Hooks reference - Claude Code Docs（该页面的 "Debug hooks" 小节介绍用 --debug-file 捕获 Hook 执行的调试日志）