# Install OpenAgent in Claude Code Desktop

Choose by MCP source, not just the Code tab: a Code session using a third-party inference (3P) Gateway and unprefixed `mcp__openagent__*` tools still needs the active 3P Connector. Updating this Code plugin does not update that Connector. The plugin tools use the `mcp__plugin_openagent_openagent__*` prefix.

## 1. Add the Gitee Marketplace

The plugin repository is [hualia2009/claude-plugin](https://gitee.com/hualia2009/claude-plugin), published from `master`.

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

If the Marketplace is not already configured, run:

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

The result must contain `openagent-claude` with the Gitee repository above and ref `master`. If the same name points to an old local test directory, uninstall this plugin and remove that Marketplace before adding the correct source. If it points to another repository, stop and investigate; do not overwrite it. A Marketplace add performs a Git clone, so wait for the process to exit and do not start duplicate operations merely because output pauses.

In an interactive Claude Code session, the equivalent command is:

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

## 2. Install the plugin

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

Confirm that `openagent@openagent-claude` is installed and enabled, and that its version matches `openagent/.claude-plugin/plugin.json`. Do not substitute cache-file inspection for the plugin status check.

The interactive equivalent is `/plugin install openagent@openagent-claude`; choose user scope. In Desktop, open a local Code session and use **+ → Plugins → Manage plugins** to confirm that OpenAgent is enabled. Create a new local Code session if an existing session did not load the new plugin.

Do not manually copy Skills into `~/.claude/skills`, and do not run a separate `claude mcp add` for the same MCP. Desktop plugin and CLI behavior follows the [official Desktop documentation](https://code.claude.com/docs/en/desktop).

## 3. Connect the OpenAgent MCP

The plugin declares this native HTTP MCP:

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

This is the REL endpoint. Do not change environments based on the `pre` substring in the hostname. The header requests an OAuth challenge during an unauthenticated connection; it is not a credential.

Start login in an interactive local terminal and keep waiting for the same process:

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

If stdin is not a terminal and the command tool has no PTY option, macOS may use:

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

That `script` syntax is macOS-specific. Windows and Linux should use a local interactive terminal or `/mcp`. A PTY does not turn a remote session into a local one. While login is still running, do not start it again. Ask the user to complete login and authorization in the opened OpenAgent page, then wait for the callback.

OAuth requires `agent.discover`, `agent.invoke`, and `artifact.read`, subject to the actual authorization page. Claude stores and uses the credentials. Never provide a fixed Bearer token, copy a Codex token, or print an OAuth URL, authorization code, access token, refresh token, or PKCE verifier.

If login is cancelled, rejected, times out, or fails, stop and report the actual state. Retry only after the user explicitly asks to continue. Successful authentication requires an explicit successful result and process exit for `plugin:openagent:openagent`, or an authenticated `/mcp` state; `Connected` by itself is insufficient.

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

Report plugin enablement and login status, then remind the user to create a **New session** under **Code → Local**. Do not assume that the installation session hot-loads the newly installed tools.

## 4. Verify Skills and the real connection

In a new local Code session, confirm these five plugin Skills:

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

Their registered names may include the `openagent:` prefix. Then send this read-only request:

```text
Show my OpenAgent Credits balance and spending this month.
```

Confirm that the plugin's `openagent_account_credits` tool is called and report only its current result. If the tool is unavailable, unauthenticated, or fails, report the failure; do not invent a balance or treat a missing value as zero.

The MCP tool catalog should expose search, guide, account, selection wait, progress, upload, run, and stop capabilities. Runtime tool names and schemas are authoritative. After verification, the user may send:

```text
OpenAgent is installed. Open the new-user guide.
```

Do not automatically create a task in another client. UI cards do not prove that a business task succeeded.

## 5. Use and troubleshoot OpenAgent

| Goal | Example input |
| --- | --- |
| Browse Agents | Search for available Agents |
| Find by capability | Find an Agent that can create a presentation |
| Discover and run | Use OpenAgent to plan a two-day Beijing trip with transport, meals, and budget |
| Use a selected Agent | Use an Agent on OpenAgent (agent_id: the ID actually returned), followed by the task |
| Continue | Continue the same Agent task and change day two to indoor activities |
| Stop | Stop the current OpenAgent task |

Preserve the actual Agent name and ID exactly. Browsing or selection alone must not start a default trial task. Upload required local files successfully before passing their returned attachment references to an Agent. A completed account query does not replace business execution acceptance.

Common checks:

- If Claude can only list steps and cannot operate the computer, confirm **Desktop → Code → Local** and a selected local folder.
- If `claude` is missing, use `command -v claude`, check `~/.local/bin/claude`, or use `Get-Command claude` / `where.exe claude` on Windows. Install from the [official quickstart](https://code.claude.com/docs/en/quickstart) only when it is truly absent.
- If `mcp login` is unavailable, run `claude update`; if it still cannot be used, authenticate from `/mcp` in a local interactive session.
- For Git or Marketplace network errors, fix the actual local dependency or network issue. Do not guess proxy ports, disable TLS, or change global Git configuration.
- If a documentation webpage returns 451, judge Marketplace availability from the actual local Git command; do not repeatedly fetch the same failed page.
- If Skills exist but tools do not, check MCP authentication and create a new session; do not install a duplicate MCP.
- For a long-task timeout, keep the Invocation and mark the result unconfirmed. Do not automatically retry.
- If organizational policy blocks installation, follow that policy and do not rewrite managed settings.

## 6. Update or uninstall

Update from Gitee with:

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

Create a new local Code session and verify the actual version. Runtime changes require a plugin manifest version bump; INSTALL/README-only changes do not.

To remove only this user-scoped plugin and its dedicated Marketplace, fully quit Claude Desktop, Claude Code, and any CLI sessions using it, then run:

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

The script checks plugin and Marketplace state, refuses to modify state while the plugin is in use, logs out the plugin MCP, uninstalls the plugin, removes the dedicated Marketplace, and verifies only these OpenAgent-specific directories:

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

It does not delete all of `~/.claude`, other plugins, other MCP configuration, or user artifacts. The equivalent manual commands are:

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

After uninstalling, create a new Claude Code session and confirm that `mcp__plugin_openagent_openagent__*` tools no longer appear. Existing sessions do not hot-unload plugin MCPs.

Installation behavior is governed by the official [Claude Code Desktop](https://code.claude.com/docs/en/desktop), [Marketplace](https://code.claude.com/docs/en/discover-plugins), and [MCP](https://code.claude.com/docs/en/mcp) documentation.