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

#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:

     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:

     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

   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.

#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.

Resulting shape (placeholders, not real values):

{
  "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):

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:

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:

   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:

   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.