# 连接 Codex Desktop 与 WorkBuddy

> 从官网一句话安装 Beav Creator Plugin，并验证 Codex 或 WorkBuddy 与本机 Beav MCP 的连接。

- 原文: https://www.getbeav.com/docs/agent/connect

## 准备

1. 在同一台电脑安装 Beav 桌面版；它已内置所需命令，无需单独安装 CLI。已有独立 CLI 的用户也可继续使用。
2. 使用已安装程序的完整路径核对 `beav version`；测试压缩包也可以使用其中的 `bin/beav` 完整路径。
3. 打开 Codex Desktop，在任意任务中发送下面的提示词。

```text
/goal Read https://www.getbeav.com/agent to install the Beav Creator plugin and set up a new task for me.
```

## Codex 会执行什么

1. 读取 `/agent` 返回的机器安装指南。
2. 定位 Codex Desktop 自己内置的 CLI，不依赖用户终端的 `PATH`；当前 macOS ChatGPT App 的位置是 `Contents/Resources/codex-cli/CodexCLI.app/Contents/MacOS/codex`，以实际安装包和 `plugin --help` 为准。
3. 检查 Beav 是否已安装。没有则提醒用户先安装 [Beav 桌面版](https://www.getbeav.com/download)，安装后在同一任务继续，不提前安装插件。
4. 执行 `beav extension prepare codex --output json`。如果 Codex 的命令沙箱阻止本地运行时或文件写入，提示用户在外部普通终端依次运行 `beav open --output json` 和准备命令，只返回准备结果的 `marketplacePath`，不要发送完整 JSON 或凭据。
5. 核对本机 marketplace 与插件清单，使用 Codex CLI 添加或更新 `beav-local`，再执行 `plugin add beav-creator@beav-local --json`，使旧缓存也得到刷新。
6. 读取 `plugin list --json --marketplace beav-local` 和安装缓存，确认插件已安装、启用，版本、MCP 命令和 Skill 与准备结果一致。
7. 创建新任务，在新会话里验证 `creator_status`、`creator_capabilities`、`workspace_list` 与可用时的只读数据访问。新任务验证前只报告“已安装，连接待验证”。

`beav extension install codex --output json` 是兼容别名，同样只准备插件，不会自行调用裸 `codex` 命令或修改 Codex 配置。

## 新任务如何协作

更新后的宿主与插件 0.2.0 提供直接数据和工具访问。新任务先调用 `creator_status`、`creator_capabilities` 与 `workspace_list`，读取完整分页工具目录；存在当前空间时，打开 `creator_session_open` 并只读列举知识库验证数据连接。宿主 Agent 可以直接执行工作，也可以用 `creator_delegate` 委派给 Beav Agent。需要用户查看、审批或细调时，Beav 返回 localhost browser handoff；浏览器只是用户工作台，不是 Agent 控制面。

直接调用使用 `{sessionId,idempotencyKey,input}`；网络结果不确定时保留原键重试，不换键重复写入。直接会话的空间当前必须在 Beav 中启用，视频编辑需先绑定实际工程。委派后续修改继续查询并续接同一个 Beav task。任务终态不是内容已保存的证明，需要保存内容时读取实际资源引用；普通回答不必产生文件。

准备插件会创建宿主独立的本机授权，默认覆盖业务数据。凭据保存在插件包外，不应复制到模型上下文；更新保留原授权，撤销后需明确授权再用 `--reauthorize` 替换。普通调用不会重新开启被禁用的网关。

机器可执行安装契约位于 [https://www.getbeav.com/agent.md](https://www.getbeav.com/agent.md)。

## WorkBuddy 接入

把下面的提示词发送给 WorkBuddy：

```text
Read https://www.getbeav.com/workbuddy to install the Beav Creator plugin and connect it to my local Beav workspace.
```

WorkBuddy 会执行：

1. 读取 `/workbuddy` 返回的机器安装指南。
2. 定位 WorkBuddy App 内置的 CodeBuddy CLI，并检查本机 Beav。如果尚未安装，WorkBuddy 会提醒先安装 [Beav 桌面版](https://www.getbeav.com/download)，等待安装后在同一任务继续；此时不准备或安装插件。不要求 shell `PATH` 已配置 `codebuddy`，也无需单独安装 Beav CLI。
3. 给出已安装 Beav 的准确命令路径。用户在 WorkBuddy 外的普通终端依次运行 `"<BEAV_CLI>" open --output json` 和 `"<BEAV_CLI>" extension prepare workbuddy --output json`，只把第二条命令返回的 `marketplacePath` 发给 WorkBuddy。桌面版已内置这些命令，无需另装 Beav CLI。WorkBuddy 的命令沙箱可能阻止 Beav 写入本机运行文件，因此不要在其中反复尝试准备命令。
4. WorkBuddy 读取该路径下的插件清单，使用 `codebuddy plugin validate` 校验 marketplace，再以 user scope 安装 `beav-creator@beav-local`。不要发送完整准备结果或凭据。
5. 通过 `/reload-plugins` 热加载插件，并用 `creator_status`、`creator_capabilities` 与 `workspace_list` 验证同一套 Beav MCP，并在存在当前空间时只读核对数据访问。

`beav extension install workbuddy --output json` 是 prepare-only 兼容别名。Codex 与 WorkBuddy 只在宿主安装格式和加载方式上不同；两者共享同一个 Beav Creator Skill、Creator Gateway、内部 Agent 和 localhost 用户工作台。

机器可执行安装契约位于 [https://www.getbeav.com/workbuddy.md](https://www.getbeav.com/workbuddy.md)。