# 外部智能体 (/zh/docs/ai/agents)

Echolot 自带 MCP 服务器。通过它，Claude Code、Claude Desktop、Cursor、VS Code 和 Codex 等 AI 客户端可以列出你存储的请求、发送请求、
读取响应、添加检查并运行文件夹，用的正是 App 自己使用的工具。工作区在 Echolot 中打开时，它们的调用在 App 内运行：任何可能更改数据的操作都由你批准，
每次调用都看得到，机密值也永远不会到达智能体。

## 工作原理 [#how-it-works]

客户端用工作区的路径启动 `echolot mcp serve`。接下来会怎样，取决于 App：

- **工作区已在 Echolot 中打开，且智能体已开启。** 该命令连接到 App，客户端的调用在工作区的窗口中运行。需要批准的调用会在表单中询问你，
  每次调用都显示在页面标题栏的**智能体**下。
- **其他情况**（App 已关闭、工作区未打开，或智能体已关闭），该命令自行提供工作区。此时没有人可以询问，所以本该询问的操作会被拒绝。
  参见[独立运行](#on-its-own)。

每个打开的窗口只在 `127.0.0.1` 上提供其工作区，端口由系统选择，并且只面向出示本次会话随机令牌的调用方。命令通过 Echolot 的 Application Support
文件夹中的一个私有文件找到该窗口。不会有任何内容监听你的网络。

## 开启智能体 [#turn-agents-on]

<Steps>
<Step>
打开**设置 › 智能体**，开启**允许智能体使用打开的工作区**。该开关在你开启之前是关闭的。工作区窗口页面标题栏中的**智能体**弹出窗口里也有同一个开关。
</Step>
<Step>
在 Echolot 中打开工作区。窗口提供工作区期间，页面标题栏中**智能体**旁的圆点会变绿；有客户端连接时，它会显示连接数。
</Step>
<Step>
按下文连接客户端。每个工作区和客户端只需做一次。
</Step>
</Steps>

工作区也可以为自己关闭智能体：**工作区设置 › 智能体 › 智能体可以使用此工作区**。关闭后，客户端无论经由 App 还是独立运行，都无法从该工作区得到任何内容。

## 连接客户端 [#connect-a-client]

点按页面标题栏中的**智能体**。在**连接客户端**下，每个客户端都有一个按钮：

<Shot id="ai-agents-popover" alt="页面标题栏中的“智能体”弹出窗口，包含允许智能体访问的开关、一个已连接的客户端、最近的调用以及“连接客户端”按钮" />

| 客户端 | 按钮 | 作用 |
| --- | --- | --- |
| **Claude Desktop** | **添加到 Claude** | 为此工作区构建一个 Claude Desktop 扩展，并在 Claude Desktop 中打开，由它请你确认。仅限直接下载版。 |
| **Claude Code** | **拷贝命令** | 拷贝一条 `claude mcp add` 命令。将它粘贴到“终端”中。 |
| **Cursor** | **添加到 Cursor** | 打开 Cursor 安装 MCP 服务器的提示。 |
| **VS Code** | **添加到 VS Code** | 打开 VS Code 安装 MCP 服务器的提示。 |
| **Codex** | **拷贝 config.toml 条目** | 拷贝一个条目，用来粘贴到 Codex 的 `config.toml` 中。 |
| **其他** | **拷贝 JSON** | 拷贝一个 `mcpServers` 条目，这是大多数 MCP 客户端读取的格式。 |

它们下方是命令本身和**拷贝**按钮，适用于任何要求提供命令及其参数的客户端。

服务器在客户端中的名称是 `echolot-` 加上工作区的名称。以 Alpenglow 工作区为例，Claude Code 的命令如下（`echolot` 的路径是 App 内的工具）：

```sh
claude mcp add --scope user echolot-alpenglow -- /Applications/Echolot.app/Contents/Helpers/echolot mcp serve ~/Alpenglow.echolot
```

Codex 的条目如下：

```toml
[mcp_servers.echolot-alpenglow]
command = "/Applications/Echolot.app/Contents/Helpers/echolot"
args = ["mcp", "serve", "/Users/you/Alpenglow.echolot"]
```

在“终端”中，`echolot mcp setup <client> -w <workspace>` 会为 `claude-code`、`claude-desktop`、`cursor`、`vscode` 和 `codex` 打印相同的设置。
参见 [`echolot mcp`](/docs/cli/mcp)。

<Edition only="appstore">
  App Store 版的 App 内没有命令行工具，也没有 Claude Desktop 扩展。请单独安装命令行工具（设置 › 智能体和“智能体”弹出窗口中的**获取命令行工具**会带你前往下载）；
  由客户端运行它，工作区在 Echolot 中打开时，它们的调用仍然在 App 内运行。这些按钮拷贝命令或代码片段，或打开客户端自己的安装提示；它们从不写入其他 App 的文件夹。
</Edition>

### 一键添加到 Claude Desktop [#claude-desktop-in-one-click]

<Edition only="direct">
  Claude Desktop 扩展（`.mcpb`）内含命令行工具，因此只在直接下载版中提供。
</Edition>

**设置 › 智能体 › Claude Desktop** 列出你最近使用的工作区。点按某个工作区旁的**添加到 Claude**，会开启智能体，为该工作区构建扩展，并交给 Claude Desktop，
由它请你确认。Claude Desktop 收到后，该行会显示**已添加**；以后要更新扩展，请按住 Control 键点按**已添加**并选取**再次添加**。

如果未安装 Claude Desktop，该部分会说明，并附上**获取 Claude Desktop**链接，而**添加到 Claude**会改为在访达中显示扩展。

## 工具集 [#toolsets]

智能体能看到的每个工具都会占用它的上下文空间，所以 Echolot 把工具分成几组提供。在**设置 › 智能体 › 供智能体使用的工具**中选取。**请求**始终开启；**请求**和**流程**
在你更改之前默认开启。这些复选框决定智能体能看到哪些工具，而不是它们无需询问就能做什么：每个工具在更改数据或访问新主机之前仍会询问。对于内置助手，
**设置 › 助手 › 询问时机**决定它询问哪些操作。

| 工具集 | 智能体可以用它做什么 |
| --- | --- |
| **请求** | 列出、读取、创建和发送请求；响应、历史记录、GraphQL、正在运行的模拟服务器 |
| **流程** | 运行提供给智能体的流程，回答它们提出的问题 |
| **工作区** | 创建、重新命名、移动、复制和删除文件夹与请求；文件夹的认证；工作区变量；将收集到的数据存储为文件 |
| **环境** | 创建、更改和删除环境 |
| **规范** | 读取、编写 OpenAPI 规范并对其做 Lint；将文件夹链接到规范并应用更改 |
| **模拟服务器** | 创建、更改和删除模拟服务器及其路由，使用示例数据；根据路由创建请求；将响应存储为示例 |
| **MCP 服务器** | 添加、更改、检查和删除 MCP 服务器 |
| **历史记录** | 打开、比较和删除过去的交换记录 |
| **流程编辑** | 读取、绘制和删除流程；在你批准后试运行一次 |

使用默认工具集时，智能体得到的工具可以列出、读取、创建、更新和发送请求，运行带检查的文件夹，逐段读取响应，查看历史记录，检查 GraphQL 查询，
将请求拷贝为 cURL 或代码，导入，对规范做 Lint，启动和停止模拟服务器，以及运行提供给智能体的流程。它还会得到两个提示词：`debug_request` 和 `write_tests`。

更改工具集后，打开的窗口会用新的工具集重新开始提供服务；请重新连接客户端以获取它。

**任何工具集都从不提供**以下内容：更改智能体规则、代理、证书、工作区的认证、除认证之外的文件夹设置、脚本（请求脚本、文件夹脚本和模拟脚本），
以及使用机密获取或签名的认证（OAuth 2.0、AWS、JWT 等）。这些只属于你自己。

智能体可以为请求和文件夹设置 **Bearer**、**Basic** 或 **API 密钥**认证，并让请求保留响应中的值（比如登录返回的令牌，供之后的请求使用）：
`create_request` 和 `update_request` 接受 `auth` 和 `captures`，而 `save_folder_auth` 设置文件夹中的请求继承什么。凭据必须是 `{{variables}}`；
智能体自己写入密码或令牌会被拒绝，因此它们绝不会落入文件。名称看起来像凭据（token、password、key…）的捕获值会被保存为机密。

智能体通过各自的工具启动提供给它们的流程（在“流程”列表中以闪光图标标记），每次都要在你批准该流程当前的样子之后；参见[运行流程](/docs/flows/running-and-triggers)。
开启**流程编辑**后，`try_flow` 会将任何其他流程运行一次，包括智能体正在绘制的那个：你会看到它发送、存储和运行的内容，并且无论规则如何，每次都要批准这次运行，
而**在本次会话中允许**只涵盖该流程的这个版本。

## 查看智能体的操作 [#see-what-agents-do]

窗口提供工作区期间，页面标题栏中的**智能体**弹出窗口会显示：

- 每个调用过的客户端，包括其调用次数和失败次数以及上次出现的时间。关闭它的开关，今后会拒绝该客户端的调用，以及它正在等待的所有批准。
- **最近的调用**：最新的调用，包含工具、客户端、时间、持续时间和任何错误。

在客户端调用之前，它显示**尚无智能体使用过此工作区。** 智能体关闭时，它会说明客户端仍可独立工作，只是没有你的批准。

智能体的每次发送也会以客户端的名称出现在工作区的[历史记录](/docs/workspaces/history)中。

## 批准 [#approvals]

当客户端想要执行规则要求询问的操作时，工作区的窗口中会出现一个表单：***客户端*想要发送可能更改数据的请求**，并显示请求发出时的样子，机密已被遮盖。
选取**允许一次**、**在本次会话中允许**（在窗口关闭之前，再次发出同样的调用无需询问）或**拒绝**。五分钟内无人回答的问题会被拒绝。该表单与[助手](/docs/ai/assistant#approve-what-changes)使用的是同一个。

没有工作区规则时，询问的情况如下：

| 操作 | 默认 |
| --- | --- |
| **读取请求和环境** | 允许 |
| **安全的发送（GET、GraphQL 查询、MCP 读取）** | 允许 |
| **其他发送** | 询问 |
| **发送到受保护的环境** | 询问，始终如此 |
| **发送到新主机** | 询问，始终如此 |
| **对工作区的更改** | 询问 |
| **删除** | 询问 |

新主机是指窗口开始提供服务时，工作区中没有任何请求或环境使用过的主机。智能体读取的数据可能经由它外泄，所以总会询问，
发送到[受保护的环境](/docs/workspaces/protected-environments)也是如此。

## 工作区规则 [#workspace-rules]

**工作区设置 › 智能体**（在边栏底部的工作区菜单中选取**工作区设置…**）为此工作区设定规则。规则存储在 `workspace.toml` 中，
因此会随它一起通过 Git 传递，并且同时适用于外部智能体和助手。

<Shot id="ai-agents-workspace-rules" alt="工作区设置的“智能体”标签页：智能体的开关、每个操作的规则，以及主机和限制字段" />

- **智能体可以使用此工作区**：关闭后，智能体无法从该工作区得到任何内容。
- **智能体可以做什么**：针对上表中每个操作的规则：**默认**（并注明默认值是什么）、**允许**、**询问**或**拒绝**。发送到受保护的环境和新主机只能是**询问**或**拒绝**。
- **主机和限制**：
  - **允许的主机**：智能体可以发送到的主机，用逗号或空格分隔。
  - **每个会话发送次数**：智能体在一个会话中最多可以发送的次数。留空表示没有限制。
  - **每分钟发送次数**：智能体在一分钟内最多可以发送的次数。留空表示没有限制。

更严格的规则始终生效。随文件而来的较宽松规则（来自队友，经由 Git）只有在你信任之后才会在你的 Mac 上生效：在此之前，“智能体”弹出窗口会说明工作区的规则会允许哪些操作无需询问，
而智能体仍然会询问。选取**信任这些规则**即可接受。你自己在“工作区设置”中设定的规则是受信任的。

## 智能体永远得不到的内容 [#what-agents-never-get]

- **机密值。** Echolot 会替换智能体收到的所有内容中的每个机密值，包括错误，无论是纯文本、JSON、URL 编码还是 Base64 形式。智能体只能按名称看到机密变量。
- **历史记录中的凭据。** 过去的交换记录送达智能体时，凭据标头已被遮盖，也不含传输捕获。
- **你的机密不会发给别人的主机。** 智能体的发送如果重定向到工作区未使用的主机，会在途中丢弃其凭据标头。

## 独立运行 [#on-its-own]

当 App 没有打开该工作区，或使用 `--headless` 时，`echolot mcp serve` 自行提供工作区，由策略单独决定：

| `--policy` | 运行 | 拒绝 |
| --- | --- | --- |
| `standard`（默认） | 读取和安全的发送 | 其他发送、更改、删除、受保护的环境、新主机 |
| `readonly` | 读取 | 所有发送、更改和删除 |
| `permissive` | 读取、所有发送、更改 | 删除、受保护的环境、新主机 |

机密从这台 Mac 的钥匙串和 `ECHOLOT_SECRET_…` 变量中解析，永远不会到达智能体。`--toolsets` 选取工具集（`all` 表示全部），`--env` 指定调用未指明环境时使用的环境，
`--http 0` 则在 `127.0.0.1` 上提供带令牌的 Streamable HTTP，而不是标准输入输出。工作区自己的规则会收紧策略；`--trust-workspace-policy` 让它们也可以放宽策略。
参见 [`echolot mcp`](/docs/cli/mcp)。

```sh
echolot mcp serve ~/Alpenglow.echolot --policy readonly --toolsets requests,history
```

## 疑难解答 [#troubleshooting]

- **客户端已连接，但没有任何询问，更改被拒绝。** 命令在独立运行：请在 Echolot 中打开工作区并开启**设置 › 智能体 › 允许智能体使用打开的工作区**，然后重新连接客户端。
- **客户端完全得不到工具。** 工作区设置 › 智能体中的**智能体可以使用此工作区**已关闭，或者你在“智能体”弹出窗口中关闭了该客户端的开关。
- **智能体需要的工具缺失。** 在**设置 › 智能体 › 供智能体使用的工具**中开启它所在的工具集，然后重新连接客户端。
- **“添加到 Claude”呈灰色。** 此构建内没有命令行工具；echolot.dev 上的发行版有。