# 在 Claude Desktop 安装 OpenAgent

执行任何安装命令前，先确认当前会话实际所在的客户端及 MCP 来源。如果不是适用的 Claude Desktop 路径，不得执行本文命令、注册 OAuth 客户端或修改配置；请返回 [OpenAgent 安装汇总页](https://oasn-ow.haimawan.com/plugin)，找到当前客户端对应的安装链接。如果无法确认客户端或连接来源，停止安装并询问用户。

按实际 MCP 来源选择，不只看界面标签：**Code 标签下使用 3P Gateway**、工具名为 `mcp__openagent__*` 时，仍需配置下方当前生效的 3P Connector；工具名为 `mcp__plugin_openagent_openagent__*` 的 Claude Code 插件使用第 1～7 节。Cowork / Chat 的第三方推理（3P）模式也使用 3P Connector。两者是不同配置，仅更新 Code 插件不会修改这项 Connector。

```text
先确认当前会话实际所在的客户端与 MCP 来源，并打开 https://oasn-ow.haimawan.com/plugin 核对安装入口。只有确认使用 Claude Code 插件时，才执行 claude plugin marketplace add；3P Gateway 会话应走当前生效配置的 Connector 路径。
```

## Claude Desktop 3P：自动添加当前配置的 OpenAgent Connector

本节适用于已在这台 macOS 电脑上完成 **Configure Third-Party Inference** 的 Claude Desktop，包括使用 3P Gateway 的 Code 会话。只修改本机当前生效的 3P 配置，不在 claude.ai 账号中添加远程 Connector，也不安装 Code 插件。配置字段和本机路径依据 [Claude Desktop 3P 官方扩展说明](https://claude.com/docs/third-party/claude-desktop/extensions)及[单机配置说明](https://claude.com/docs/third-party/claude-desktop/installation)。

发布前提：Access 服务必须已支持 `X-OASN-MCP-OAuth: required` 的连接期授权挑战，且本脚本已随 Marketplace 仓库发布到 Gitee `master`；仅改本机配置不能补齐旧服务端行为。若此前的 `openagent` 连接只授予 `agent.discover`，先在 **Cowork → Customize → Connectors** 手动 **Disconnect**；然后**完全退出 Claude Desktop**，在本机终端确认 `python3 --version` 可用，再执行以下命令；可先[查看脚本源码](https://gitee.com/hualia2009/claude-plugin/blob/master/install-desktop-connector.py)：

```bash
/bin/bash -o pipefail -c "curl -fsSL --proto '=https' --proto-redir '=https' 'https://gitee.com/hualia2009/claude-plugin/raw/master/install-desktop-connector.py' | python3 -"
```

脚本只向当前生效配置的 `managedMcpServers` 添加或升级 `openagent`（Streamable HTTP，地址为 `https://oasn-pre.haimawan.com/mcp/v1/open-agent`），设置 `oauth.scope: "agent.discover agent.invoke artifact.read"`、`oauth.clientId`、固定的 `oauth.callbackPort` 及非敏感请求头 `X-OASN-MCP-OAuth: required`，保留推理提供方、CC Switch、其他 Connector、现有工具策略和其他请求头。脚本需要联网，先向 OpenAgent 的公开 OAuth 注册端点创建仅供本机回调的公开客户端，并确认服务端准许三项 scope；注册不包含用户凭据、不会获取 Token 或代替用户同意。Claude 随后使用该客户端完成原生 PKCE 授权和凭据保存。这样避免 Claude 自动注册的客户端仅获准 `agent.discover`，导致完整授权请求收到 `invalid_scope`。配置变更不会扩大旧 Token 的权限，必须由用户重新授权。

已有同名同地址、同 transport 的旧匿名项、`oauth: true` 或仅指定完整 `oauth.scope` 的项会补齐上述配置；已预注册的正确配置重复运行不联网、不写文件。自定义 OAuth、`headersHelper`、Authorization、冲突标记、同名不同地址、重复目标或异常配置均停止，不覆盖原值。注册失败或回执没有完整 scope 时，本机配置不修改；公开客户端注册本身可能已在服务端留下未授权记录。发生配置修改前会在原目录创建仅本机用户可读的备份；备份可能含推理凭据，不要上传或发送给他人。脚本不写固定 Token，不复制 Code/Codex 的凭据，也不能替用户完成授权。没有 Python 3、本机尚未配置第三方推理，或组织托管配置覆盖了本机配置时，停止并向管理员报告，不尝试绕过策略。

重新打开 Claude Desktop 后按顺序验收：

1. 在 **Cowork → Customize → Connectors** 找到 `openagent`，点击 **Connect**，由用户在系统浏览器完成 OpenAgent 原生 OAuth。确认授权页包含 `agent.discover`、`agent.invoke`、`artifact.read`；若缺少调用权限或用户取消、拒绝、超时，停止，不自动重复登录。
2. 新建 Cowork / Chat 会话，发送“仅查询我的 OpenAgent Credits 余额和本月消耗，不运行任务”。确认实际调用受保护的 `openagent_account_credits` 并成功返回，才算发现权限可用；缺失或失败不能当作余额 0。再要求只读调用 `openagent_list_recent_invocations`，确认 `agent.invoke` 可用且不新建任务。若仍报 `Insufficient scope` 或 `Error POSTing to endpoint`，保留错误时间和 requestId，核查本次授权范围与连接状态，不自动重跑业务任务。
3. 再只读调用一次 `openagent_user_guide`，目视确认引导卡真实显示。连接、`tools/list`、Agent 选择及引导卡可以在匿名路径成功，均不能单独证明调用权限已就绪。引导卡成功也不等于 `openagent_progress` 或真实执行已验收；真实任务需用户另行明确提出。

若之后用 CC Switch 切换到另一套 3P 配置，需在完全退出 Claude 后对新的生效配置重新运行脚本。配置、授权、工具调用与卡片是不同验收项，脚本完成不代表全链路完成。

以下第 1～7 节仅用于 **Claude Code 插件**路径；只使用 3P Connector 时不必执行这些 `claude plugin` 命令。

## 1. 添加 Gitee Marketplace

插件仓库：[hualia2009/claude-plugin](https://gitee.com/hualia2009/claude-plugin)，发布分支为 `master`。

先在本机命令工具检查 Git、Claude Code CLI 和登录能力；CLI 缺失或不支持登录时按第 6 节处理，再继续：

```bash
git --version
claude --version
claude mcp login --help
claude plugin marketplace list
```

确认尚未配置本 Marketplace 后，执行：

```bash
claude plugin marketplace add "https://gitee.com/hualia2009/claude-plugin.git#master"
claude plugin marketplace list
```

结果应包含 `openagent-claude`，来源为上述 Gitee 仓库、ref 为 `master`。已有同名 Marketplace 时先核对来源；如果仍指向旧的本地测试目录，按第 7 节卸载本插件并移除旧 Marketplace 后再添加；如果指向其他仓库，停止并检查，不直接覆盖。

同名且来源正确时直接继续安装；已有插件需要更新时执行第 7 节。Marketplace 添加会执行 Git 克隆，使用可持续运行的进程并轮询到退出；暂时没有输出不代表失败，不要并发重复添加。

也可在 Claude Code 交互会话中执行：

```text
/plugin marketplace add https://gitee.com/hualia2009/claude-plugin.git#master
```

## 2. 安装插件

```bash
claude plugin install openagent@openagent-claude --scope user
claude plugin list
```

确认 `openagent@openagent-claude` 已安装并启用，版本与仓库中 `openagent/.claude-plugin/plugin.json` 一致。不要通过读取缓存文件代替插件状态检查。

交互会话也可使用 `/plugin install openagent@openagent-claude`，在安装界面选择用户范围。Desktop 已安装不代表终端 CLI 一定存在；找不到 `claude` 时先按第 6 节查找可执行文件。

在 Desktop 的 **Code** 页签打开一个本地会话，从输入框旁 **+ → Plugins → Manage plugins** 确认 OpenAgent 已启用；**Add plugin** 可从已配置的 Marketplace 中选择插件。已有会话没有加载新插件时，新建一个本地 Code 会话。

不需要把 Skills 手工复制到 `~/.claude/skills`，也不需要单独执行 `claude mcp add` 注册相同 MCP；避免重复工具。Desktop 插件入口及 CLI 共享配置依据 [官方 Desktop 文档](https://code.claude.com/docs/en/desktop)。

## 3. 连接 OpenAgent MCP

插件的 `.mcp.json` 声明：

```json
{
  "mcpServers": {
    "openagent": {
      "type": "http",
      "url": "https://oasn-pre.haimawan.com/mcp/v1/open-agent",
      "headers": { "X-OASN-MCP-OAuth": "required" }
    }
  }
}
```

该地址是 REL，与现有 Codex 公共安装文档一致。不要根据域名中的 `pre` 自行改为其他环境。`X-OASN-MCP-OAuth: required` 仅让未登录的连接在握手时收到 OAuth 挑战，不是凭据；进度卡重连时不应先建立匿名 MCP 会话。

在本机交互终端发起插件 MCP 登录；Claude 代执行时优先开启命令工具的 PTY/交互终端选项，并持续等待同一登录进程：

```bash
claude mcp login plugin:openagent:openagent
```

若命令提示 stdin 不是终端，而当前命令工具没有 PTY 选项，macOS 可用系统自带的 `script` 包装后执行：

```bash
script -q /dev/null claude mcp login plugin:openagent:openagent
```

上面的 `script` 参数只适用于 macOS；Windows/Linux 可使用本机交互终端或下面的 `/mcp` 入口，不照搬不同系统的命令语法。PTY 只解决终端输入要求，不会把远程会话变成本机会话。登录仍在运行时不要再次启动；需要用户授权时提示“请在打开的 OpenAgent 页面完成登录和授权”，保留进程并等待回调，不把等待状态报告成安装完成。

也可在 Claude Code 交互会话运行 `/mcp`，选择 OpenAgent 服务并点击 Authenticate。若提示找不到服务，先执行 `claude mcp list` 核对实际名称和插件启用状态。登录后回到 Desktop 的 Code 本地会话继续使用。

由用户在 Claude 发起的 OpenAgent OAuth 页面完成登录与授权，然后等待同一流程回调成功。权限包括服务所需的 `agent.discover`、`agent.invoke`、`artifact.read`，以实际授权页为准。OAuth 凭据由 Claude 保存和使用，不填写固定 Bearer Token，不复制 Codex 的令牌，也不打印 OAuth URL、authorization code、access token、refresh token 或 PKCE verifier。

登录取消、拒绝、超时或失败时停止并报告实际状态，不循环发起登录。用户要求继续登录时再发起一次。以登录命令对 `plugin:openagent:openagent` 的明确认证成功输出及成功退出，或 `/mcp` 的认证成功状态，确认本次登录完成；单独的 `Connected` 不能证明 OAuth 成功。连接及认证方式依据 [Claude Code MCP 文档](https://code.claude.com/docs/en/mcp)。

登录后检查：

```bash
claude plugin list
claude mcp get plugin:openagent:openagent
```

报告插件是否启用及登录结果，然后提醒用户点击 **New session**，仍选择 **Code → Local**。不要假定安装会话立即获得新插件工具；下一节的真实工具检查在新会话执行。CLI 与 Desktop 本地 Code 会话共享配置，无需在两个地方分别安装或重复登录。

## 4. 检查 Skills 和真实连接

安装完成后，在**新建的 Code 本地会话**的插件详情或 Skills 菜单确认以下五个入口：

```text
openagent-first-task-router
openagent-guide-agent
openagent-search-agent
openagent-run-agent
openagent-query-account
```

它们的注册名可能带 `openagent:` 前缀；以当前菜单显示为准。自然语言可触发相应 Skill，也可从菜单显式选择。

先发送只读请求：

```text
查询我的 OpenAgent Credits 余额和本月消耗。
```

确认调用的是插件提供的 `openagent_account_credits`，结果来自当前工具返回。工具未暴露、未登录或查询失败时报告实际失败，不编造余额、不把缺失值当成 0。

确认 MCP 工具列表包含搜索、引导、账户、选择等待、进度、上传、运行、停止共八个入口。运行时工具名和 schema 是调用依据；若部署版本与包中说明不同，记录实际差异，不反复猜参重试。

完成检查后，可发送：

```text
OpenAgent 已安装，打开新用户引导
```

不需要自动创建或跳转到另一客户端的任务。动画或进度卡能否显示取决于实际 Claude 版本与服务端 MCP Apps 支持；卡片本身不能证明业务任务成功。

## 5. 使用方式

| 目的 | 可复制输入 |
| --- | --- |
| 浏览 Agent | 搜索可用的 Agent |
| 按能力发现 | 帮我找一个制作 PPT 的 Agent |
| 自动寻找并执行 | 用 OpenAgent 帮我安排北京两日游，包含交通、餐饮和预算 |
| 指定 Agent | 使用 OpenAgent 上的 Agent (agent_id: 你实际取得的ID)，并补充你的具体任务 |
| 继续任务 | 继续刚才那个 Agent 的任务，把第二天行程改为室内活动 |
| 停止执行 | 停止当前这个 OpenAgent 任务 |

指定 Agent 时原样保留实际名称和 ID，不把示例当作可用 ID。只浏览或只选择 Agent 时，Claude 会先询问具体任务，不自动执行默认试用。任务需要本地文件时，先确保当前 Code 会话能读取文件；上传成功后才将原样附件回执传给 Agent。

搜索页优先使用 Claude Browser；没有自动打开工具时会给出“打开 OpenAgent 选择页”链接，点击后按客户端选项选择 Open in app。Claude 等待同一选择会话，不需要为了点击链接重新搜索。取消或超时后不会自动重开。业务结果按实际返回交付正文、文件及页面链接。

## 6. 验收与问题定位

| 场景 | 操作 | 预期结果 |
| --- | --- | --- |
| 插件加载 | Code 本地会话打开插件详情 | 正确 Marketplace、版本、已启用；五个 Skills 可见 |
| MCP 和 OAuth | 登录后执行账户只读查询 | 当前账户结果或可信错误，不借用其他客户端登录 |
| 浏览选择 | 发送“搜索可用的 Agent”，选择一个 Agent | 同一选择会话返回，保留选中身份并询问任务；没有默认 Run |
| 业务执行 | 用户明确给出一项业务需求 | 单次 Run 返回可信终态和实际正文/产物 |
| 续接 | 要求同一 Agent 修改结果 | 使用可信 Session，新的幂等键；切换 Agent 不复用 Session |
| 上传与下载 | 明确提供所需文件并要求产物 | 必需附件上传成功后才执行；实际文件或可用下载链接已交付 |
| 停止 | 对正在运行的任务明确要求停止 | 调用可信 Invocation 对应的停止工具，依据返回状态报告 |
| 界面或网络失败 | 记录自然发生的卡片错误、浏览器失败或断连 | 界面不裁决业务；未知执行状态不自动重放 |

没有运行过的项目保持“未验证”。账户查询成功不能替代 Agent 执行验收，CLI 插件校验也不能替代 Desktop 加载验收。

常见问题：

- **Claude 只列步骤，表示无法操作本机**：确认进入的是 Desktop 的 Code 页签，环境为 Local，并选中了本机文件夹。远程聊天、Cloud 或 SSH 会话执行的安装属于对应远程环境；不要在其中安装 CLI 后宣称本机插件已就绪。
- **找不到 `claude`**：先执行 `command -v claude`，再检查 `~/.local/bin/claude`；Windows 用 `Get-Command claude -ErrorAction SilentlyContinue` 或 `where.exe claude`。找到后用实际绝对路径运行，避免仅因 PATH 未更新重复安装。确实不存在时，按 [Claude Code 官方安装说明](https://code.claude.com/docs/en/quickstart) 在本机安装，再检查版本和 `claude mcp login --help`。
- **CLI 没有 `mcp login`**：执行 `claude update`，等待完成后重新检查；更新失败时按官方安装说明处理并保留具体错误。无法使用登录命令时，可在本机 Claude Code 交互会话通过 `/mcp → Authenticate` 完成授权。
- **找不到 Git 或 Marketplace 网络失败**：缺少 Git 时按 [Git 官方安装说明](https://git-scm.com/downloads) 安装；克隆失败时检查实际网络和已有代理，等待当前进程退出后再重试。不猜代理端口、不关闭 TLS 校验、不修改全局 Git 配置。
- **Gitee 安装文档网页无法读取**：网页或 `raw` 地址返回 451、读取工具拒绝访问，不等同于 Git 仓库不可用。可直接使用文档开头包含完整安装命令的请求；按本机 Git 命令的实际结果判断 Marketplace 是否可访问，不反复抓取同一失败网页。
- **登录要求交互终端**：按第 3 节使用 PTY，或在本机终端／`/mcp` 入口登录；不要因此重复安装插件。
- **找不到插件**：检查添加的是包含 `.claude-plugin/marketplace.json` 的目录，名称为 `openagent-claude`；确认正在使用 Code 本地会话。
- **Skills 有、工具没有**：检查 MCP 连接与 OAuth，并新建会话；不要再安装一份重复 MCP。
- **无动画/进度卡**：检查当前客户端 MCP Apps 能力；以实际工具结果判定业务状态。
- **长任务超时**：保留已有 Invocation 与错误，标记结果未确认，不自动重试。Codex 的 `tool_timeout_sec` 不是 Claude 配置，不能通过复制该字段延长 Claude 的等待。
- **安装被组织策略阻止**：按现有组织插件策略处理，不绕过策略或改写托管配置。

## 7. 更新与卸载

从 Gitee 获取插件更新：

```bash
claude plugin marketplace update openagent-claude
claude plugin update openagent@openagent-claude --scope user
claude plugin list
```

新开 Code 本地会话，核对实际版本。维护者修改 Skills、MCP 等运行内容时必须更新插件清单版本；仅修订 INSTALL/README 不要求递增运行版本，安装说明以 Gitee 最新正文为准。

一条命令卸载用户范围的本插件及其独立 Marketplace：

先完全退出 Claude Desktop、Claude Code 和仍在使用本插件的 CLI 会话，再在系统终端执行：

```bash
curl -fsSL --proto '=https' --proto-redir '=https' 'https://gitee.com/hualia2009/claude-plugin/raw/master/uninstall-openagent.sh' | bash -s -- --yes
```

脚本会先读取插件和 Marketplace 状态，并检查缓存中的 `.in_use` 进程标记（包括 Claude 原子写入产生的 `<pid>.tmp.<随机值>` 临时标记）；仍有 Claude 进程使用插件时，在修改任何状态前停止。确认可清理后，如插件仍已安装，脚本先执行本地 MCP OAuth 退出和插件卸载；随后移除 Marketplace，只删除以下两个 OpenAgent 专属目录并复核结果：

```text
~/.claude/plugins/marketplaces/openagent-claude/
~/.claude/plugins/cache/openagent-claude/openagent/
```

`CLAUDE_CODE_PLUGIN_CACHE_DIR` 或 `CLAUDE_CONFIG_DIR` 已配置时，脚本使用对应插件根目录。旧版脚本已卸载插件但仍留有 Marketplace 或版本缓存时，新版脚本会通过该残留插件定义调用官方 MCP OAuth 退出，再完成目录清理；不直接读取令牌存储。Marketplace 仍在列表但 CLI 明确报告 user settings 已无声明时，脚本才按 CLI 提示移除同名 Marketplace 的剩余作用域；其他删除错误不会触发该回退，也不会影响其他 Marketplace。重复执行且上述安装状态和目录均不存在时安全退出；`--yes` 仅跳过脚本自身的人工确认。脚本不删除整个 `~/.claude`、其他插件、其他 MCP 配置或用户产物。卸载完成后必须新建 Claude Code 会话，确认 `mcp__plugin_openagent_openagent__*` 工具不再出现；已有会话不会热卸载插件 MCP。

也可在本机终端手动执行相同操作：

```bash
claude mcp logout plugin:openagent:openagent
claude plugin uninstall openagent@openagent-claude --scope user
claude plugin marketplace remove openagent-claude --scope user
```

手动命令不会保证立即清除 Claude 延迟回收的历史缓存；需要达到上述目录不存在的验收标准时使用完整脚本。也可在 Code 的插件管理器禁用或卸载。不要删除整个 `~/.claude`、清空全部 MCP、卸载其他插件或删除用户产物。脚本清除的是 Claude 本地保存的 MCP OAuth 凭据；如需同时撤销 OpenAgent 服务端授权，应使用 OpenAgent 实际提供的账号授权管理入口。

安装流程参考 [ChatCut 的 Claude Code 安装指南](https://chatcut.io/claude)，命令和客户端边界以 [Claude Code Desktop](https://code.claude.com/docs/en/desktop)、[Marketplace 安装](https://code.claude.com/docs/en/discover-plugins)及 [MCP 文档](https://code.claude.com/docs/en/mcp)为准。