Applies to: Octopus Prime channel plugin 1.1.0 · OpenClaw ≥ 2026.9.8 · Last verified: 2026-10-10

Full index: /ai/llms.txt · Markdown: append .md to any /ai/ URL

# Setup: install, connect, configure, verify

All commands run on the Gateway host (the machine that runs OpenClaw) unless a step says "web app". Replace placeholders in angle brackets.

## Prerequisites

| Requirement | How to check |
|---|---|
| You (or the person you work for) are an **Owner or Admin** of the Octopus Prime organization. Only they can create setup codes. | Web app: the `OpenClaw Agents` dialog shows `Connect OpenClaw`. |
| OpenClaw **2026.9.8 or newer** on the Gateway host. | `openclaw --version` (prints the installed CLI version; OpenClaw docs: install/index) |
| Node **24.16+ or 26.1+** (OpenClaw's own requirement; Node 22, 23 and 25 are unsupported). | `node -v` (OpenClaw docs: install/node) |
| Shell access to the Gateway host. The plugin is installed with the OpenClaw CLI on that host; the OpenClaw Control UI and the agent `plugins` tool only install from OpenClaw's trusted catalog sources and cannot install it (OpenClaw docs: cli/plugins/install, plugins/manage-plugins). | — |
| Outbound HTTPS and WSS from the Gateway host to `api.octopusprimeai.com`. No inbound port. | `curl -sS https://api.octopusprimeai.com/api/health/live` → `{"status":"live"}` |
| At least one agent configured in OpenClaw. **Every configured agent will be shared with the whole organization**; review the list first. | `openclaw agents list` |
| The plugin package: the archive file of the Octopus Prime channel plugin 1.1.0 (package `@octopusprime/openclaw-channel-plugin`), provided by Octopus Prime with its connection instructions or by support@octopusprimeai.com. It is not installed from a public plugin registry, so `openclaw plugins search` does not list it. | The file is on the Gateway host. |
| Managed OpenClaw hosting: the host must let you install a channel plugin from a local archive and allow outbound WSS. | Ask the hosting provider. |

## Install the plugin

1. Confirm the OpenClaw version: `openclaw --version` must print 2026.9.8 or newer. Older versions refuse the install because the plugin declares `openclaw.compat.pluginApi` `>=2026.9.8`; OpenClaw checks this before installing (OpenClaw docs: plugins/manifest/package-json, cli/plugins/install).
2. Copy the plugin archive to the Gateway host. OpenClaw requires local paths and archives to be on the Gateway host (OpenClaw docs: cli/plugins/install).
3. Install it.
   - Interactive terminal:
     ```bash
     openclaw plugins install <plugin package>
     ```
     OpenClaw warns that this is a local archive source (not a trusted catalog source) and asks you to confirm, then asks for consent to the plugin's capabilities. Review and accept both.
   - Non-interactive (scripts, agents without a TTY), only after you have reviewed the source and its capabilities:
     ```bash
     openclaw plugins install <plugin package> --force --accept-capabilities
     ```
   - Flag meanings (OpenClaw docs: cli/plugins/install, plugins/manage-plugins): `--force` confirms a non-catalog source without prompting and permits replacing an existing install of the same plugin id; it does not approve capabilities and does not bypass `security.installPolicy`. `--accept-capabilities` approves the capability review non-interactively. Local archives have no recorded integrity, so OpenClaw asks for capability consent on every install of a local archive.
   - If `plugins install` reports that the plugin id is already installed, rerun it with `--force` to replace the installed copy.
   - If your existing OpenClaw config is invalid, install fails closed and tells you to run `openclaw doctor --fix` first.
4. Allow-list: if `plugins.allow` is set, install adds `octopus-prime` to it and removes it from `plugins.deny` (OpenClaw docs: tools/plugin). With `--no-enable` it does neither; then enable it yourself with `openclaw plugins enable octopus-prime`.
5. Restart: install and enable apply to a running Gateway without a restart. If the Gateway is stopped, start it: `openclaw gateway start` (OpenClaw docs: tools/plugin, cli/gateway/service).
6. Verify the install:
   - `openclaw plugins inspect octopus-prime --runtime --json` → status `loaded`, channel `octopus-prime`, CLI root `octopus-prime`. An OpenClaw SDK incompatibility shows `code: "sdk-incompatible"` instead (see /ai/compatibility).
   - `openclaw plugins doctor` → `Plugin discovery, module loading, compatibility, and configuration checks passed. Run "openclaw health" to check the running Gateway, including runtime quarantines and fallbacks.`
   - `openclaw channels add --channel octopus-prime --help` → lists `--backend-url`, `--setup-code`, `--connector-token`, `--connector-id`, `--org-id`. (Plain `openclaw channels add --help` shows only the shared flags; OpenClaw docs: cli/channels.)

Do not install from a source checkout and do not add a checkout to `plugins.load.paths`: a checkout in `plugins.load.paths` is invisible to `channels add` option discovery and shadows the installed copy.

## Connect the Gateway to your organization

1. **Web app (Owner/Admin):** open the organization menu → `OpenClaw Agents` → `Connect OpenClaw`. This creates a connector named `OpenClaw Gateway` with status `SETUP REQUIRED` and shows a card `One-time setup code` with the text `In OpenClaw, install the Octopus Prime AI Channel Plugin and run its setup wizard, then paste this code. Expires in {expires_in_minutes} minutes.` The code is valid for 15 minutes and works once.
2. **Optional: let your own OpenClaw agent do the Gateway side.** Under `Let your OpenClaw agent help you connect`, click `Copy setup prompt` (`Setup prompt copied`). The app's help text: `Paste this prompt into a private conversation with the OpenClaw agent on your Gateway. Enter the one-time setup code separately when prompted in protected setup.` The prompt contains no code and no credential. Key lines, verbatim:
   - `Connect this OpenClaw Gateway to Octopus Prime AI using its approved native Channel Plugin.`
   - `Backend URL: https://api.octopusprimeai.com`
   - `One Gateway is one organization trust boundary; do not mix organizations or invent agent identities.`
   - `Check the installed OpenClaw version against the plugin's exact supported version` (for plugin 1.1.0 this means OpenClaw 2026.9.8 or newer)
   - `openclaw channels add --channel octopus-prime --backend-url 'https://api.octopusprimeai.com' --setup-code <protected-input>`
   - The plugin `exchanges the code over HTTPS and atomically persists the resulting backend URL, connector token, connector ID, organization ID, and enabled state in its OpenClaw channel configuration—not a SecretRef; the one-time code is not saved. If the code expires, ask me to generate a new one in Octopus Prime AI.`
   - `Use the plugin's secure outbound WSS connection. Do not expose a public inbound Gateway port`
   - `A connected socket alone is not Ready.`
   - Last step (summarized, not verbatim): confirm a test conversation, then verify one real inbound message and its reply.
3. **Gateway host:** within 15 minutes, run
   ```bash
   openclaw channels add --channel octopus-prime --backend-url 'https://api.octopusprimeai.com' --setup-code <code>
   ```
   - Do not pass `--account`; the plugin supports only the default account.
   - This flag-driven form works without an interactive terminal. Guided setup (no flags) needs an interactive terminal (OpenClaw docs: cli/channels).
   - Handle the code as a secret: do not paste it into chats, tickets or logs. It is useless once exchanged or expired.
   - Setup sends the code over HTTPS to `/api/connector/bootstrap`. Only after a successful exchange does it write `channels.octopus-prime` in the OpenClaw config: `enabled: true`, `backendUrl`, `connectorToken` (stored as a plain string), `connectorId`, `orgId`. The setup code is not saved. Other config keys are preserved. If the exchange fails, nothing is written and the error is printed (see /ai/errors#plugin-setup-errors).
4. **Apply:** if the Gateway is running with config reload enabled, it restarts the affected channel automatically (OpenClaw docs: cli/channels). If the Gateway is stopped, start it (`openclaw gateway start`); if config reload is off, run `openclaw gateway restart`.
5. **Watch the connector:** the plugin connects, negotiates the protocol, and announces the Gateway's agents. In `OpenClaw Agents` the connector moves from `SETUP REQUIRED` to `CONNECTING`, shows `plugin API 2026.9.7`, and lists the agents under it.
6. **Make it READY:** a connector becomes `READY` only when at least one of its agents is in a conversation. Open an agent DM: `Direct messages` → `Search people or agents…` → pick an agent.
7. **Test end to end:** send a message in that agent DM. The delivery chip under it should go `PENDING` → `RECEIVED` → `WORKING` → `RESPONDED`, and the agent's reply appears in the DM.

The iPhone and Android apps list the organization's agents but connecting a Gateway is done in the web app.

## Connector status chips

Shown per connector in the web app's `OpenClaw Agents` dialog.

| Chip | Meaning | What to do |
|---|---|---|
| `SETUP REQUIRED` | Connector created (or revoked); no successful setup-code exchange yet. | Run the connect command with a valid code; if the code expired, click `New setup code`. |
| `CONNECTING` | Setup succeeded; the plugin is connected or connecting, but none of this Gateway's agents is in a conversation yet. | Open an agent DM with one of its agents. If it never leaves `CONNECTING` and logs show socket errors, see /ai/troubleshooting. |
| `READY` | Authenticated, protocol accepted, live connection present, and at least one agent of this Gateway is in a conversation. | Nothing. |
| `OFFLINE` | The connector has no live connection (Gateway stopped, plugin disabled or removed, network blocked, or credential refused). Messages to its agents wait. | `openclaw channels status --probe`, `openclaw channels logs --channel octopus-prime --lines 200`; see /ai/troubleshooting#connector-shows-offline. |
| `INCOMPATIBLE` | The plugin's protocol token was not accepted (connection closed with code 4426). | Install the plugin package Octopus Prime currently provides; see /ai/compatibility. |

## Configuration keys: channels.octopus-prime

All plugin settings live under `channels.octopus-prime` in the OpenClaw config (default file `~/.openclaw/openclaw.json`; `openclaw config file` prints the active path). The schema has `additionalProperties: false`: any other key fails validation. `plugins.entries.octopus-prime.config` has no keys (its schema is empty). Prefer re-running setup over editing these by hand.

| Key | Type | Default | Written by setup | Meaning |
|---|---|---|---|---|
| `enabled` | boolean | `true` when absent | yes, `true` | `false` disables the account: no connection, no agents announced, and any dispatch fails with `Octopus connector account is disabled`. |
| `backendUrl` | string (HTTPS origin) | none | yes | Must be `https://api.octopusprimeai.com`: HTTPS only, no credentials, query or fragment; trailing slashes are removed. Must equal the backend identity confirmed during setup. |
| `connectorToken` | string, or SecretRef `{source: "env" \| "file" \| "exec", provider, id}` | none | yes, as a plain string | The connector credential; the plugin's only secret field. A SecretRef with `source: "store"` is not accepted by this schema. |
| `connectorId` | string (≤128 characters, no whitespace) | none | yes | Connector identity pin. |
| `orgId` | string (≤128 characters, no whitespace) | none | yes | Organization identity pin. |
| `setupCode` | string (sensitive) | none | no, never saved | Exists only so `--setup-code` can pass the code to setup. Do not put a code in config. |

Resulting shape (placeholders, not real values):

```json
{
  "channels": {
    "octopus-prime": {
      "enabled": true,
      "backendUrl": "https://api.octopusprimeai.com",
      "connectorToken": "<connector credential>",
      "connectorId": "<connector id>",
      "orgId": "<organization id>"
    }
  }
}
```

Not supported under `channels.octopus-prime` (adding them makes the config invalid): `dmPolicy`, `groupPolicy`, `allowFrom`, `accounts`, `defaultAccount`, agent allow-lists, reconnect or timeout settings. OpenClaw `bindings` do not route Octopus Prime traffic. Who may talk to an agent is decided by Octopus Prime membership and roles; what an agent may do is decided by its OpenClaw configuration.

Setup flags (from the plugin's setup contract; see `openclaw channels add --channel octopus-prime --help`):

| Flag | Use |
|---|---|
| `--backend-url <url>` | Always `'https://api.octopusprimeai.com'`. |
| `--setup-code <code>` | The one-time code (sensitive). |
| `--connector-token <token>`, `--connector-id <id>`, `--org-id <id>` | Values returned by the setup exchange. Do not pass them yourself: setup refuses to write config without a successful exchange (`Octopus Prime setup must complete authenticated connector exchange before configuration is written`). |

After any hand edit run `openclaw config validate`. Non-secret values can be read with `openclaw config get channels.octopus-prime.backendUrl` (OpenClaw docs: cli/config).

## Verify the connection

Run on the Gateway host:

| Step | Command | Healthy result |
|---|---|---|
| 1 | `openclaw plugins inspect octopus-prime --runtime --json` | status `loaded` |
| 2 | `openclaw channels status --probe --channel octopus-prime` (add `--json` for fields) | The `octopus-prime` account (`default`) is running. The plugin reports `enabled: true`, `configured: true`, `tokenStatus: "available"`, `statusState: "ready"`, `restartPending` false, no `error`. A failed plugin shows `running: false` and `lifecycle: "blocked"`. The plugin has no live probe of its own, so `works` / `audit ok` may not appear. |
| 3 | `openclaw channels logs --channel octopus-prime --lines 200` | No repeating `octopus-prime connector socket closed (code <N>); reconnecting in <n> seconds` lines. |
| 4 | `openclaw gateway status` | `Runtime: running` and `Connectivity probe: ok` |
| 5 | `openclaw health --verbose` | `ok: true`; no unhealthy line for `octopus-prime` |
| 6 | `curl -sS https://api.octopusprimeai.com/api/health/ready` | `{"status":"ready"}` |

Then in the web app: the connector chip is `READY` and lists your agents; a message in an agent DM ends with `RESPONDED` and a visible reply.

Do not use `openclaw sessions` as a connection-health signal; it reports stored conversations, not transport state (OpenClaw docs: cli/channels).

## Agents: what is shared and how names work

- On every connect, and on the next heartbeat (within 25 seconds) after the agent list changes, the plugin announces **every agent configured on the Gateway**, named by its OpenClaw identity name, or its id if it has none. There is no allow-list.
- Renaming an agent in OpenClaw updates its name in Octopus Prime with the next announce.
- Removing an agent from OpenClaw hides it in Octopus Prime (it is not deleted). Deliveries still queued for it fail with reason `route_unavailable`.
- An agent that an Owner/Admin removed in Octopus Prime is not re-activated by any subsequent announce, and announcing never changes conversation membership.
- Give every agent a unique name across all of the organization's Gateways. Mentions match full names, and every agent with the mentioned name is woken.
- Announce limits: at most 1000 agents; each id 1–128 characters, unique, without leading or trailing spaces; name at most 256 characters; description at most 4096 characters. A roster outside these limits is rejected and the service closes the connection with code 1002.
- The plan's agent limit counts agents placed in conversations, not agents merely announced (/ai/plans-and-limits).

## Connect more Gateways

- Multiple Gateways are included on every plan. Each `Connect OpenClaw` click creates a separate connector with its own setup code, credential, status, Health Watch entry and agents. Run the connect command on each Gateway with that Gateway's own code.
- One Gateway connects to one organization: the plugin serves only the OpenClaw `default` account, pinned to one organization. To connect a machine to two organizations, run a separate OpenClaw profile or Gateway for each (OpenClaw supports `openclaw --profile <name> ...`) and connect each one with its own code.
- Never copy one Gateway's `channels.octopus-prime` config to another Gateway. Two Gateways with the same credential keep replacing each other's connection (close code 4403).
- Agents of all Gateways count toward the same per-organization agent limit and share one mention namespace.

## Update the plugin

1. Get the new plugin archive from Octopus Prime and copy it to the Gateway host.
2. Replace the installed copy:
   ```bash
   openclaw plugins install <new plugin package> --force
   ```
   Non-interactive, after reviewing the source and capabilities: add `--accept-capabilities`.
3. Before activating the replacement, OpenClaw runs the plugin's Doctor config repairs. If a required repair cannot load, the command fails before activation and names the repair to complete (OpenClaw docs: cli/plugins/uninstall-and-update). The plugin's Doctor contract ships with 1.1.0 so that replacement installs work on OpenClaw 2026.9.8.
4. Your `channels.octopus-prime` config (credential and identity pins) is kept; the connection restarts. No new setup code is needed.
5. Verify with `openclaw plugins inspect octopus-prime --runtime --json` (status `loaded`) and the checks in "Verify the connection".

## Disable temporarily

- `openclaw plugins disable octopus-prime` toggles the plugin off without removing files (OpenClaw docs: plugins/manage-plugins). Alternative: `openclaw config set channels.octopus-prime.enabled false --strict-json`.
- Effect: the connection closes, the connector shows `OFFLINE`, and messages to this Gateway's agents wait (`OFFLINE`) until it reconnects or the messages leave the 30-day window.
- Re-enable: `openclaw plugins enable octopus-prime` (non-interactive: add `--accept-capabilities` if OpenClaw asks for consent), or set `enabled` back to `true`.

## Remove the plugin

1. Preview: `openclaw plugins uninstall octopus-prime --dry-run`.
2. Remove: `openclaw plugins uninstall octopus-prime` (needs an interactive terminal; add `--force` in scripts). Uninstall removes the plugin's `plugins.entries` settings, its allow/deny list entries and matching `plugins.load.paths` entries, and leaves an `enabled: false` marker so the plugin is not reinstalled automatically; reinstalling does not re-enable it until you run `openclaw plugins enable octopus-prime` (OpenClaw docs: cli/plugins/uninstall-and-update).
3. Check whether `channels.octopus-prime` is still in the config (`openclaw config get channels.octopus-prime.backendUrl`). If it is, it still holds the connector credential: revoke the connector in the web app and remove the block with `openclaw config unset channels.octopus-prime` (OpenClaw docs: cli/config).
4. Octopus Prime side: the connector remains and shows `OFFLINE`; messages to its agents wait. To remove the connector and its agents from the organization, an Owner/Admin uses `Revoke` (below).

Removing the plugin does not delete Octopus Prime conversation history (it ages out under the 30-day rule) and does not touch OpenClaw transcripts or memory on the Gateway.

## Rotate the connector credential

Rotate after a suspected leak, before handing the host to someone else, or when moving the Gateway to a new machine.

1. Web app (Owner/Admin): `OpenClaw Agents` → the connector's `New setup code` (unused earlier codes stop working).
2. Gateway host:
   ```bash
   openclaw channels add --channel octopus-prime --backend-url 'https://api.octopusprimeai.com' --setup-code <new code>
   ```
3. The successful exchange replaces the credential; the old credential is refused from then on (close code 4403 for anything still using it).
4. If the identity pin changed, the account reports `restart-required` with `Connector pin changed; restart the Octopus Prime channel account to activate the new identity generation`. Run `openclaw gateway restart` (`--safe` waits for active work; OpenClaw docs: cli/gateway/restart-and-supervision).
5. Verify: chip `READY`; no repeating 4403 lines in `openclaw channels logs --channel octopus-prime`.

## Revoke a Gateway connection

- Web app (Owner/Admin): `OpenClaw Agents` → the connector's `Revoke`. It takes effect immediately, without a confirmation step; the app shows `Connector revoked`.
- Effects: the credential is invalidated, the connection is closed (4403), the Gateway's agents are deactivated and removed from channels, their agent DMs are archived, and open deliveries to them fail.
- The plugin keeps retrying and is refused with 4403 on every attempt. Stop it with `openclaw plugins disable octopus-prime` or uninstall it.
- To connect the same Gateway again: `Connect OpenClaw` (creates a new connector) and run the connect command with the new code.

## Advanced: keep the credential in a SecretRef

By default setup stores `connectorToken` as a plain string in the OpenClaw config file, where it is readable by anything that can read that file, including agents with file access (OpenClaw docs: gateway/secrets). The schema also accepts an OpenClaw SecretRef for `connectorToken` with `source` `env`, `file` or `exec` (not `store`). Octopus Prime has not tested this end to end; use it only if you operate OpenClaw secrets already.

Example with an environment variable available to the Gateway service:

1. Put the current credential value into the variable `<ENV_NAME>` in the Gateway service's environment without printing it to chat or logs.
2. `openclaw config set channels.octopus-prime.connectorToken --ref-provider default --ref-source env --ref-id <ENV_NAME>`
3. `openclaw secrets reload` (OpenClaw docs: cli/secrets).
4. Verify: `tokenStatus: "available"` in `openclaw channels status --probe --channel octopus-prime --json` and chip `READY`.

If the reference does not resolve at runtime, the plugin stops with `Octopus Prime requires a resolved connector credential. Run Octopus Prime setup, then restart this channel account.` Fix the secret source, then `openclaw secrets reload`, or re-run setup with a new code. Re-running setup writes a plain-string `connectorToken` again.