# 连接 Codex Desktop 与 WorkBuddy

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

- 原文: https://beav.pro/docs/agent/connect

## 准备

1. 在同一台电脑安装 [Beav 桌面版](https://beav.pro/download)。
2. 桌面安装包不会把 `beav` 加入 `PATH`，请使用桌面版可执行文件的完整路径核对 `beav version`；macOS 标准安装为 `/Applications/Beav.app/Contents/MacOS/beav`。
3. 打开 Codex Desktop，在任意任务中发送下面的提示词。

```text
/goal Read https://beav.pro/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://beav.pro/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. 创建新任务，在新会话里验证连接、确认当前空间，读取该空间的账号运营方案、风格与协作档案，并在 Codex 右侧浏览器打开知识库。原安装回复会说明实际空间名称、档案读取和网页打开结果，并给出新聊天入口；新任务验证前只报告“已安装，连接待验证”。

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

## 新任务如何协作

核对日期：2026-10-08。以下交接使用 Beav 2.8.14 已有接口；需要更新后的官网安装指引，或随新版 Beav 发布并刷新后的插件 Skill。修改后的完整安装与侧栏显示尚待实机验收。

新任务先调用 `creator_status`、`creator_capabilities` 与 `workspace_list`，确认当前启用的空间；只读列举知识库，并通过 `Read` 读取 `profiles://creator_profile`、`profiles://soul`、`profiles://agent` 的实际正文，分别对应 `CreatorProfile.md`、`Soul.md`、`Agent.md`。已有定位、受众、目标、风格与协作偏好会作为后续创作参考；不会为安装验证改写档案或生成内容。

安装结果会明确说明当前空间名称、档案中明确的账号名称、哪些文档已读取或不可用，以及[本机知识库网页](https://beav.pro/docs/agent/local-library)的打开结果。网页地址取自 MCP 返回值，在新聊天的 Codex 右侧浏览器中打开并指定知识库标签；切到新聊天后可继续创作。没有浏览器面板工具时改用 `library_open` 打开系统浏览器并说明；打开失败或仅排队时提供链接和真实状态。

没有活动空间时，先在 Beav 打开空间。档案为空、缺失或读取失败时，会明确说明而不宣称上下文完整。空间与社媒账号并不等同，`accounts://current` 历史归档需要另有真实会话账号绑定；不会根据空间名称猜账号。切换空间或上下文丢失后，Agent 应重新读取相关文档；档案作为参考，不覆盖你的当前明确要求。

工具列表只放常用工具（数据读写、选题、生图、生视频、配音、转录和任务委派）；视频剪辑、素材与稿件管理等其余工具先用 `creator_tools` 查找，再用 `creator_tool_call` 调用。宿主 Agent 可以直接执行工作，也可以用 `creator_delegate` 委派给 Beav Agent。浏览器供你查看与挑选内容，Agent 数据操作继续走 MCP。

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

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

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

## 保存成稿与制作素材包

可以直接对已连接的 AI 说：“把这篇文章保存到 Beav 稿件库”，或在指定平台后说“把这篇稿件做成素材包”。Agent 会使用当前空间的稿件库，并返回保存的标题与资源引用；在 Beav 的“账号档案 → 稿件”中可继续查看、编辑，同一稿件的平台素材包也保存在这里。打包不会自动发布。

这条链路复用现有 MCP：通过 `creator_tools` 发现 `manuscripts_create_project`、`manuscripts_write` 与 `manuscripts_packages_begin/build/list` 对应的工具，再用 `creator_tool_call` 调用。AI 会核对保存后的实际正文和素材包资源，不会把聊天文字或任意目录中的 Markdown 当作稿件库保存结果。后续修改已有素材包时会重新打开同一稿件和平台的打包上下文，保持包的 ID 与地址，不重复新建稿件。只保存文章不需要先选择平台。

2026-10-08 已通过真实 MCP 验证 Beav 2.8.14 的稿件创建、正文保存/读回、列表可见、通用文字包构建/读回、同包更新和测试稿回收。本次未验证图片包、付费媒体生成或平台发布。接口已存在，补充的 Skill 说明需随新版 Beav 发布并刷新插件；安装验证本身只读取与发现能力，不创建测试稿件。

## WorkBuddy 接入

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

```text
Read https://beav.pro/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://beav.pro/download)，等待安装后在同一任务继续；此时不准备或安装插件。不要求 shell `PATH` 已配置 `codebuddy`。
3. 给出已安装 Beav 桌面版可执行文件的完整路径（下文记为 `<BEAV_APP>`）。用户在 WorkBuddy 外的普通终端依次运行 `"<BEAV_APP>" open --output json` 和 `"<BEAV_APP>" extension prepare workbuddy --output json`，只把第二条命令返回的 `marketplacePath` 发给 WorkBuddy。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://beav.pro/workbuddy.md](https://beav.pro/workbuddy.md)。