# 配置 Agent 集成

> **说明**
> 本页按 Pebrel 2.1.1 核对。设置页里的"Hook"是各工具对"事件入口"的称呼，本页统一叫"集成"。

## 先了解默认行为

集成让工具在开始、结束或需要你处理时主动告诉 Pebrel，Pebrel 据此更新标签和窗格上的活动提示，并发出通知。它在 Windows、macOS 和 Linux 上都可以使用。

- **Claude Code 和 Codex 默认开启。** 只要它们安装在这台电脑上，Pebrel 会自行在它们的配置里写入集成入口，通常不需要你操作。
- **其他工具默认关闭。** 需要在 **设置 → Agents** 里自己打开，包括 OpenCode、Cursor Agent、Kimi Code、Pi、Oh My Pi、GitHub Copilot 和 Grok。
- **集成只在 Pebrel 里起作用。** 在 Pebrel 之外的终端运行同一个工具，不会发生任何变化。

各工具具体支持哪些功能，见[支持的 AI 命令行工具](/docs/agents/)。

## OSC 7501 与版本范围

**2026-10-21 合入主线，尚未包含在 v2.2.2 发布包中。** 支持的客户端实际发送有效报告时，桌面 Windows、macOS、Linux 的本地 PTY 和内置 SSH 共用 OSC 7501 状态解析。

状态选择顺序是：真实的窗格或连接失败优先，其次有效 OSC 7501，然后 Hook，最后屏幕与进程启发式。协议可表达空闲、进行、完成、阻塞、报错，并细分权限、问题和认证请求。各客户端、版本和终端复用链路的发送能力不同，不保证每个工具都报告五种状态。

Hook 继续提供会话身份、回答捕获和可操作的权限请求。单独收到协议状态不等于能够自动执行权限操作，也不代表会产生所有 Hook 通知。

Android 远控可以继承桌面的任务状态；手机独立终端和直连 SSH 尚未接入这条状态投影。macOS 和 Linux 的原生任务栏进度也不等同于桌面标签状态。

## 在设置里查看和开关

打开 **设置 → Agents**，页面标题是"编程智能体"。每个工具占一行，从左到右依次是：

- 工具图标和名称；
- Pebrel 找到的程序路径，鼠标停在路径上可以看到完整内容；找不到时显示"未安装"；
- 当前状态；
- 一个开关。

1. 先在终端里启动一次要用的工具，让它完成初始配置。工具还没有创建过配置时，这一行会提示"请先运行一次此工具以创建配置，然后刷新"。
2. 点击右上角的 **刷新**，重新检测。
3. 打开这个工具的开关。点击整行也可以切换。
4. 看到"Hooks 已安装，请重启 agent 使其生效"后，退出并重新启动这个工具。
5. 提交一个简短任务，检查标签上的状态是否随任务变化。

只需要打开自己用的工具。开关灰着无法点击，通常是因为 Pebrel 还没有找到这个工具，或它还没有创建过配置。

### 状态的含义

| 状态 | 含义 | 怎么处理 |
| --- | --- | --- |
| Hook 已安装 | 集成已经就绪 | 重启工具后即可使用 |
| Hook 未安装 | 工具已找到，集成处于关闭状态 | 需要时打开开关 |
| Hook 已安装 · 需修复 | 入口还在，但内容与当前版本不一致，例如工具更新时改写过配置 | 关闭再打开一次 |
| 需要检查 | 读取或写入这个工具的配置时出错，原因会显示在这一行 | 看提示，检查配置文件的权限，再刷新 |
| 处理中… | 正在写入或移除 | 稍候 |

如果提示"缺少 hook 辅助程序，请修复 Pebrel 安装后再启用"，说明 Pebrel 自带的辅助程序没有找到，重新安装 Pebrel 即可。

## 开启后会改动什么

Pebrel 只写入属于自己的条目，不会改动你已有的其他配置：

| 工具 | 修改位置（均在用户目录下） |
| --- | --- |
| Claude Code | `.claude/settings.json`，设置了 `CLAUDE_CONFIG_DIR` 时用该目录 |
| Codex | `.codex/` 下的 `config.toml` 和 `hooks.json` |
| OpenCode | `.config/opencode/plugins/pebrel.js` |
| Pi | `.pi/agent/extensions/pebrel.ts` |
| Oh My Pi | `.omp/agent/extensions/pebrel.ts` |
| Kimi Code | `.kimi-code/config.toml` |
| Cursor Agent | `.cursor/hooks.json` |
| GitHub Copilot | `.copilot/hooks/pebrel.json` |
| Grok | `.grok/hooks/pebrel.json` |

这些文件属于对应工具自己的配置。开关处于打开状态时，如果工具升级或别的程序改动了它们，Pebrel 会检测到并把自己的条目补回；你主动关闭的工具不会被补回。

对于 Claude Code 和 Codex，Pebrel 还会放入一个名为 `pebrel-runtime` 的技能，让它们在对话里直接操作 Pebrel，例如分屏、打开文件或把任务交给另一个窗格里的工具，用法见[命令行控制与自动化](/docs/runtime/)。你修改过的技能文件不会被覆盖。

## 关闭集成

在 **设置 → Agents** 关闭该工具的开关，再重启工具。出现"Hooks 已移除，请重启 agent 使其生效"，表示已经移除。关闭后仍可在终端里正常运行这个工具，在 v2.2.2 中活动提示会退回到[屏幕识别](/docs/agents/)；支持 OSC 7501 的后续版本仍可使用有效协议报告。

想一次移除所有工具的集成，在终端运行：

```sh
pebrel setup-ai --remove
```

它只移除 Pebrel 写入的条目，保留其他集成。不带 `--remove` 再运行一次，会重新为 Claude Code、Codex 以及你在设置里打开过的工具写入集成。

## WSL 与 SSH

**设置 → Agents** 只管理这台电脑上的工具。WSL 和服务器上的工具有各自的配置，由下面的方式处理。

- **通过 Pebrel 的 SSH 连接：** 连接时会自动检查服务器，为其中已安装的 Claude Code、Codex、OpenCode 和 Pi 配置集成。这一步失败不会影响你正常使用终端。需要手动处理时运行 `pebrel setup-ai --ssh 主机别名或user@host`；加上 `--remove` 会移除，并记住这台主机不再自动配置。
- **WSL：** 在 Windows 上打开 WSL 终端时，会为发行版里的 Claude Code 和 Codex 配置集成。手动运行 `pebrel setup-ai --wsl 发行版名称`，需要指定用户时再加 `--wsl-user 用户名`。Codex 可能会要求你在它的 `/hooks` 里确认这些入口。

SSH 和 WSL 里的其他工具仍可使用，只是没有集成，状态提示依赖屏幕识别。

## 工具没有被检测到

先在准备使用它的终端里运行工具命令。命令找不到时，修复安装和 PATH；命令可用，再点 **刷新**。

确认安装的是目标 CLI。例如，Cursor 桌面程序的 `cursor` 命令不等于 Cursor Agent CLI，后者的命令是 `agent`。工具刚升级过时，重新启动 Pebrel 和工具可以清除旧的检测与运行状态。

## 收不到任务通知

先确认工具已在启用集成后重启，再检查 **设置 → 终端 → 提醒** 里的通知选项。任务状态能更新但卡片没有出现时，通常应继续检查通知显示设置，而不是重新安装工具。

通知时长、点击跳回来源窗格和系统通知见[通知](/docs/notifications/)。

---
Source: Kuddev/pebrel PR #291, WilliamWang1721 and Pebrel contributors.
Adapted for pebrel.com. License: GPL-3.0.
