# CLI 代理

在写作工作区内使用你已经在终端中运行的代理。

把你已安装的代理带进 Oleafly。**CLI 代理**模式使用该代理自己的运行时和登录状态，让你可以用已经熟悉的工具在稿件旁边工作。

![设置 → AI 助手 → CLI 代理。在顶部检查已安装的代理，然后展开某个代理完成它的设置。](https://cdn.oleafly.com/images/screenshots/desktop/docs/settings-cli-agents-dark-window-v2.png#view=519,89,883,902)

## 连接代理

1. 打开**设置 → AI 助手 → CLI 代理**，选择**检查已安装的代理**。
2. 展开你的代理。**程序**一行显示 Oleafly 找到的程序及其位置。
3. 选择**测试**。如果卡片要求安装桥接程序，请先选择**安装桥接程序**。
4. 通过代理自己的命令行工具登录。卡片会显示它的**登录命令**；打开项目后，**打开登录终端**会给你一个用来运行该命令的终端。
5. 打开助手，切换到 **CLI 代理**，并选择该代理。
6. 从一个小任务开始，例如解释项目结构，或修改一个段落。

如果你切换到一个尚未就绪的代理，助手会显示一张设置卡片，说明缺少什么。它的**设置**按钮，例如**设置 Claude Code**，会在设置中打开该代理。如果只缺少桥接程序，卡片上的**安装桥接程序**会安装它。

身份验证、模型访问和计费都归所选的代理管理。支持该 CLI 的账户或订阅，可以按该提供商的条款使用；Oleafly 不会另外增加 AI 订阅。

## 选择程序

在**程序**标签下，卡片会显示 Oleafly 启动的文件及其来源：**自动检测到**、**由你选择**或**由 Oleafly 安装**。对于某些代理，这一行改为位于 **ACP 桥接**详情内。

要使用另一份副本，请点击 **选择…**，然后选取该文件。如果 Oleafly 什么也没找到，这一行会显示**未在这台电脑上找到**，并给你一个填写位置的字段。输入或粘贴路径，然后按 Enter 或选择**测试**。你选取或输入的文件只有在通过测试后才会保存。**使用自动检测**会放弃你的选择。

Oleafly 会在安装程序放置代理的文件夹中查找：

- 在 Windows 上，它能找到用 npm、pnpm、Scoop、winget 和类似工具安装的代理，无论在哪个盘上。它每次都会重新读取搜索路径，所以**检查已安装的代理**也能找到你在 Oleafly 打开期间安装的代理。
- 在 macOS 上，它能找到通常只有你的 shell 才知道的文件夹中的代理，例如 `~/.local/bin` 或 nvm 文件夹，即使你是从 Dock 或访达打开 Oleafly 的。

当 Oleafly 找到一个名称正确但无法使用的文件时，设置会告诉你它找到了什么以及原因。Windows 上常见的情况是：找到的是 PowerShell 脚本，而 Oleafly 需要 `.cmd` 或 `.exe` 版本。**Oleafly 跳过的文件**会列出每个这样的文件及其原因，例如它是文件夹、桌面应用、`node` 之类的 shell 或运行时，或是位于网络位置的副本。

设置中的路径在你把鼠标悬停在上面或用 Tab 键切换到它们之前会保持模糊，因此设置的截图不会暴露你的文件存放在哪里。

## 测试代理

**测试**会在一个属于 Oleafly 的空文件夹中（远离你的项目）启动代理，并等待它作答。它不会保存任何内容。通过时，你会看到代理的名称和版本。失败时，你会得到一句话说明原因，以及一件可以尝试的事：

| 测试报告的情况 | 可以尝试的做法 |
| --- | --- |
| 那里没有文件，或是文件夹、桌面应用，或是 Oleafly 无法启动的文件 | 点击 **选择…**，然后选取程序本身 |
| 尚未安装桥接程序 | **安装桥接程序** |
| 代理需要 Node.js，或需要更新版本的 Node.js | **获取 Node.js** |
| 代理启动了但没有作答、提前停止，或发送了 Oleafly 无法读取的回复 | **复制详细信息**，或**打开终端**自己运行它 |

如果你选择的文件因文件本身以外的任何原因而失败，**仍然使用**会不管怎样都把它保存下来。

## 代理目录

| 代理 | CLI 命令 |
| --- | --- |
| Claude Code | `claude` |
| Codex CLI | `codex` |
| Gemini CLI | `gemini` |
| Pi | `pi` |
| OpenCode | `opencode` |
| OpenClaw | `openclaw` |
| Cline | `cline` |
| Hermes Agent | `hermes` |
| CodeBuddy | `codebuddy` |
| Kimi Code | `kimi` |
| Grok Build | `grok` |
| Cursor | `cursor-agent` 或 `agent` |
| DeepSeek Harness | `dsh` |
| Qoder | `qodercli` |

该目录标明了受支持的启动路径。可用的模型、附件、会话恢复和用量报告取决于代理开放了什么。设置会在会话开始之前报告缺少的要求。

Pi 通过 pi-acp 桥接程序运行，版本为 0.0.34，Oleafly 会让桥接程序指向你的 Pi 程序。在 Windows 上，它能处理名称中带空格的项目文件夹。

## 在稿件旁工作

给代理一个具体的请求，并在助手面板中跟踪它的回复、工具活动和权限提示。打开生成的源码，在 Oleafly 中编译它。

> 阅读引言和方法部分。列出引入方式不一致的术语，并给出文件位置。

如果想要一份单独的副本和最终审阅，请在[研究任务](/docs/research-tasks/)中选择一个可用的代理。该页面列出了隔离工作的平台要求。

## 研究起点

新对话会打开代理的主页，其中提供研究起点。选择一个会填入消息但不会发送，因此你可以先阅读和调整。如果还没有打开任何对话，它会新开一个。

| 起点 | 它要求什么 |
| --- | --- |
| **文献检索** | 针对项目研究问题的带注释阅读清单，使用 `oleafly-literature-sweep` 技能 |
| **相关工作** | 根据阅读清单和参考文献起草的相关工作一节，使用 `oleafly-related-work` |
| **引用核查** | 对照所引来源检查稿件的论述，使用 `oleafly-verify-claims` |
| **稿件审阅** | 对整篇稿件的审阅，使用 `oleafly-review-manuscript` |
| **可复现性核查** | 每个结果要复现还缺什么：代码、数据、软件版本、随机种子和构建说明 |
| **图片核查** | 检查每张图和每个表：标题、标签、交叉引用、坐标轴标签和单位、可读性，以及灰度下仍然清晰的颜色 |
| **Git 审阅** | 汇总未提交的更改和最近的提交，并标出看起来不是有意为之的编辑。仅在 Git 仓库中显示 |
| **参考文献整理** | 打开**清理参考文献库**，它会在你预览更改之后统一引用键并移除重复项 |

各项核查和稿件审阅会让代理不要动稿件文件，并把发现写入 `research/` 中的一个文件，例如 `research/figure-audit.md`。

你选择的技能，无论来自起点还是主页上的技能列表，都会以一个标签的形式显示在消息上方。Oleafly 会把技能的指令与你的消息一起发送，所以像 Pi 这样得不到 Oleafly 工具的代理，也能照着执行。点击该标签可以移除它。如果该技能在该项目中已关闭，起点会在不带该技能的情况下填入消息。

## 权限请求

当代理在行动之前询问时，卡片会显示代理**需要权限**，并提供代理自己的选项。如果请求会更改文件，卡片会列出这些文件。**显示更改**会打开某个文件的差异，让你在回答之前先读一读。太大而无法显示的更改会说明这一点，你可以在这一轮结束后审阅。**忽略**会取消请求而不允许它。搁置两分钟的请求会过期，代理必须重新询问。

## 审阅并撤销更改

一轮更改了文件之后，回复下方的一行文字会说明更改了多少个。**审阅**显示每一处更改，**撤销**和**重做**可以逐个文件使用，也可以对整轮使用。[审阅并撤销一轮的更改](/docs/ai-chat/#review-and-undo-a-turn)说明了它的工作方式以及它不会动哪些内容。

## 对话与导出

助手标题栏有**新对话**、**已保存的对话**和**代理设置**。每个对话都会记录它开始时项目所处的 Git 提交。

要在 Oleafly 之外保留一份副本，请打开**已保存的对话**并选择**导出对话…**，然后在保存对话框中选择 Markdown 或 JSON。Markdown 文件以项目、代理、模型、对话开始时所在的提交（会注明是否有未提交的更改）以及开始和最后更新的时间开头。之后是消息、技能、工具调用和更改的文件。JSON 保存完整的记录。

## 自定义代理

选择**查找更多代理**，在 ACP 注册表中搜索其他团队发布的代理；或选择**添加自定义代理**，自己粘贴一个定义。运行之前，请检查它的可执行文件或包、参数和连接要求。注册一个定义不会安装或启动该代理。

## 改用外部客户端

如果你更愿意留在代理自己的界面中，请通过 MCP 连接它。[Oleafly 的 MCP 服务器](/docs/mcp/)在 Oleafly 打开期间，为它提供应用的项目工具。[`oleafly` 命令](/docs/cli/#connect-an-agent-over-mcp)在应用关闭时同样可用，[`oleafly-cli` 技能](/docs/cli/#the-oleafly-cli-skill)则会教你的代理使用它的命令。