> ## Documentation Index
> Fetch the complete documentation index at: https://docs.useorgx.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# OpenClaw Plugin Setup

> Connect the OrgX OpenClaw plugin in about 60 seconds using secure browser pairing.

## Questions This Page Answers

* What is the fastest way to connect OpenClaw to OrgX reliably?
* When should I use browser pairing vs manual API key fallback?
* How do I verify the plugin is actually healthy after pairing?
* What unique capabilities does the OpenClaw plugin add vs hosted MCP alone?

## 60-Second Setup

<Steps>
  <Step title="Install the plugin">
    `bash openclaw plugins install @useorgx/openclaw-plugin `
  </Step>

  <Step title="Open the dashboard">
    Visit `http://127.0.0.1:18789/orgx/live` from your OpenClaw runtime.
  </Step>

  <Step title="Start pairing">
    Click **Connect OrgX** in the onboarding panel.
  </Step>

  <Step title="Confirm on web">
    Sign in at [useorgx.com](https://useorgx.com) and approve the OpenClaw
    connection.
  </Step>

  <Step title="Return to OpenClaw">
    The plugin stores a dedicated credential and runs first sync automatically.
  </Step>
</Steps>

<img src="https://mintcdn.com/neuromosaic/jQgSROOHTkjtaQwb/images/openclaw/openclaw-onboarding.png?fit=max&auto=format&n=jQgSROOHTkjtaQwb&q=85&s=3b0e0b5bd6582fb61716afed2c2f8866" alt="OpenClaw OrgX dashboard onboarding panel" width="1280" height="800" data-path="images/openclaw/openclaw-onboarding.png" />

## How Pairing Works

1. OpenClaw requests a short-lived pairing session from OrgX.
2. OrgX opens a secure browser confirmation page tied to that session.
3. After confirmation, OrgX provisions a plugin-scoped key for that installation.
4. OpenClaw receives the key, stores it locally with restricted file permissions, then acknowledges receipt.

<Tip>Pairing sessions expire automatically after 10 minutes for security.</Tip>

## Manual Key Fallback

If browser pairing is blocked, use **Use API key instead** in onboarding.

### Step-by-step (With Screenshots)

1. Open OrgX settings and go to API keys:
   * `https://www.useorgx.com/settings#security`
2. Generate a new API key (keep it private).

<img src="https://mintcdn.com/neuromosaic/jQgSROOHTkjtaQwb/images/openclaw/orgx-settings-security.png?fit=max&auto=format&n=jQgSROOHTkjtaQwb&q=85&s=dd5d8dc4c109f1a1931c686845996e3c" alt="OrgX settings security page (API keys)" width="1280" height="800" data-path="images/openclaw/orgx-settings-security.png" />

3. In OpenClaw onboarding, choose **Use API key instead**.
4. Paste the `oxk_...` key and submit.

<img src="https://mintcdn.com/neuromosaic/jQgSROOHTkjtaQwb/images/openclaw/openclaw-manual-key.png?fit=max&auto=format&n=jQgSROOHTkjtaQwb&q=85&s=015ac953a55836e74218dca118143cd2" alt="OpenClaw manual API key entry" width="1280" height="800" data-path="images/openclaw/openclaw-manual-key.png" />

5. On success, onboarding should show **Connected** and first sync should start automatically.

<Info>
  Manual key fallback is for auth recovery, not for forcing a GitHub or Linear
  dependency. OrgX can still orchestrate through direct provider APIs with your
  own supported model credentials when hosted Claude pairing is not the active
  path.
</Info>

## First-Run Validation Checklist

<Check>Onboarding status changes to **Connected**</Check>
<Check>The dashboard loads live sessions/activity without restart</Check>
<Check>`orgx_status` returns OrgX workspace data from the plugin tools</Check>
<Check>First sync completes within your first minute on healthy network</Check>

## Troubleshooting Matrix

| Symptom                         | Likely Cause              | Action                                              |
| ------------------------------- | ------------------------- | --------------------------------------------------- |
| Pairing never completes         | Browser tab not confirmed | Re-open connect URL and approve                     |
| Pairing expired                 | Session timeout           | Start pairing again from dashboard                  |
| Connected then reconnect prompt | Key revoked/invalid       | Run browser pairing again or paste a new manual key |
| Manual key validation fails     | Wrong/expired key         | Generate a fresh API key and retry                  |
| Dashboard shows partial data    | OrgX API transient issue  | Refresh status and retry sync                       |

## Rotate, Revoke, Reconnect

1. Revoke plugin credentials from OrgX API key settings when rotating access.
2. In OpenClaw onboarding, click disconnect (or clear and reconnect).
3. Run browser pairing again to mint a fresh installation-scoped credential.

## Security Notes

* The plugin stores credentials in `~/.config/useorgx/openclaw-plugin/auth.json`.
* Directory and file permissions are restricted to local user access.
* Browser pairing avoids copy/paste secret handling on the primary path.

## What the Plugin Enables

The OpenClaw plugin gives you more than onboarding:

| Capability                                         | Source of truth in code                          | What you get                                            |
| -------------------------------------------------- | ------------------------------------------------ | ------------------------------------------------------- |
| Local MCP bridge (`/orgx/mcp`)                     | `orgx-openclaw-plugin/src/mcp-http-handler.ts`   | Call OrgX tools without separate hosted MCP OAuth setup |
| Domain-scoped MCP endpoints (`/orgx/mcp/{domain}`) | `ORGX_MCP_ALLOWED_TOOLS_BY_SCOPE`                | Safer default tool exposure by domain                   |
| Live dashboard (`/orgx/live`)                      | `orgx-openclaw-plugin/src/http/index.ts`         | Activity feed, mission control, decisions, run controls |
| Health + diagnostics                               | `orgx-openclaw-plugin/src/http/routes/health.ts` | Connection, outbox, replay, and runtime status checks   |

See the full code-generated tool matrix in [OpenClaw Plugin MCP Tools](/docs/api/openclaw-plugin-mcp-tools).

## Local MCP Bridge Endpoints

| Endpoint                                                          | Purpose                      |
| ----------------------------------------------------------------- | ---------------------------- |
| `http://127.0.0.1:18789/orgx/mcp`                                 | Full plugin MCP tool surface |
| `http://127.0.0.1:18789/orgx/mcp/engineering` (and other domains) | Domain-scoped subset         |

<Tip>
  The plugin can auto-register this local bridge in Claude/Codex/Cursor config
  files under the name `orgx-openclaw`.
</Tip>