# 智能体调试

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

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

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

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

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

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

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)), `Ctrl+Alt+S` (Visual Studio), `⌘ Comma` (Visual Studio (macOS)), `Ctrl+Alt+S` (NetBeans), `Ctrl+Alt+S` (Eclipse), `⌘ Comma` (Eclipse (macOS)) 打开设置，然后选择  `插件` 。

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

## 调试器如何连接到智能体

IntelliJ IDEA 通过两种方式向智能体提供调试器函数／方法：

共享 MCP 服务器
: 调试器工具通过 MCP 服务器与分析、格式设置和其他 IDE 工具一起提供。 这些描述始终是智能体上下文的一部分，即使未进行调试也是如此。 调试器工具带有  `xdebug_`  和  `jvm_debug_`  前缀。 此选项在 IntelliJ IDEA 2026.1.3 及更高版本中可用。

路由模式
: MCP 服务器公开一个通用工具  `execute_tool` ，以及  `ij-debugger`  技能。 所有标记为仅限路由的工具（包括调试器工具）都会对代理隐藏，并且只能通过  `execute_tool`  访问。 命令、形参和调试场景位于该技能中，智能体仅在需要调试器时才会加载它们。 由于在此之前调试器描述不会进入智能体上下文，路由模式可降低令牌消耗。 此选项在 IntelliJ IDEA 2026.2 及更高版本中可用。

## 将智能体连接到调试器

调试器工具通过 IntelliJ IDEA MCP 服务器提供，因此一旦启用服务器，客户端即可访问这些工具。

Procedure:

1. 启用 MCP 服务器，并按照 [MCP 服务器](mcp-server.html) 中所述设置客户端。

2. 重新启动客户端，以便它获取 IntelliJ IDEA 工具，包括带有  `xdebug_`  和  `jvm_debug_`  前缀的调试器工具。

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

## 启用路由模式

在路由模式下，IntelliJ IDEA 会将仅限路由的工具（包括调试器工具）的描述排除在代理上下文之外，直到代理需要这些工具。 MCP 服务器公开一个通用工具  `execute_tool` ，智能体会按需加载  `ij-debugger`  技能。 路由模式适合较长的会话，在这类会话中，始终开启的工具描述会占用本可供智能体用于任务的上下文。

Procedure:

1. 在主菜单中，前往  `设置 | 工具 | MCP 服务器 | 暴露工具` 。

2. 请选择   启用仅路由器模式   复选框。 调试器工具仍可通过  `execute_tool`  访问，  `ij-debugger`  技能会告诉智能体何时使用这些工具。 要关闭路由模式，请清除该复选框。

路由模式适用于已选择   仅路由器   选项的工具。 默认情况下，会为调试器工具选择该选项。

![MCP 服务器的“已公开工具”设置，显示 IntelliJ IDEA 中调试器工具的“已启用”和“仅路由”复选框已选中。](https://resources.jetbrains.com.cn/help/img/idea/2026.3/cl_agentic_debugging_tools.png)

## 安装调试器技能

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

> **Note:**
> 如果已安装并启用 [AI 助手](ai-assistant-in-jetbrains-ides.html) 插件，则对应的调试器技能可用。

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

Procedure:

1. 前往  `设置 | 工具 | 技能` 。

2. 导航到   捆绑技能   部分并找到  `ij-debugger`  技能。 它默认启用，但仅对 IDE 内部的智能体可用。

![ij-调试器技能](https://resources.jetbrains.com.cn/help/img/idea/2026.3/ai_bundled_skills_debugger.png)

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

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

根据选择的目标，该技能会安装到以下文件夹：

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

* Codex ： Windows: `%USERPROFILE%\.codex\skills\ij-debugger\` macOS: `~/.codex/skills/ij-debugger/` Unix / Linux: `~/.codex/skills/ij-debugger/`

要在外部客户端中调用该技能，请使用  `/ij-debugger` ，或在合适时自动激活。

## 使用智能体调试代码

通过调试器工具，代理可以：

* 为运行配置或源位置启动调试会话，重用正在运行的会话，或将调试器附加到正在运行的本地进程。

* 设置、静音和移除 [断点](using-breakpoints.html) 与 [日志点](logpoints.html)，设置方法和异常断点，并运行到特定行。

* 逐步执行代码，并暂停、恢复或停止会话。

* 检查线程、调用堆栈和变量，捕获线程转储，对表达式求值，并更改变量值。

* 读取被调试进程的输出。

代理会跟踪它设置的断点以及手动设置的断点。 完成后，它只会移除自己设置的断点。

首先，打开项目并向代理描述问题。 当任务需要运行时证据时，代理会自行应用  `ij-debugger`  技能。 要显式调用该技能，请在 Claude Code 中以  `/ij-debugger`  开头编写提示，或在 Codex 中以  `$ij-debugger`  开头。

![以 /ij-debugger 开头的 Claude Code 提示词，用于调用调试器技能，以便在 IntelliJ IDEA 中进行运行时调查法律保持助手? Wait final has weird? I need correct. I accidentally typed not done. Need final valid JSON. Use commentary? We need final only. Let's produce. Ensure no Japanese style. Need no extra ](https://resources.jetbrains.com.cn/help/img/idea/2026.3/logpoints-skill.png)

例如：

```TEXT
Adding a pet whose name only differs in case from one an owner
already has is not rejected as a duplicate. Start a debug session,
set a breakpoint in Owner.getPet(), and find out why the duplicate
check misses it.
        
```

智能体会设置所需的断点，启动调试会话，并等待程序暂停。 执行停止时，它会读取调用堆栈、局部变量以及测试其假设所需的表达式，然后报告发现的内容。

![IntelliJ IDEA 在 getPet() 的断点处暂停，调试工具窗口显示调用堆栈以及不匹配的名称和 compName 变量值](https://resources.jetbrains.com.cn/help/img/idea/2026.3/ij_agentic_debugging.png)

智能体控制标准 IntelliJ IDEA 调试器，因此可以在   调试   工具窗口中跟踪会话，并随时接管。