# Agentic 调试

> For the complete documentation index, see [llms.txt](https://www.jetbrains.com/zh-cn/help/clion/llms.txt).

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

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

> **Note:**
> [调试器工具](mcp-server.html#debugger-toolset)在 CLion 2026.1.3 及更高版本中可用。 [Router 模式](#router-mode)在 CLion 2026.2 及更高版本中可用。

Procedure: 启用调试器 MCP 工具包插件

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

1. 按下 `Ctrl+Alt+S` (Windows), `⌘ Comma` (macOS), `⌘ Comma` (IntelliJ IDEA Classic (macOS)), `⌘ Comma` (macOS System Shortcuts), `Ctrl+Alt+S` (XWin), `Ctrl+Alt+S` (GNOME), `Ctrl+Alt+S` (KDE), `Ctrl+Alt+S` (Emacs), `Ctrl+Alt+S` (Sublime Text), `⌘ Comma` (Sublime Text (macOS)), `⌘ Comma` (Xcode), `Ctrl+Alt+S` (Visual Studio), `⌘ Comma` (Visual Studio (macOS)), `Ctrl+Alt+S` (ReSharper), `⌘ Comma` (ReSharper (macOS)), `Ctrl+Alt+S` (QtCreator), `⌘ Comma` (QtCreator (macOS)), `Ctrl+Alt+S` (NetBeans), `Ctrl+Alt+S` (Eclipse), `⌘ Comma` (Eclipse (macOS)) 打开设置，然后选择  `插件` 。

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 服务器提供，服务器启用后客户端即可访问这些工具。

Procedure:

1. 按 [MCP 服务器](mcp-server.html)中的说明启用 MCP 服务器并设置客户端。

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

可在 [MCP 服务器](mcp-server.html)设置中查看已公开的工具，并可为单个工具启用或禁用。

## 开启路由器模式

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

Procedure:

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

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

![CLion 中 MCP 服务器的 Exposed Tools 设置，显示带有已启用和仅路由器复选框的调试器工具。](https://resources.jetbrains.com/help/img/idea/2026.3/cl_agentic_debugging_tools.png)

## 安装调试器技能

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

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

Procedure:

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

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

![CLion 调试器技能](https://resources.jetbrains.com/help/img/idea/2026.3/cl_bundled_skills_debugger.png)

3. 要在 IDE 之外的 Claude Code 或 Codex 中使用该技能，需要为这些客户端显式安装它。 为此，请点击 ![](https://resources.jetbrains.com/help/img/idea/2026.3/app-client.expui.general.chevronDownLarge.svg) 并根据要使用的客户端选择   Claude Agent (全局)   或   Codex (全局)  。

![为外部客户端安装 CLion 调试器技能](https://resources.jetbrains.com/help/img/idea/2026.3/cl_installing_debugger_skill.png)

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

* Claude Code ： Windows: `%USERPROFILE%\.claude\skills\clion-debugger\` macOS: `~/.claude/skills/clion-debugger/` Linux: `~/.claude/skills/clion-debugger/`

* Codex ： Windows: `%USERPROFILE%\.codex\skills\clion-debugger\` macOS: `~/.codex/skills/clion-debugger/` Linux: `~/.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 硬故障](#hardfault)。

## 使用代理调试代码

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

```TEXT
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 变量的值。](https://resources.jetbrains.com/help/img/idea/2026.3/cl_agentic_debugging.png)

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

## 调试 ARM Cortex-M 硬故障

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

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

> **Note:**
> 硬故障调试在 CLion 2026.2.2 及更高版本中可用。

### 代理接收的内容

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

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

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

* 导致故障的内存映射访问背后的外设寄存器，从设备的 [SVD 描述](peripheral-view.html#periph-tab) 解码而来。

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

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

### 查找硬故障的原因

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

Procedure:

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

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

```TEXT
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 寄存器或异常堆栈帧时，代理会自行应用该技能。 如果代理忽略了该技能，请在提示中指明它的名称，以使任务更清晰:

```TEXT
Use the clion-embedded-hardfault skill to find the cause of this fault.
                    
```

3. 代理读取已解码的故障数据，检查内存和反汇编，并将故障指令跟踪到源代码。 然后，它会报告 bug 的位置以及修复方法。

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

## 限制

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

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

* [硬故障调试技能](#hardfault)可在 AI 聊天 工具窗口和 CLI 模式下与 Claude Code 及 Codex 配合使用。 对于 GitHub Copilot，它仅在 CLI 模式下工作。

