llms.txt: machine-readable documentation index. Markdown version of this page is also available.

CLion 2026.3 Help

Agentic 调试

CLion 通过集成的 MCP 服务器向外部 AI 代理公开其调试器。 连接了调试器工具后,Claude、Codex 或 Junie 等代理可以自主驱动 CLion 的调试会话:启动和停止、管理断点、逐步执行代码、检查线程和变量,以及计算表达式。

无需自己步进代码,只需用自然语言描述问题,让代理收集运行时证据。 当需要源代码和日志无法可靠揭示的事实时,这会很有帮助,例如运行时值、分支决策、调用顺序、线程上下文,或程序是否曾运行到某一特定行。

启用调试器 MCP 工具包插件

此功能依赖于调试器 MCP 工具包插件,该插件默认在 CLion 中捆绑并启用。 如果相关功能不可用,请确保您未禁用该插件。

  1. 按下 Ctrl+Alt+S 打开设置,然后选择 插件。

  2. 找到 调试器 MCP 工具包 插件并点击 Enable。

调试器如何访问代理

CLion 以两种方式向代理提供调试器功能:

共享 MCP 服务器

调试器工具与分析、格式设置和其他 IDE 工具一同,通过 MCP 服务器提供。 它们的描述始终在代理上下文中,即使未进行调试。 调试器工具均以 xdebug_ 为前缀。 此选项适用于 CLion 2026.1.3 及更高版本。

路由器模式

MCP 服务器同时公开一个通用工具 execute_tool ,以及 clion-debugger 技能。 命令、参数和调试场景都在该技能中,只有代理需要调试器时才会加载。 调试器描述直到需要时才进入代理上下文,因此路由器模式减少了 token 消耗。 路由器模式支持 GDB、LLDB 和基于 DAP 的调试器,被 Claude Code、Codex 等代理使用。 此选项适用于 CLion 2026.2 及更高版本。

将代理连接到调试器

调试器工具通过 CLion MCP 服务器提供,服务器启用后客户端即可访问这些工具。

  1. 按 MCP 服务器 中的说明启用 MCP 服务器并设置客户端。

  2. 重启客户端以加载 CLion 工具,包括以 xdebug_ 为前缀的调试器工具。

可在 MCP 服务器 设置中查看已公开的工具,并可为单个工具启用或禁用。

开启路由器模式

在路由器模式下,CLion 会将调试器命令描述保持在代理上下文之外,直到代理需要它们。 MCP 服务器同时公开一个通用工具 execute_tool ,代理可按需加载 clion-debugger 技能。 路由器模式适合较长会话,因常驻工具描述会占用代理可用于任务的上下文。

  1. 在主菜单中,进入 设置 | AI | MCP 服务器 | Exposed 工具.

  2. 请选择 启用仅路由器模式 复选框。 调试器工具依旧可通过 execute_tool 访问,且 clion-debugger 技能会告知代理何时使用。 要关闭路由器模式,请取消复选框。

    CLion 中 MCP 服务器的 Exposed Tools 设置,显示带有已启用和仅路由器复选框的调试器工具。

安装调试器技能

为了改进外部客户端使用 IDE 调试器工具的方式,可以为它们安装特定技能。 此技能随 IDE 捆绑提供,并指导外部客户端何时应用调试器工具。

要为外部客户端安装该技能:

  1. 转到 设置 | AI | 技能。

  2. 导航到 捆绑技能 部分并找到 clion-debugger 技能。 它默认已启用,但仅供 IDE 内部的代理使用。

    CLion 调试器技能
  3. 要在 IDE 之外的 Claude Code 或 Codex 中使用该技能,需要为这些客户端显式安装它。 为此,请点击 并根据要使用的客户端选择 Claude Agent (全局) 或 Codex (全局)。

    为外部客户端安装 CLion 调试器技能

根据所选目标,该技能会安装到以下文件夹:

  • Claude Code:

    %USERPROFILE%\.claude\skills\clion-debugger\

    ~/.claude/skills/clion-debugger/

    ~/.claude/skills/clion-debugger/

  • Codex:

    %USERPROFILE%\.codex\skills\clion-debugger\

    ~/.codex/skills/clion-debugger/

    ~/.codex/skills/clion-debugger/

要在外部客户端中调用该技能,请使用 /clion-debugger ,或让它在相关时自动激活。

代理可以执行的操作

通过调试器工具,代理可以像你一样进行运行时调查:

  • 为运行配置或源代码位置启动调试会话,并检查正在运行会话的状态(xdebug_start_debugger_session, xdebug_get_debugger_status)。

  • 列出、设置和移除断点,并运行到指定行(xdebug_list_breakpoints, xdebug_set_breakpoint, xdebug_remove_breakpoint, xdebug_run_to_line)。

  • 通过步进、恢复、暂停或停止会话来控制执行(xdebug_control_session)。

  • 读取局部变量、帧值和嵌套字段,评估或更改表达式(xdebug_get_frame_values, xdebug_get_value_by_path, xdebug_evaluate_expression, xdebug_set_variable)。

  • 检查线程及其调用堆栈(xdebug_get_threads, xdebug_get_stack)。

  • 读取已暂停原生会话的 CPU 寄存器、内存和机器指令(xdebug_get_registers、 xdebug_read_memory、 xdebug_disassemble)。

  • 解码已暂停嵌入式会话的 ARM Cortex-M 故障状态寄存器(xdebug_get_fault_status)。 有关详细信息,请参阅 调试 ARM Cortex-M 硬故障。

使用代理调试代码

打开项目,然后向代理描述问题并让其调试代码。 例如:

The cart total is far too low. Start a debug session, set a breakpoint in line_total(), and find out why the discount is applied incorrectly.

代理会设置所需断点,启动调试会话并等待程序暂停。 当执行停止时,代理会读取调用堆栈、局部变量及需用于假设测试的表达式,然后汇报所发现的信息。

CLion 在 line_total() 的断点处暂停,调试工具窗口显示调用堆栈以及 gross 和 net 变量的值。

代理控制标准 CLion 调试器,可在 调试 工具窗口跟踪会话,并可随时接管。

调试 ARM Cortex-M 硬故障

硬故障是 ARM Cortex-M CPU 异常,当操作在低级别失败时处理器会引发该异常,例如程序访问无效内存地址时。 故障处理程序会捕获堆叠寄存器和故障状态寄存器,但会在不对其解码的情况下停止执行,因此处理器只报告发生了故障,而不说明原因。

捆绑的 clion-embedded-hardfault 技能会将该停止转变为一次调查。 CLion 会解码故障数据并将其交给代理,代理会将发生故障的指令跟踪回源代码,并报告导致故障的原因。

代理接收的内容

CLion 向代理提供以下证据,而不是原始寄存器转储:

  • 故障状态寄存器,已解码为它们所报告的故障条件。

  • 硬件在故障发生时堆叠的异常帧,会在运行中的程序覆盖它之前读取。

  • 导致故障的内存映射访问背后的外设寄存器,从设备的 SVD 描述 解码而来。

  • 故障地址处的反汇编以及周围内存。

CLion 从自身的内存映射、寄存器和指令编码模型构建此数据,因此代理会从故障地址开始,而不是从程序输出中重构它。 数据来自调试器,这使该技能独立于硬件供应商: 它可与用于片上调试的任何工具配合使用,包括 ST-LINK、Segger J-Link 和 Lauterbach TRACE32。

查找硬故障的原因

该技能通过调试器工具工作,因此请先启用 MCP 服务器,如 将代理连接到调试器 中所述。 该技能本身默认在 设置 | AI | 技能 中的 捆绑技能 部分启用。 要在 IDE 之外的客户端中使用它,请按照 安装调试器技能 中所述进行安装。

  1. 对目标进行片上调试,并让程序运行,直到它在故障处理程序中停止。

  2. 用自然语言向代理描述问题,例如:

    This firmware hard faults from time to time, probably on an invalid memory access. Find the cause and tell me how to fix it.

    当会话在 HardFault_Handler、 MemManage_Handler、 BusFault_Handler 或 UsageFault_Handler 中停止,或者提示提到 CFSR、HFSR、MMFAR 或 BFAR 寄存器或异常堆栈帧时,代理会自行应用该技能。 如果代理忽略了该技能,请在提示中指明它的名称,以使任务更清晰:

    Use the clion-embedded-hardfault skill to find the cause of this fault.
  3. 代理读取已解码的故障数据,检查内存和反汇编,并将故障指令跟踪到源代码。 然后,它会报告 bug 的位置以及修复方法。

  4. 自行应用修复,或让代理应用修复并再次运行调试会话以检查结果。

限制

  • 断点错误和日志型断点输出仅由基于 JVM 的调试器报告。 对于 C 和 C++ 调试器,即使配置了日志断点,这些事件流也可能保持为空。

  • 调试会话期间通过调试器工具暂不支持对 constexpr 表达式的计算。

  • 硬故障调试技能可在 AI 聊天 工具窗口和 CLI 模式下与 Claude Code 及 Codex 配合使用。 对于 GitHub Copilot,它仅在 CLI 模式下工作。

2026年 11月 6日