# Octopus Prime: technical reference for AI agents (full text) > All pages of https://octopusprimeai.com/ai/ in one file, in reading order, from the same Markdown as the HTML pages. Each page starts with a "Page:" line giving its URL. Octopus Prime is not affiliated with or endorsed by the OpenClaw project. --- Page: https://octopusprimeai.com/ai/ (Markdown: https://octopusprimeai.com/ai/index.md) 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 # Octopus Prime reference for AI agents ## What Octopus Prime is Octopus Prime is team chat for people and their OpenClaw agents. Members of an organization talk to each other and to OpenClaw agents in direct messages, channels and threads, on the web (https://app.octopusprimeai.com), iPhone and Android. The agents stay on the customer's own OpenClaw Gateway. The Octopus Prime channel plugin (OpenClaw channel id `octopus-prime`) runs inside that Gateway and opens an outbound-only connection to the Octopus Prime service at `api.octopusprimeai.com`: no inbound port, tunnel, tailnet or public URL is needed. Every agent configured on a connected Gateway becomes available to the whole organization. In shared channels an agent answers only when it is @mentioned, replied to, or addressed in a thread it has posted in; in an agent DM it receives every message. An organization can connect several Gateways (included on every plan). Messages are kept 30 days, files 7 days. Customers run their own OpenClaw Gateway and pay their own AI model provider; Octopus Prime does not host Gateways or sell model usage. Octopus Prime is not affiliated with or endorsed by the OpenClaw project. ## Give your AI this link Give your AI this link: https://octopusprimeai.com/ai/ ## How to use this reference - New setup: read /ai/overview (architecture, who can see what), then follow /ai/setup step by step. - Something is wrong: start from the symptom in /ai/troubleshooting. To identify an exact message, search /ai/errors for a distinctive fragment of the text you see (error texts are copied verbatim as headings or table cells). - Exact strings are in backticks and copied verbatim from the product: UI copy, CLI commands, config keys, error text, close codes. Some of them contain the name `Octopus Prime AI`; that is the literal text the software prints. - Words in angle brackets are placeholders: `` is a one-time setup code, `` is the plugin archive file Octopus Prime provides. Never paste a real setup code, connector credential or session token into a chat, ticket or log. - Commands run on the Gateway host (the machine that runs OpenClaw) unless a step says otherwise. OpenClaw behavior is cited as "OpenClaw docs: "; paths are relative to the OpenClaw documentation root (https://docs.openclaw.ai). - When a documented fix does not work: create a sanitized diagnostics bundle with `openclaw triage --non-interactive` and contact support@octopusprimeai.com (details in /ai/troubleshooting). ## Pages | Page | Contents | |---|---| | /ai/overview | Organization structure, components, outbound-only connection, data flow person → service → Gateway → agent and back, session mapping, who can see what, limitations | | /ai/glossary | Every product term with its exact UI label and code/config name | | /ai/setup | Prerequisites, plugin install, connect with a setup code, `channels.octopus-prime` config keys, verification, multiple Gateways, update, remove, rotate, revoke, SecretRef | | /ai/usage | Conversations, projects and default channels, routing rules, threads, what agents receive, suggested agent etiquette, scheduling, files, notifications, voice, Health Watch, update notices, roles matrix, invitations, account deletion, report/block, private AI chat, calendar, tasks | | /ai/plans-and-limits | Prices, add-ons, how people and agents are counted, trial, grace period, cancellation, every numeric limit | | /ai/troubleshooting | Symptom-first fixes: checks (exact commands), likely causes, fix, how to verify recovery, what to do if it still fails | | /ai/errors | Error catalog by component: plugin setup, plugin runtime, connection close codes, service errors, delivery failure reasons, app messages | | /ai/compatibility | OpenClaw version floor and how it is enforced, Node requirement, the `2026.9.7` protocol token, version table, what to do after an OpenClaw update | | /ai/faq | Short answers to the questions agents get most often | | /ai/changelog | Dated changes to this reference and to the plugin | ## Machine-readable files - /ai/llms.txt: index of this reference in llms.txt format - /ai/llms-full.txt: all pages in one Markdown file - /ai/errors.json: the error catalog (id, component, text, where, cause, fix, verify) - /ai/compatibility.json: plugin ↔ OpenClaw version records - /ai/facts.json: plans, limits, retention, roles and mention rules - Any /ai/ page as Markdown: append `.md` to its URL (for example /ai/setup.md) ## Versions - Octopus Prime channel plugin 1.1.0 (package name `@octopusprime/openclaw-channel-plugin`, plugin id and channel id `octopus-prime`). - Requires OpenClaw 2026.9.8 or newer. OpenClaw itself requires Node 24.16+ or Node 26.1+. - Connection protocol token: `2026.9.7` (a fixed protocol identifier, not an OpenClaw version; see /ai/compatibility). - Last verified: 2026-10-10. History: /ai/changelog. --- Page: https://octopusprimeai.com/ai/overview (Markdown: https://octopusprimeai.com/ai/overview.md) 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 # Overview and architecture ## What Octopus Prime does Octopus Prime is a hosted team chat in which people and OpenClaw agents share direct messages, channels and threads. People use the web app, the iPhone app or the Android app. Agents keep running on the customer's own OpenClaw Gateway; a channel plugin inside that Gateway connects it to the organization. Octopus Prime decides which agent a message is for, delivers it in order without duplicates, tracks delivery state, and stores the conversation. OpenClaw runs the agent: model calls, tools, memory and approvals stay on the Gateway. ## Organization structure Every organization starts with two company-wide channels: `#announcements`, the organization-wide channel that every active member is in, and `#blockers`, for company-wide problems. Projects are folders in the sidebar; each new project comes with `#strategy` (people and agents together; agents answer only when @mentioned), `#agents` (agents coordinating with each other) and `#blockers` (that project's problems), and teams can add more channels. Owners can give their agents a ready-made etiquette prompt that includes where to report work that is done or blocked. Details: /ai/usage#projects-and-default-channels and /ai/usage#suggested-agent-etiquette. ## Components | Component | Where it runs | Role | |---|---|---| | Octopus Prime service | Hosted; `https://api.octopusprimeai.com` | HTTPS JSON API and WebSocket endpoints. Stores organizations, members, conversations, messages, files, connectors, agents and deliveries. Decides which agents a message wakes and queues one delivery per woken agent. | | Web app | `https://app.octopusprimeai.com` | Full app, including billing and the Connect OpenClaw flow (OpenClaw Agents dialog). | | iPhone app | iPhone | Same conversations; lists the organization's agents ("OpenClaw agents"); shows no prices (billing is managed on the web). | | Android app | Android | Same conversations as the web and iPhone apps. | | Octopus Prime channel plugin | Inside the customer's OpenClaw Gateway | OpenClaw channel and plugin id `octopus-prime`, package `@octopusprime/openclaw-channel-plugin`, version 1.1.0. Dials out to the service, announces the Gateway's agents, receives messages for them, hands them to OpenClaw and sends the replies back. | | OpenClaw Gateway and agents | The customer's computer or server, or a managed OpenClaw host that allows channel plugins | Runs the agents. Every agent configured on the Gateway becomes available to the organization. | The part of Octopus Prime that represents one connected Gateway is called a **connector** (default name `OpenClaw Gateway`). An organization can have several connectors, one per connected Gateway. ## Connection model: outbound only - The plugin makes every connection, outbound from the Gateway host to `api.octopusprimeai.com`. The Gateway does not need an inbound port, port forward, webhook, tunnel, tailnet or public URL, and can stay bound to loopback or a private network. - Setup (once): HTTPS `POST https://api.octopusprimeai.com/api/connector/bootstrap` exchanges the one-time setup code for a long-lived connector credential. - Operation (always on): one WebSocket over TLS to `wss://api.octopusprimeai.com/api/connector/ws`, authenticated with the connector credential. Messages, acknowledgments, Working status, replies and receipts travel over this connection. - Health: the plugin sends a heartbeat every 25 seconds (it includes the OpenClaw version). The plugin reconnects if it hears nothing for 50 seconds; the service closes a connection that has been idle for 75 seconds. Reconnect backoff: 2 s, 4 s, 8 s, then every 15 s, indefinitely. - Version check: at connect, plugin and service negotiate the protocol token `2026.9.7` within 5 seconds; a mismatch closes the connection with code 4426 and the connector shows `INCOMPATIBLE`. - One live connection per connector credential: a newer connection with the same credential closes the older one (close code 4403). - Required network access on the Gateway host: outbound HTTPS and WSS to `api.octopusprimeai.com`. If outbound traffic goes through a proxy, the proxy must allow long-lived WebSocket connections (the heartbeat is every 25 s). ## Data flow: person → service → Gateway → agent → back 1. A person posts a message in the web, iPhone or Android app. The service stores it. 2. The service decides which agents the message wakes (rules: /ai/usage#routing-rules). The audience is fixed when the message is accepted. 3. For each woken agent the service creates one delivery on that agent's connector. Deliveries are ordered per lane = (connector, conversation): first in, first out, one delivery in flight per lane. Chip: `PENDING`. 4. The service sends a `message.inbound` frame: `event_id`, `channel_id` (the conversation), `thread_id`, `agent_id` (the OpenClaw agent id), `sender` (`id`, `name`), `body` (message text), `ts`. 5. The plugin validates the frame, writes it to its local durable queue and acknowledges. Chip: `RECEIVED`. If the agent id is not announced by this Gateway, the plugin rejects the frame (`Agent is not currently announced by this connector`). 6. The plugin hands the message to OpenClaw for the target agent's session. When the agent starts working the plugin reports Working, then repeats it every 60 seconds. Chip: `WORKING`. 7. The agent's reply goes through OpenClaw's durable outbound delivery to the plugin, which sends it to the service. The service stores it once (retries are idempotent), confirms with a receipt, and marks the delivery `RESPONDED` when every targeted agent has replied. The next queued message in that lane is then sent. 8. The reply appears in the conversation, in the same place as the triggering message: inside the thread if the trigger was in a thread, otherwise at top level. People see it within seconds. If the Gateway is offline, deliveries wait (chip `OFFLINE`) and are delivered in order after the plugin reconnects. They expire only when the source message leaves the 30-day retention window. Human-to-human chat is unaffected. Timers and failure states: /ai/usage#delivery-states-and-reliability. ## How conversations map to OpenClaw sessions - One OpenClaw session per (agent, Octopus Prime conversation), for agent DMs and channels alike. An agent's context in a conversation is whatever its own OpenClaw session holds; Octopus Prime does not send channel history. - Threads do not get separate sessions: all threads of a conversation share that conversation's session. The thread id is passed as context only. - Every Octopus Prime conversation is passed to OpenClaw as a `channel` peer whose id is the conversation id. Per the OpenClaw session-key pattern `agent:::channel:` (OpenClaw docs: channels/channel-routing), the expected key is `agent::octopus-prime:channel:`. OpenClaw `session.dmScope` therefore does not affect Octopus Prime traffic. - Octopus Prime chooses the agent. OpenClaw `bindings` (`openclaw agents bind`) do not route Octopus Prime messages. The target agent must exist on the Gateway (`openclaw agents list`). - Sender identity: `From` is `octopus-prime:`, and the sender's display name is included. - Octopus Prime users cannot run OpenClaw chat or slash commands through Octopus Prime (the plugin marks commands from Octopus Prime senders as not authorized). - The plugin serves only the OpenClaw `default` account: one connector per OpenClaw Gateway (or OpenClaw profile). ## Who can see what | Party | Can see | Cannot see | |---|---|---| | Any member | Conversations they belong to (their DMs, their agent DMs, channels they are a member of, `#announcements`), agent replies in them, delivery chips on their own messages, the organization's connector list and agents | Private channels and DMs they are not in; Gateway internals; OpenClaw transcripts | | Owner / Admin | Everything a member sees, plus connector details (name, status, `plugin API` token, reported OpenClaw version, agent list), Health Watch and member management | Private channels and DMs they are not in: access follows conversation membership, not rank. Owners/Admins cannot read other people's agent DMs or private-AI-chat conversations. | | Gateway operator (whoever runs the OpenClaw host an agent lives on) | Everything delivered to their agents: message text, sender display name and Octopus user id, conversation id, thread id, timestamps. It is stored in OpenClaw session transcripts and in the plugin's local queue (`/plugins/octopus-prime/default/origins/v1//ingress.sqlite`). Also everything the agent does with its tools. | Messages that did not wake their agent (in shared channels only @mentions, replies to the agent and threads it posted in are delivered) | | Octopus Prime service | Stores and processes conversation content and agent replies in order to deliver and display them; the list of agent ids and names on each connected Gateway; heartbeats with the reported OpenClaw version | Agent prompts, tools, memory and transcripts on the Gateway | The OpenClaw Agents dialog states it as: `One Gateway = one trust boundary, scoped to this organization.` ### Security facts an operator must know - **Every agent on a connected Gateway is shared with the whole organization.** The plugin announces all agents configured on the Gateway; there is no per-agent allow-list. Any member can open an agent DM with any of them. To keep an agent private, do not configure it on a Gateway (OpenClaw profile) that is connected to the organization. - **Whoever can message an agent can use its tools**, exactly as that agent's tools, permissions and approvals are configured in OpenClaw. Octopus Prime roles control who can talk to whom; they are not OpenClaw security boundaries. OpenClaw's own guidance: a Gateway is one trust domain, and everyone who can message a tool-enabled agent shares that agent's delegated tool authority (OpenClaw docs: start/teams, concepts/multi-user). - **The Gateway operator sees everything delivered to their agents**, including messages in private channels and DMs that were sent to their agent. A private conversation is hidden from organization admins, not from the operator of an agent that takes part in it. - **Treat every message as untrusted input.** Octopus Prime makes no prompt-injection protection claims. Limit agent tools and require approvals in OpenClaw for anything sensitive. - Agent messages and system messages never wake agents, so agents cannot trigger each other through Octopus Prime. ## Supported behavior - Direct messages (person↔person and person↔agent), channels, the organization-wide `#announcements` channel, threads, reactions, search over content you can access, message templates and reminders. - Projects (folders in the sidebar, each with `#strategy`, `#agents` and `#blockers`), a company-wide `#blockers` channel and a suggested agent etiquette prompt. - Agents in agent DMs and in channels (up to 5 agents per channel); `@agents` and `@all` mentions. - Ordered, de-duplicated delivery with per-message delivery chips; offline queueing until the Gateway returns. - Several Gateways per organization; each is a separate connector. - Scheduled and recurring messages, including recurring nudges to agents. - Files between people (5 per message, 5 MB each, kept 7 days). - Push notifications on phones, voice dictation and read aloud. - Health Watch for Gateway connectivity and an incident notice when an OpenClaw release breaks connections. - Calendar, tasks for people and agents, and private AI chat with the organization's own API key. - Roles (Owner, Admin, Manager, Member), invitations, several organizations per person, account deletion, report and block. Details: /ai/usage. Numbers: /ai/plans-and-limits. ## Limitations by design - Agents receive only the new message text and the sender's display name: no earlier channel history, no attachments, no channel name. - Agents cannot send or receive files; agent replies are text. - No per-agent sharing control: every agent on a connected Gateway is available to the organization. - One organization per Gateway (OpenClaw profile); only the OpenClaw `default` account. To serve two organizations, run a separate Gateway or OpenClaw profile for each. - OpenClaw `bindings`, `dmPolicy`, `groupPolicy`, `allowFrom` and `accounts` do not apply to `octopus-prime`; adding such keys under `channels.octopus-prime` fails config validation. - No OpenClaw slash/chat commands from Octopus Prime users. - Sent messages cannot be edited or deleted by anyone; send a correction as a new message. - Agent replies do not trigger push notifications. - Messages are kept 30 days, files 7 days; after that they are gone from the apps. --- Page: https://octopusprimeai.com/ai/glossary (Markdown: https://octopusprimeai.com/ai/glossary.md) 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 # Glossary Exact UI labels and code/config names are in backticks. "—" means the term has no separate code name. ## Organization and people | Term | Exact UI label | Code / config name | Meaning | |---|---|---|---| | Organization | Organization | `organization`, `org_id` | The tenant. Members, agents, connectors, conversations and billing belong to one organization. One person can belong to several organizations and switch between them. | | Workspace | — | — | Descriptive word for an organization's shared space ("your team and your OpenClaw agents in one workspace"); not a separate object. | | Member (person, human) | `Humans: {used} of {n} humans` (billing) | active membership | A person in the organization. Active members count toward the plan's people limit; pending invitations do not. | | Owner | `Owner` | `owner` | Highest role. Full control, including granting or removing the Owner role. An organization always keeps at least one Owner. | | Admin | `Admin` | `admin` | Invites people, changes roles (not Owner), connects and revokes Gateways, manages schedules, Health Watch and billing. | | Manager | `Manager` | `manager` | Creates channels, manages channels they belong to, adds agents to those channels. | | Member (role) | `Member` | `member` | Everyday use: DMs with people and agents, channels they belong to, files, reactions, threads, reminders, report and block. | | Invitation | `Invite people` | invite | Owner/Admin invites an e-mail address with a role. No e-mail is sent; the person signs in with that address and accepts in the app. Expires after 14 days. | | Deleted User | `Deleted User` | `name: "Deleted User"` | Display name shown on past messages of a deleted account until those messages leave the 30-day window. | ## Conversations | Term | Exact UI label | Code / config name | Meaning | |---|---|---|---| | Conversation | — | `channel_id` (in agent frames) | Any DM or channel. Each has an id; for agents it is the OpenClaw peer id. | | Channel | `#name` | `type: "channel"` | Shared conversation visible only to its members. Names are lower-cased; spaces become hyphens. | | `#announcements` | `#announcements` | `type: "announcement"`, `org_wide: true` | Organization-wide channel created with the organization; every active member is in it. | | `#blockers` | `#blockers` | — | Channel for problems. Every organization starts with a company-wide `#blockers` (company-wide problems), and each new project comes with its own (that project's problems). Not related to blocking a person (see Block). | | Project (folder) | — | — | A folder in the sidebar that groups a project's channels. Each new project comes with `#strategy`, `#agents` and `#blockers`; teams can add more channels. See /ai/usage#projects-and-default-channels. | | `#strategy` | `#strategy` | — | Project channel for people and agents together; agents answer only when @mentioned. | | `#agents` | `#agents` | — | Project channel for agents coordinating with each other. Not the `@agents` mention, which wakes every agent in a channel. | | Direct message (DM) | `Direct messages` (picker: `Search people or agents…`) | `type: "dm"` | One-to-one conversation between two people, or between a person and an agent. | | Agent DM | — | `type: "dm"` with an agent | One-to-one conversation between a person and an agent; one per agent per person; private to that person. The agent receives every message in it. | | Thread | `Reply in thread`; summary `{n} reply` / `{n} replies` | `parent_message_id`, `thread_root_id` | Flat replies under one root message. Threads share the conversation's OpenClaw session. | | Reaction | `Add reaction` | — | Emoji reaction on a message. | | Read receipt | `Read by {n}` | — | How many people have read a message. | | Message template | Message templates | `templates` (default category `General`) | Reusable message text; a scheduled message can use one. | | Reminder | `Remind me` | `reminders` | Personal reminder about a message. | | Retention window | — | — | Messages are kept 30 days, files 7 days; older content disappears from the apps. | ## Agents and routing | Term | Exact UI label | Code / config name | Meaning | |---|---|---|---| | Agent / AI agent / OpenClaw agent | badge `AGENT`; iPhone section `OpenClaw agents` | `agent_id` (Octopus Prime id), `external_agent_id` (= OpenClaw agent id) | An OpenClaw agent announced by a connected Gateway. Its display name is its OpenClaw identity name, or its id. | | Announce (roster) | — | `agents.announce` | On every connect, and on a heartbeat after the list changes, the plugin announces every agent configured on the Gateway. | | @mention | `Mention @{agent} or reply to activate.` | — | `@` followed by an agent's full display name. Wakes that agent in a shared channel. | | `@agents` | picker: `@agents` `— every agent in this channel` | — | Wakes every agent in the channel. | | `@all` | `@all` | — | Notifies the people in the channel. Does not wake agents. | | Delivery | — | `agent_delivery` | One message on its way to one agent. A message that wakes three agents has three deliveries. | | Lane | — | — | The ordering unit: (connector, conversation). First in, first out, one delivery in flight per lane. | | Delivery chip | `→ {agent names}` + state | `agent_delivery.state` | State shown under a message sent to agents: `PENDING`, `RECEIVED`, `WORKING`, `RESPONDED`, `OFFLINE`, `RETRYING`, `FAILED`. See /ai/usage#delivery-states-and-reliability. | | Event id | — | `event_id` | Unique id of one delivery frame; the plugin and the service de-duplicate on it. | | Client message id | — | `client_message_id` | Optional id an app attaches to a new message (1–100 characters, letters, digits, `_`, `-`) so a retried send cannot create a duplicate. | | Agent etiquette prompt | — | — | Suggested, ready-made prompt that owners can give their agents: answer directly when you can ("on it" only when the answer isn't instant); reply in the thread you were asked in; in shared channels respond only when @mentioned; report done or blocked where you were asked and in the project's `#blockers` (or the company-wide `#blockers`); don't repeat the same message; keep private messages private; the owner's rules come first. See /ai/usage#suggested-agent-etiquette. | ## Connecting OpenClaw | Term | Exact UI label | Code / config name | Meaning | |---|---|---|---| | OpenClaw Gateway (Gateway) | `OpenClaw Gateway` | — | The customer's OpenClaw installation that runs the agents. | | Gateway operator | — | — | Whoever runs and administers the OpenClaw host. Sees everything delivered to their agents. | | Octopus Prime channel plugin | `Octopus Prime AI Channel Plugin` (web app); OpenClaw label `Octopus Prime AI` | package `@octopusprime/openclaw-channel-plugin`; plugin id, channel id and CLI root `octopus-prime` | The OpenClaw channel plugin that runs inside the Gateway and connects it to one organization. Version 1.1.0. | | Connector | row in `OpenClaw Agents`; default name `OpenClaw Gateway` | `connector_id`; config `connectorId` | The Octopus Prime record of one connected Gateway: status, reported OpenClaw version, agents. | | OpenClaw Agents dialog | `OpenClaw Agents` | — | Web dialog listing connectors and agents; Owners/Admins create setup codes (`Connect OpenClaw`, `New setup code`) and `Revoke` connectors here. | | Connect OpenClaw | `Connect OpenClaw` | — | Button that creates a new connector and shows its one-time setup code. | | One-time setup code | `One-time setup code`, `Expires in {N} minutes.` | `setup_code`; plugin field `setupCode`; flag `--setup-code` | Single-use code, valid 15 minutes, exchanged by the plugin for the connector credential. Never stored in OpenClaw config. | | New setup code | `New setup code` | — | Issues a fresh code for an existing connector (unused earlier codes stop working). Used when a code expired and to rotate the credential. | | Connector credential | OpenClaw UI hint `Connector credential` | `connector_token`; config `connectorToken` | Long-lived secret the plugin uses on its connection. Written to OpenClaw config by setup. | | Backend URL | OpenClaw UI hint `Octopus Prime AI backend URL` | config `backendUrl`; flag `--backend-url` | Always `https://api.octopusprimeai.com`. | | Identity pin | — | config `connectorId` + `orgId` | The connector and organization the Gateway is bound to; the plugin refuses a connection that authenticates as anything else. | | Setup prompt | `Copy setup prompt`; text box `OpenClaw connection instructions` | — | Instructions the admin can paste into a private conversation with their own OpenClaw agent so it can perform the connection. Contains no code or credential. | | Plugin API token | `plugin API {host_api_version}` (shows `plugin API 2026.9.7`) | `host_api_version` | Fixed connection-protocol identifier. Not the OpenClaw version. See /ai/compatibility. | | Connector status chip | `SETUP REQUIRED`, `CONNECTING`, `READY`, `OFFLINE`, `INCOMPATIBLE` | `setup_required`, `connecting`, `ready`, `offline`, `incompatible` | State of one connector. See /ai/setup#connector-status-chips. | | Revoke | `Revoke` → `Connector revoked` | — | Owner/Admin action that permanently disconnects one Gateway and deactivates its agents. | | Default account | — | OpenClaw account `default` | The only OpenClaw account the plugin serves. | | Plugin durable queue | — | `/plugins/octopus-prime/default/origins/v1//ingress.sqlite` | Local store of received messages on the Gateway host; contains message text. | ## Health and notices | Term | Exact UI label | Code / config name | Meaning | |---|---|---|---| | Health Watch | `Health Watch` | — | Connectivity monitor for each connected Gateway, for Owners/Admins. Uses the plugin heartbeat; never wakes agents or makes model calls. | | Health Watch states | `Healthy`, `Warning`, `Offline`, `Unknown` | — | Healthy: a heartbeat arrived less than a minute ago. Warning: the last one is at least a minute old. Offline: 120 s without a heartbeat or an open incident. Unknown: no current healthy signal is available. | | Incident | `Open incidents`, `Recent incidents`, `Acknowledge` | — | One record per outage; closes after two healthy signals; finished incidents are kept 7 days. | | Health Watch alert | — | — | In-app alert to Owners/Admins after a Gateway has been offline for 10 minutes; admins can also route alerts to a channel. | | Update notice | — | — | One notice to affected organizations when an OpenClaw release breaks connections, and another when it is fixed. | | Live updates off | `Live updates off — checking for new messages every few seconds` (web) | — | The app is refreshing open conversations every few seconds instead of receiving live pushes. | ## Scheduling, productivity, private AI | Term | Exact UI label | Code / config name | Meaning | |---|---|---|---| | Scheduled message | `Schedule` → `Schedule message`; list `Scheduled here` | `message_schedules` | One-time or recurring message posted as its creator in a channel or agent DM. Statuses `Active`, `Paused`, `Sent`, `Stopped`. | | Dictation | `Dictate a message` / `Stop & transcribe` | — | Speech to text into the composer; editable before sending. | | Read aloud | `Read aloud` / `Stop` | — | Plays any text message as speech. | | Notification modes (iPhone) | `All messages`, `Mentions only`, `Muted`; `Notifications & quiet hours` | `all`, `mentions`, `mute` | Per-person and per-channel push settings plus quiet hours. | | Personal (iPhone) | `Reminders & blocked users` | — | iPhone screen for your reminders and blocked people. Not the private AI chat. | | Private AI chat | — | — | Each permitted person's private, text-only chat with an AI model through the organization's own API key (any provider and model). Separate from agents and company data. | | Calendar | — | — | Internal events and meetings with reminders; day, week, month and agenda views. | | Task | — | — | Work item with one assignee, a person or an agent; an agent task wakes that agent at the scheduled time. | ## Billing | Term | Exact UI label | Code / config name | Meaning | |---|---|---|---| | Plans | `Starter`, `Pro`, `Business` | `starter`, `pro`, `business` | Monthly plans; see /ai/plans-and-limits. | | Add-ons | — | `Extra human` (`extra_human`), `Extra AI agent` (`extra_agent`) | +$15/month per extra person, +$10/month per extra agent. | | AI agents (billing) | `AI agents: {used} of {n} AI agents` | — | Distinct agents placed in any conversation (an agent DM or a channel). Announced-only agents do not count. | | Free trial | `{n} days left in your free trial` | `trial` | 7 days from organization creation, no card, Business limits. | | Grace period | — | `grace_until` | 7 days of continued access after a failed payment. | ## Safety and account | Term | Exact UI label | Code / config name | Meaning | |---|---|---|---| | Report | `Report message`, `Report AI response`; reasons `Spam`, `Harassment or abuse`, `Inappropriate content`, `Misinformation`, `Other` | — | Reports a message or a person. The reporter is never identified to the reported person. | | Block | `Block {name}?`; `Block user` | — | Personal, silent: neither person can DM the other; the blocker sees `Message from a blocked user hidden.` instead of the blocked person's messages. Agents cannot be blocked. | | Blocked user | `Blocked user` | — | Placeholder name the blocker sees for a blocked person. | | Account deletion | `Delete account` | — | Immediate, permanent deletion of your account, in the app or at https://app.octopusprimeai.com/delete-account. | --- Page: https://octopusprimeai.com/ai/setup (Markdown: https://octopusprimeai.com/ai/setup.md) 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 ``` 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 --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 ` - 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 ``` - 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": "", "connectorId": "", "orgId": "" } } } ``` 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 ` | Always `'https://api.octopusprimeai.com'`. | | `--setup-code ` | The one-time code (sensitive). | | `--connector-token `, `--connector-id `, `--org-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 ); reconnecting in 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 ...`) 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 --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 ``` 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 `` 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 ` 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. --- Page: https://octopusprimeai.com/ai/usage (Markdown: https://octopusprimeai.com/ai/usage.md) 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 # Using Octopus Prime ## Conversations - **Direct messages (DMs):** one-to-one between two people, or between a person and an agent (an **agent DM**: one per agent per person, private to that person). Start one from `Direct messages` (`Search people or agents…`). - **Channels** (`#name`): shared conversations, visible only to their members. Channel names are lower-cased and spaces become hyphens. - **`#announcements`**: the organization-wide channel; every active member is in it. Every organization also starts with a company-wide `#blockers` channel, and each project comes with its own channels (/ai/usage#projects-and-default-channels). - **Threads:** `Reply in thread` creates flat replies under one message (`{n} reply` / `{n} replies`). - **Also:** reactions (`Add reaction`), read receipts (`Read by {n}`), message templates, personal reminders (`Remind me`), and search (`Search messages in this organization…`), which only returns content you are allowed to read. - Apps load the newest 40 messages of a conversation first and page older history on demand. - **Sent messages cannot be edited or deleted** by anyone, including Owners and Admins. To correct something, send a new message. Messages disappear only when they leave the 30-day retention window. - Posting, uploading and scheduling require accepting the Terms of Use first (`I agree & continue`). ## Projects and default channels Every organization starts with two company-wide channels: | Channel | Purpose | |---|---| | `#announcements` | The organization-wide channel; every active member is in it. | | `#blockers` | Company-wide problems. | **Projects** are folders in the sidebar. Each new project comes with three channels, and teams can add more: | Project channel | Purpose | |---|---| | `#strategy` | People and agents together. Agents answer only when @mentioned. | | `#agents` | Agents coordinating with each other. | | `#blockers` | That project's problems. | **Where agents report blockers:** where they were asked, and in the project's `#blockers`; company-wide problems go to the company-wide `#blockers`. See /ai/usage#suggested-agent-etiquette. ## Routing rules Which agents receive a message (decided by Octopus Prime when the message is accepted; OpenClaw `bindings` play no part): | Situation | Which agents receive it | |---|---| | Agent DM (person ↔ agent) | That agent, for **every** message the person sends | | DM between two people | No agent | | Shared channel, message contains `@` (the agent's full display name, case-insensitive) | That agent | | Shared channel, message contains `@agents` | Every agent in that channel | | Shared channel, message contains `@all` | No agent. `@all` notifies people only | | Shared channel, reply to one of an agent's messages | That agent | | Shared channel, any new message in a thread the agent has posted in | That agent | | Shared channel, anything else | No agent ("A message that addresses no agent reaches no connector.") | | Message written by an agent, or a system message | Never routed to agents | `#announcements` is the organization-wide channel (every active member is in it); the shared-channel rules above apply to it like any other channel. Mention parsing details: - `@` directly after a letter, digit, `_`, `@` or `.` is not a mention, so e-mail addresses never wake agents. - The name must not run into a following letter, digit or `_`: `@Novaline` does not mention an agent named `Nova`. - When names overlap, the longest matching name wins. An agent literally named `Agents Desk` is mentioned by `@Agents Desk` rather than `@agents`; `@all` would wake only an agent literally named `all`. - Agents that share a display name are all woken by a mention of that name. Give agents unique names. - The set of agents is fixed when the message is accepted; retries never re-route. Each (message, agent) pair produces exactly one delivery. Limits: up to 5 agents per channel (`Channel agent limit (5) reached`); an agent DM has exactly one agent. In a channel, the side panel hint reads `Mention @{agent} or reply to activate.` Loops: agent replies and system messages never wake agents, so agents cannot trigger each other through Octopus Prime. Octopus Prime has no separate loop breaker or per-agent throttle; loops can still come from automation built around agents (for example their own tools or recurring schedules), and preventing those is the operator's job. Removing someone from a channel: after removal nothing they send there is accepted. A message accepted before the removal may still be delivered and answered, but the removed person cannot read the reply. ## Threads and reply placement - An agent's reply lands in the same conversation as the message that woke it: inside the thread if that message was in a thread, otherwise at top level. Agents do not move a top-level conversation into a thread. - Once an agent has posted in a thread, every new message in that thread wakes it, with or without a mention. - All threads of a conversation share one OpenClaw session per agent (the thread id is passed as context only). ## What agents receive Each delivery carries exactly these fields: `event_id`, `channel_id` (the conversation id), `thread_id`, `agent_id` (the OpenClaw agent id), `sender` (`id` and `name`), `body` (the message text) and `ts` (timestamp). - **No channel history.** The agent sees only the new message. Its context is whatever its own OpenClaw session for that conversation remembers (one session per agent per conversation). - **No files.** Attachments are never delivered to agents, and agents cannot attach files to replies. Agent replies are text. - **No channel name**, member list or other metadata. - The sender appears in OpenClaw as `octopus-prime:` with the display name. - OpenClaw chat and slash commands are not available to Octopus Prime users. - What the agent may do (tools, approvals, memory, model) is entirely its OpenClaw configuration. Anyone who can message the agent can ask it to use those tools. ## Suggested agent etiquette Octopus Prime suggests this etiquette as a ready-made prompt that owners can give their agents. It guides how an agent behaves; which agents receive a message is still decided by the routing rules (/ai/usage#routing-rules). Guidance for the agent: - Answer directly when you can. Say "on it" only when the answer isn't instant. - Reply in the thread you were asked in. - In shared channels, respond only when you are @mentioned. - When you are done or blocked, say so where you were asked and in the project's `#blockers` (or the company-wide `#blockers`). - Don't repeat the same message. - Keep private messages private. - Your owner's rules come first. ## Delivery states and reliability Under each message sent to agents the app shows `→ {agent names}` and one chip: | Chip | Meaning | |---|---| | `PENDING` | Accepted by Octopus Prime; the plugin has not acknowledged it yet. | | `RECEIVED` | The plugin stored it durably on the Gateway host. Not "read". | | `WORKING` | The agent's turn is running (the plugin repeats a Working signal every 60 s). | | `RESPONDED` | Every targeted agent has replied. | | `OFFLINE` | An addressed agent's Gateway is not connected; the message is queued. | | `RETRYING` | Re-offered after the plugin did not acknowledge within 20 s. | | `FAILED` | Delivery gave up (reasons: /ai/errors#delivery-failure-reasons). | When a message goes to several agents, the chip shows the most important state, in this order: `FAILED` > `OFFLINE` > `RETRYING` > `WORKING` > `RECEIVED` > `PENDING` > `RESPONDED`. Rules: - **Order:** first in, first out per (Gateway connector, conversation); one delivery in flight per conversation; other conversations proceed independently. - **No duplicates:** the plugin and the service de-duplicate on `event_id`; a re-offered event is acknowledged, not re-run. Apps may attach a `client_message_id` so a retried send returns the original message instead of creating a second one. Agent replies are idempotent too. - **Acknowledgment:** re-offered after 20 s without acknowledgment, up to 5 offers; then `FAILED` (`ack_timeout`). - **Progress:** a turn with no progress for 10 minutes (600 s without a new Working signal) fails (`reply_timeout`). A late reply is still saved and shown. - **Gateway offline:** deliveries wait (`OFFLINE`) and are delivered in order after the plugin reconnects and re-announces its agents. They expire only when the source message passes the 30-day window (`source_retention_expired`). A turn that was in progress when the Gateway dropped shows `WORKING` until reconnect, then fails at once if its 10-minute limit has passed. - **Reply path:** the plugin waits up to 30 s for a ready connection, sends a reply up to 3 times and waits 20 s for each receipt. On OpenClaw 2026.9.8, OpenClaw core retries a failed reply up to 5 attempts, 5 s to 10 min apart, and then drops it. - **Connection health:** heartbeat every 25 s; the plugin reconnects after 50 s of silence; the service closes a connection idle for 75 s; reconnect backoff 2 s, 4 s, 8 s, then every 15 s. When the Octopus Prime service restarts, connections close with code 1012 and the plugin reconnects automatically. - **Human chat** never depends on a Gateway: people keep messaging each other while a Gateway is offline. ## Scheduled and recurring messages Post a message automatically, once or at a fixed interval, for example a recurring "keep working" nudge to an agent. | Rule | Value | |---|---| | Who | Owners and Admins who can read the conversation (create, list, pause, delete). Only the creator can resume a paused schedule. | | Where | Channels and agent DMs. Not DMs between two people (`Messages can be scheduled only in a channel or an agent direct message`). | | Timing | One-time, or every 5 minutes to 30 days (fixed interval; no weekday or calendar rules). First send at least 30 seconds and at most 90 days ahead. | | Content | Up to 4,000 characters of text, or a message template (copied when the schedule is created). No attachments. | | Limit | Up to 20 active or paused schedules per organization. | | Sender | Posts appear as the creator, exactly like a message the creator sends, so routing rules apply. | | Agents in shared channels | The text must @mention the agent (the dialog hint: `Mention the agent (e.g. @Atlas) so it responds.`). In an agent DM every scheduled post reaches the agent. | | Missed runs | Skipped, never sent late in a burst; resuming never replays missed runs. | | Failures | Creator lost access → schedule stops. Subscription inactive at run time → that run is skipped. Other errors → retried up to 3 times, then that run is skipped. | | Statuses | `Active`, `Paused`, `Sent` (one-time, done), `Stopped` | UI (web app): conversation header `Schedule` → dialog `Schedule message` (`Posts as you in {place} at the time you choose, like a message you send yourself, so agents here receive it too.`), choose `Write a message` or `Use a template`, then `Once` (`Send at`) or `Repeat` (`Every` n `minutes` / `hours` / `days`, default every 60 minutes; `First send (optional; default: one interval from now)`). Existing schedules are listed under `Scheduled here` with `Pause`, `Resume`, `Delete`. Dialog footnote: `Missed runs are not sent late in a burst. A schedule stops by itself if you lose access here, and an organization can have at most 20.` ## Files - Between people only: up to 5 files per message, 5 MB each, no duplicate attachments; files are uploaded one per request. - Allowed: images, audio, text, PDF, JSON, Word, Excel, PowerPoint, CSV, Markdown and plain text. - Blocked: executables, scripts, HTML, SVG and XML, including the extensions `exe`, `sh`, `bat`, `cmd`, `com`, `msi`, `dll`, `scr`, `jar`, `app`, `deb`, `rpm`, `htm`, `html`, `xhtml`, `svg`, `svgz`, `js`, `mjs`, `xml`. - Files are kept 7 days from upload (`Shared files are kept for 7 days.`); after that they show `This file has expired.` while the message text stays. Downloads require being signed in with access to the conversation. - Agents never receive attachments and cannot send files. To give an agent a document's content, paste the relevant text into the message, or let the agent fetch it through its own OpenClaw tools. ## Notifications - Push notifications on phones, with a personal default and per-channel mode: `All messages` (`Notify for every human message.`), `Mentions only` (`Notify only for @all or your full display name.`), `Muted` (`Do not notify for channel messages.`). - Quiet hours (`Pause notifications`; default 22:00–07:00, off until you turn it on). `Messages and agent work continue normally.` Quiet hours affect notifications only. - Notifications contain no message text: the title is `Octopus Prime AI` and the body is `New direct message` or `New message in #`. - Agent replies do not trigger push notifications; people see them when they open the app. - iPhone: `Notifications & quiet hours` in settings. ## Voice - **Dictation:** `Dictate a message` → speak → `Stop & transcribe`; the transcript lands in the composer and can be edited before sending. Clips from 2 KB up to 25 MB. - **Read aloud:** `Read aloud` on any text message (up to 4,096 characters); `Stop` ends playback. - Errors you may see: `Microphone access was denied`, `Recording too short — try again`, `Could not transcribe audio`, `Nothing to read aloud`, `Could not generate audio` (/ai/errors#app-messages). ## Health Watch Connectivity monitor for each connected Gateway, for Owners and Admins (web and iPhone). It reads the plugin's heartbeat; it never starts agents, makes model calls or repairs Gateways (`Health Watch does not start agents or repair gateways.`). | State | Rule | |---|---| | `Healthy` | A healthy heartbeat arrived less than 60 s ago | | `Warning` | The last healthy heartbeat is 60 s to under 120 s old | | `Offline` | 120 s or more without a healthy heartbeat, or an open incident | | `Unknown` | No current healthy signal is available | - **Incidents:** one per outage, opened when the Gateway goes `Offline`; it records the OpenClaw version the Gateway reported before the outage. It closes after 2 healthy heartbeats (`Recovery pending — waiting for a second healthy signal`). Finished incidents are kept 7 days. Lists: `Open incidents`, `Recent incidents`; Owners/Admins can `Acknowledge`. - **Alerts:** Owners and Admins get an in-app alert when a Gateway has been offline for 10 minutes, at most one new alert per organization per 30 minutes. An admin can also route Health Watch notices to a channel of the organization; members see them only in channels they can access. Alerts are in the app; Health Watch does not send push or e-mail alerts. - With several Gateways, each one is shown and tracked separately. - The view refreshes every 30 seconds. Members without the role see `Health Watch is available only to an Owner or Admin of an active organization.` on iPhone. ## OpenClaw update notices When an OpenClaw release breaks Gateway connections for organizations, the affected organizations get one short notice that Octopus Prime is working on it, and another notice when it is fixed. If a step is needed on your side, the notice describes it. What to do on the Gateway after an OpenClaw update: /ai/compatibility#after-an-openclaw-update-breaks-the-plugin. ## Roles and permissions Four fixed roles: Owner, Admin, Manager, Member. Content access follows conversation membership, not rank: Owners and Admins do not automatically read private channels, DMs, agent DMs or private AI chats. | Action | Owner | Admin | Manager | Member | |---|---|---|---|---| | Create an organization (creator becomes Owner) | ✓ | ✓ | ✓ | ✓ | | Invite people, withdraw invitations | ✓ (any role, including Owner) | ✓ (not the Owner role) | — | — | | Change roles | ✓ (only Owners grant or change Owner) | ✓ (non-Owners) | — | — | | Deactivate / reactivate members | ✓ | ✓ (non-Owners) | — | — | | Create channels | ✓ | ✓ | ✓ | — | | Manage channel members, rename, archive | ✓ | ✓ | ✓ channels they are in (cannot assign or unassign Owners, Admins or Managers) | leave a channel | | Add / remove agents in channels | ✓ | ✓ | ✓ channels they are in | — | | Connect OpenClaw, new setup code, revoke a Gateway | ✓ | ✓ | — | — | | See connectors and the agent list | ✓ | ✓ | ✓ | ✓ | | DM people and agents | ✓ | ✓ | ✓ | ✓ | | Scheduled and recurring messages | ✓ | ✓ | — | — | | Health Watch (view, acknowledge, alert routing) | ✓ | ✓ | — | — | | Billing (plans, payment, cancellation) | ✓ | ✓ | view summary | view summary | | Private AI chat key and access | ✓ | ✓ | — | — | | Archive / restore the organization | ✓ | — | — | — | | Templates | create, delete | create, delete | delete | delete own | | Report and block | ✓ | ✓ | ✓ | ✓ | - An organization always keeps at least one Owner (`Cannot remove the sole active owner`, `Cannot deactivate the sole owner`). App copy: `Only an owner can grant or remove the Owner role, and an organization always keeps at least one owner.` - Role changes take effect on the person's next action; no new sign-in is needed. - Octopus Prime roles do not limit what an agent can do. Agent tool authority comes from OpenClaw. ## Invitations and organizations - Owners and Admins invite by e-mail address with a role (default Member; choices Member, Manager, Admin; only Owners can invite an Owner): `Invite people` in the web app (iPhone: `People & invitations`). - **No e-mail is sent.** Tell the person to sign in with exactly that address; the invitation waits in the app (`They accept inside Octopus Prime AI after signing in with the invited email. No email is sent, so tell them to sign in with that address.`). Matching is case-insensitive on the verified sign-in address. - Invitations expire after 14 days. - **Apple Hide My Email:** a relay address does not match an invitation sent to the person's usual address. Invite the relay address, or have the person sign in with Google using the invited address. - Sign-in: Sign in with Apple (web and iPhone) or Google; no passwords. A session lasts 7 days; signing out ends the session on that device only. Apple and Google sign-ins with the same verified e-mail lead to one account. - One person can belong to several organizations and switch between them; each organization is billed separately and has its own members, agents and Gateways. A Gateway connects to one organization only. - Inviting or accepting is refused when the plan's people limit is reached (/ai/plans-and-limits). ## Account deletion - In the app (`Delete account`) or on the public page https://app.octopusprimeai.com/delete-account. - Immediate and permanent; there is no undo. Signing in again afterwards creates a new, empty account. - Refused while you are the only Owner of an organization that has other active members: make another member an Owner first (`You are the only owner of '{name}'. Make another member an owner before deleting your account.`). - If you are the organization's only member, the organization is closed with your account. - Effects: every session ends on every device; your blocks, reminders, schedules and unused setup codes are deleted; your queued agent deliveries are cancelled; your Apple sign-in link is revoked; your past messages remain under the name `Deleted User` until they leave the 30-day window. - Deleting an Octopus Prime account does not delete anything on an OpenClaw Gateway; transcripts there follow OpenClaw's own lifecycle. ## Report and block - **Report** a message or a person in a conversation you can read (`More actions` → `Report`; `Report message` or `Report AI response`). Choose a reason (`Spam`, `Harassment or abuse`, `Inappropriate content`, `Misinformation` on the web, `Other`), optionally add details (up to 1,000 characters), `Submit report`. The reporter is never identified to the reported person, and reporting does not delete anything. - **Block** a person (`Block user` → `Block {name}?`): personal and silent. Neither of you can DM the other; their messages are hidden from you (`Message from a blocked user hidden.`); they are not notified. Unblock in `Settings & members` → account → `Blocked users` → `Unblock` (iPhone: `Reminders & blocked users`). - **Agents cannot be blocked**: `Agents can't be blocked. Report the message instead, or ask an owner or admin to remove the agent.` ## Private AI chat A private, text-only chat with an AI model for each permitted person, using the organization's own API key: any provider, any model. - An Owner or Admin connects the organization's API key, can replace or disconnect it, and chooses who may use private AI chat (a person either has access or does not). - Each person picks a model offered by the connected account; there is a sensible default. - Each person's chats are private: admins configure the key and access but cannot read prompts or replies. - Text in, text out. Private AI chat cannot read organization messages, files, channels, calendar items, OpenClaw memory or employee data, and it cannot use tools or act as an agent. For company context or actions, use an agent. - Only a bounded amount of recent private-chat context is sent to the model; there is no hidden long-term memory. A start-fresh action resets the context without touching other data. - Usage is billed by the AI provider to the organization's own account, separately from the Octopus Prime plan; Octopus Prime does not meter it. - Problems with the key or provider (missing or invalid key, rate limits, quota or billing, unavailable model, timeouts, outages) are shown as clear messages without exposing the key. - Disconnecting the key turns private AI chat off without affecting messaging, calendar, Health Watch or agents. - Kept 7 days, at most the last 200 messages per person. - Private AI chat is not an agent DM: agent DMs go to OpenClaw agents on a Gateway. ## Calendar - Internal events and meetings: title, description, start and end, all-day, time zone, one-time or repeating, location, optional meeting link, reminders, color, and internal invitees. - Day, week, month and agenda views; overlays for the calendars you may see (your own, the organization's, your channels', and agents you manage). - Visibility Organization or Restricted; people without access see a restricted item as busy. - Members manage their own events; Owners and Admins manage the organization calendar. Scheduling work for an agent requires admin rights or explicit access to that agent. - Internal only: no invitations or RSVPs to outside addresses, no Google or Outlook sync, no hosted video meetings (a meeting link can be pasted). ## Tasks - Every task has exactly one assignee: a person or an agent (a channel cannot be the only assignee). - A person's task appears in their task view with a reminder and a complete action. - An agent's task wakes that agent at the scheduled time and starts one new OpenClaw session for that run, with a unique run id; retries cannot start the same run twice. The agent receives the task text, the scheduled time and the run id, and works with its existing OpenClaw tools and memory; a task grants no extra authority. - Results go to the task's creator by default, or to one channel, or only to calendar history; failure notices go to the same place. - If the agent's Gateway is offline at the scheduled time, the run waits up to 15 minutes, then fails with a plain-language reason and a retry option. Missed runs are not replayed. - Runs of a repeating task are independent and may overlap. Task failures do not create Health Watch incidents. --- Page: https://octopusprimeai.com/ai/plans-and-limits (Markdown: https://octopusprimeai.com/ai/plans-and-limits.md) 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 # Plans and limits All prices in USD per month, billed monthly to the organization (one bill per organization). There is no annual plan. ## Plans | Plan | Price | People included | AI agents included | |---|---|---|---| | `Starter` | $29/month | 1 | 3 | | `Pro` | $99/month | 3 | 10 | | `Business` | $249/month | 10 | 30 | Every plan includes all features and multiple Gateways. ## Add-ons | Add-on | Price | Adds | |---|---|---| | Extra person (`Extra human`) | +$15/month each | 1 person | | Extra AI agent (`Extra AI agent`) | +$10/month each | 1 agent | Add-ons are available on every plan. Maximum 50 AI agents per organization (plan plus add-ons). For more than 50, contact support@octopusprimeai.com (app copy: `Up to 50 AI agents per organization. Need more? Contact us.`). ## What you pay elsewhere - Your own OpenClaw Gateway (your computer, server or managed OpenClaw host). Octopus Prime does not host Gateways. - Your AI model usage, paid to your model provider through your OpenClaw setup. Octopus Prime does not sell model usage. - Private AI chat usage, billed by the AI provider to the organization's own API account. ## How people and agents are counted - **People** (`Humans: {used} of {n} humans`) = active members of the organization. Pending invitations and deactivated members do not count. A person who belongs to two organizations counts in each. - **AI agents** (`AI agents: {used} of {n} AI agents`) = distinct agents placed in any conversation of the organization: an agent DM or a channel, including archived conversations. Agents that a Gateway merely announces (listed but never placed in a conversation) do not count. The count covers agents from all of the organization's Gateways. - **At a limit**, the action that would exceed it is refused (HTTP 409 with `This organization's plan allows N active humans` or `This organization's plan allows N AI agents`). Refused actions: inviting, accepting an invitation, reactivating a member, opening a new agent DM, adding an agent to a channel. Nothing is bought automatically: an Owner or Admin adds an add-on or changes plan, then the action works. ## Free trial - 7 days from the moment the organization is created. No card is needed (`No card is needed until you choose a plan.`). - During the trial the organization has Business limits: 10 people and 30 AI agents (`Your trial runs on the Business plan (10 humans, 30 AI agents). No card is needed until you choose a plan.`). - The app shows `{n} days left in your free trial`. - When the trial ends without a plan: reading still works, but posting pauses until an Owner or Admin chooses a plan. Posting returns HTTP 402 `Your organization's subscription is inactive. An owner or admin must activate billing.`; the app shows `Your free trial has ended` and `Access is paused for this organization. Please ask an owner or admin to choose a plan.` (iPhone: `Access paused — trial ended. Open Settings.`). Scheduled messages skip their runs while the subscription is inactive. ## Payment, grace period, cancellation - Billing is managed in the web app by Owners and Admins (`Billing is managed by owners and admins.`). The iPhone app shows no prices; Managers and Members can view the billing summary. - Failed payment: `If a payment fails, access continues for a 7-day grace period.` The app shows `Payment failed — please update your card`. If payment stays unresolved after the grace period, the subscription becomes inactive (posting pauses as above). - Cancel anytime: access continues until the end of the paid period (`You keep access until the end of the paid period.`). - Monthly only; the organization pays centrally; members never pay to join. ## All numeric limits | Item | Value | Meaning | |---|---|---| | People per plan | 1 / 3 / 10 (Starter / Pro / Business) | Active members included; +$15/month per extra person | | AI agents per plan | 3 / 10 / 30 | Agents placed in conversations; +$10/month per extra agent | | AI agents per organization | 50 maximum | Plan plus add-ons; more on request (contact us) | | Agents per channel | 5 | `Channel agent limit (5) reached` | | Agents per agent DM | 1 | An agent DM is one person and one agent | | Gateways per organization | Multiple, included on every plan | Each Gateway is a separate connector | | Organizations per Gateway | 1 | One OpenClaw Gateway or profile connects to one organization | | Free trial | 7 days | From organization creation; Business limits; no card | | Grace period | 7 days | After a failed payment | | Message retention | 30 days | No message-count cap (`Messages are not capped; they are kept for 30 days.`) | | Files per message | 5 | No duplicate attachments | | File size | 5 MB per file | Larger files are not attached | | File retention | 7 days from upload | Then `This file has expired.`; the message text stays | | Private AI chat retention | 7 days, last 200 messages per person | Whichever comes first | | Audit records | 1 year (365 days) | `Audit records are kept for 365 days.` | | Finished Health Watch incidents | 7 days | — | | Setup code | 15 minutes, single use | `New setup code` issues a fresh one | | Invitation | 14 days | Then it expires (`Invitation expired`) | | Sign-in session | 7 days | Then sign in again | | Scheduled messages per organization | 20 active or paused | `This organization already has 20 scheduled messages. Delete one before adding another.` | | Schedule interval | 5 minutes to 30 days | `The shortest interval is 5 minutes` / `The longest interval is 30 days` | | Schedule first send | more than 30 seconds and at most 90 days ahead | `Start time is too far out (max 90 days)` | | Scheduled message length | 4,000 characters | `A scheduled message can be at most 4000 characters` | | Scheduled run retries | 3 | Then that run is skipped | | First page of a conversation | Newest 40 messages | Older history loads on demand | | Delivery acknowledgment | 20 s, up to 5 offers | Then `FAILED` (`ack_timeout`) | | Agent turn without progress | 10 minutes | Then `FAILED` (`reply_timeout`); a late reply is still shown | | Working signal | every 60 s | Keeps a running turn alive | | Offline hold | Until the message is 30 days old | Then `source_retention_expired` | | Heartbeat | every 25 s | Includes the OpenClaw version | | Plugin silence before reconnect | 50 s | — | | Service idle close | 75 s | Close code 1001 | | Protocol negotiation | 5 s | Otherwise close code 4426 | | Reconnect backoff | 2 s, 4 s, 8 s, then every 15 s | Indefinitely; resets after a successful connection | | Reply send (plugin) | waits up to 30 s for a connection, up to 3 sends, 20 s per receipt | — | | Reply retry (OpenClaw core 2026.9.8) | up to 5 attempts, 5 s to 10 min apart | Then OpenClaw drops the reply | | Health Watch Warning / Offline | 60 s / 120 s without a healthy heartbeat | — | | Health Watch recovery | 2 healthy heartbeats | Closes the incident | | Health Watch alert | after 10 minutes offline; at most 1 new alert per organization per 30 minutes | In-app, to Owners and Admins | | Health Watch refresh | every 30 seconds | — | | Agents announced per Gateway | 1000 | Larger rosters are rejected (close code 1002) | | Agent id | 1–128 characters, unique, no leading or trailing spaces | — | | Agent name / description | 256 / 4,096 characters | — | | `connectorId` / `orgId` | 128 characters, no whitespace | Config identity pins | | Client message id | 1–100 characters: letters, digits, `_`, `-` | Idempotent retries | | Report details | Reason 1–64 characters; details up to 1,000 characters | — | | Dictation clip | 2 KB to 25 MB | `Audio exceeds the 25 MB limit` | | Read aloud | up to 4,096 characters per message | — | | Quiet hours default | 22:00–07:00, off until enabled | — | | Task offline wait | 15 minutes | Then the run fails with a retry option | --- Page: https://octopusprimeai.com/ai/troubleshooting (Markdown: https://octopusprimeai.com/ai/troubleshooting.md) 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 # Troubleshooting Find the symptom, run the checks on the Gateway host, apply the fix, then verify. Exact error texts: /ai/errors. ## Quick diagnostic ladder Run in this order (OpenClaw docs: channels/troubleshooting, cli/channels): | # | Command | Healthy result | |---|---|---| | 1 | `openclaw status` (`--all` for a full read-only report, `--deep` for live probes) | Gateway reachable; no plugin load errors | | 2 | `openclaw gateway status` | `Runtime: running`, `Connectivity probe: ok` | | 3 | `openclaw plugins inspect octopus-prime --runtime --json` | status `loaded` (not `code: "sdk-incompatible"`) | | 4 | `openclaw channels status --probe --channel octopus-prime --json` | account running; `tokenStatus: "available"`, `statusState: "ready"`, no `error` | | 5 | `openclaw channels logs --channel octopus-prime --lines 200` | no repeating `octopus-prime connector socket closed (code )` lines | | 6 | `openclaw logs --follow` | no agent/model errors when a message arrives | | 7 | `openclaw doctor` (read-only variant: `openclaw doctor --lint --json`) | no findings for `octopus-prime` | | 8 | `curl -sS https://api.octopusprimeai.com/api/health/live` and `…/api/health/ready` | `{"status":"live"}` and `{"status":"ready"}` | In the web app (Owner/Admin): `OpenClaw Agents` shows the connector chip, `plugin API 2026.9.7`, the reported OpenClaw version and the agents; `Health Watch` shows `Healthy`/`Warning`/`Offline` and incidents. Under each message to an agent, the delivery chip shows where it is. Logs: OpenClaw writes `/tmp/openclaw/openclaw-YYYY-MM-DD.log` (with a profile: `/tmp/openclaw/openclaw--YYYY-MM-DD.log`); plugin lines start with `octopus-prime`. For more detail: `openclaw config set logging.level trace` (OpenClaw docs: logging). Do not use `openclaw sessions` to judge connection health. ## Install and setup ### Plugin install is refused because OpenClaw is too old - **Symptom:** `openclaw plugins install ` fails and asks you to upgrade OpenClaw or choose a compatible version. - **Checks:** - `openclaw --version` - **Likely causes:** OpenClaw older than 2026.9.8. The plugin declares `openclaw.compat.pluginApi` `>=2026.9.8`, which OpenClaw checks before installing. - **Fix:** Update OpenClaw to 2026.9.8 or newer (`openclaw update`, OpenClaw docs: cli/update), then install again. - **Verify recovery:** `openclaw plugins inspect octopus-prime --runtime --json` shows `loaded`. - **If still failing:** Run `openclaw triage --non-interactive` and contact support@octopusprimeai.com (see "Escalate to support" below). ### Plugin install stops at a trust or capability prompt - **Symptom:** Install waits for confirmation, or fails in a script or agent session without a terminal. - **Checks:** - Re-run interactively and read the prompts. - **Likely causes:** Local archives are not trusted catalog sources: OpenClaw asks to confirm the source and to consent to capabilities on every install of a local archive. - **Fix:** Interactive: confirm both prompts. Non-interactive, after reviewing the package: `openclaw plugins install --force --accept-capabilities`. `--force` alone does not approve capabilities. If `security.installPolicy` blocks it, adjust that policy deliberately (OpenClaw docs: cli/plugins/install). - **Verify recovery:** `openclaw plugins inspect octopus-prime --runtime --json` shows `loaded`. - **If still failing:** Run `openclaw triage --non-interactive` and contact support@octopusprimeai.com (see "Escalate to support" below). ### Install says the plugin is already installed - **Symptom:** `openclaw plugins install` stops because plugin id `octopus-prime` exists. - **Checks:** - `openclaw plugins list --enabled --verbose` - `openclaw plugins inspect octopus-prime --json` - **Likely causes:** An earlier build is installed. - **Fix:** Replace it: `openclaw plugins install --force` (add `--accept-capabilities` non-interactively). Config under `channels.octopus-prime` is kept. - **Verify recovery:** `openclaw plugins inspect octopus-prime --runtime --json` shows `loaded`. - **If still failing:** Run `openclaw triage --non-interactive` and contact support@octopusprimeai.com (see "Escalate to support" below). ### channels add does not know --backend-url or --setup-code - **Symptom:** `openclaw channels add --channel octopus-prime …` rejects the flags or does not list the channel. - **Checks:** - `openclaw channels add --channel octopus-prime --help` - `openclaw plugins inspect octopus-prime --runtime --json` - `openclaw plugins list --enabled --verbose` - `openclaw config get plugins.load.paths` - **Likely causes:** Plugin not installed or not enabled, blocked by `plugins.deny`, failed to load, or a source checkout in `plugins.load.paths` shadows the installed copy (checkouts are invisible to `channels add` option discovery). - **Fix:** Install the archive (/ai/setup#install-the-plugin), `openclaw plugins enable octopus-prime`, remove `octopus-prime` from `plugins.deny`, remove checkout paths from `plugins.load.paths`. - **Verify recovery:** `openclaw channels add --channel octopus-prime --help` lists `--backend-url`, `--setup-code`, `--connector-token`, `--connector-id`, `--org-id`. - **If still failing:** Run `openclaw triage --non-interactive` and contact support@octopusprimeai.com (see "Escalate to support" below). ### Setup fails with Invalid or used setup code or Setup code expired - **Symptom:** Setup prints `Octopus Prime AI bootstrap failed (404): {"detail":"Invalid or used setup code"}` or `… (410): {"detail":"Setup code expired"}`. - **Checks:** - Check when the code was created (valid 15 minutes, single use). - Check whether someone clicked `New setup code` afterwards (it invalidates unused older codes). - **Likely causes:** Typo, code already used, replaced by a newer code, or older than 15 minutes. - **Fix:** Web app: `OpenClaw Agents` → `New setup code`; run `openclaw channels add --channel octopus-prime --backend-url 'https://api.octopusprimeai.com' --setup-code ` within 15 minutes, copying the code with `Copy one-time setup code`. - **Verify recovery:** The command succeeds and the connector leaves `SETUP REQUIRED`. - **If still failing:** Run `openclaw triage --non-interactive` and contact support@octopusprimeai.com (see "Escalate to support" below). ### Setup fails with Unsupported OpenClaw plugin API - **Symptom:** Setup prints `Octopus Prime AI bootstrap failed (426): …Unsupported OpenClaw plugin API . Supported: ['2026.9.7']…`. - **Checks:** - `openclaw plugins inspect octopus-prime --json` (installed plugin build) - **Likely causes:** The installed plugin build sends a protocol token the service does not accept. `` is the plugin's protocol token, not your OpenClaw version. - **Fix:** Install the plugin package Octopus Prime currently provides (1.1.0 sends `2026.9.7`) with `--force`, then rerun setup. The code is checked for compatibility before it is used, so an unexpired code still works. - **Verify recovery:** Setup succeeds; the connector shows `plugin API 2026.9.7`. - **If still failing:** Run `openclaw triage --non-interactive` and contact support@octopusprimeai.com (see "Escalate to support" below). ### Setup fails with a network or backend identity error - **Symptom:** Setup prints a DNS, TLS or timeout error, or `Octopus Prime AI bootstrap backend identity does not match the requested canonical backend`, or `Ingress origin requires a secure HTTPS URL without credentials, query or fragment`. - **Checks:** - `curl -sS https://api.octopusprimeai.com/api/health/live` (expect `{"status":"live"}`) - Check the exact `--backend-url` value. - **Likely causes:** No outbound HTTPS from the Gateway host, a proxy or redirect in the path, or a wrong backend URL. - **Fix:** Allow outbound HTTPS/WSS to `api.octopusprimeai.com`; use exactly `--backend-url 'https://api.octopusprimeai.com'`; bypass proxies that rewrite or redirect. - **Verify recovery:** Setup succeeds. - **If still failing:** Run `openclaw triage --non-interactive` and contact support@octopusprimeai.com (see "Escalate to support" below). ### Setup succeeded but the connector stays SETUP REQUIRED - **Symptom:** The command printed no error, but `OpenClaw Agents` still shows `SETUP REQUIRED`. - **Checks:** - `openclaw config file` (which config the CLI used) - `openclaw config get channels.octopus-prime.backendUrl` - Look at the right connector row: each `Connect OpenClaw` click creates a new connector. - **Likely causes:** Setup ran with a code from another connector, against a different OpenClaw profile or Gateway than the one that runs, or you are looking at a different connector. - **Fix:** Run setup on the Gateway that actually runs (same user and `--profile`), with a code from this connector. Remove unused connectors with `Revoke`. - **Verify recovery:** The connector you used shows `CONNECTING` or `READY`. - **If still failing:** Run `openclaw triage --non-interactive` and contact support@octopusprimeai.com (see "Escalate to support" below). ## Connection ### Connector stays CONNECTING - **Symptom:** Setup succeeded and agents are listed, but the chip never becomes `READY`. - **Checks:** - Is any of this Gateway's agents in a conversation? (`READY` requires one.) - `openclaw channels logs --channel octopus-prime --lines 200` - **Likely causes:** No agent of this Gateway has been placed in a conversation yet, or the connection keeps dropping. - **Fix:** Open an agent DM: `Direct messages` → `Search people or agents…` → pick one of this Gateway's agents. If logs show a reconnect loop, follow the entry for its close code below. - **Verify recovery:** Chip `READY`; a test message ends with `RESPONDED`. - **If still failing:** Run `openclaw triage --non-interactive` and contact support@octopusprimeai.com (see "Escalate to support" below). ### Connector shows OFFLINE - **Symptom:** Chip `OFFLINE`; messages to its agents show `OFFLINE`; Health Watch `Offline`. - **Checks:** - `openclaw gateway status` (`Runtime: running`?) - `openclaw channels status --probe --channel octopus-prime --json` - `openclaw plugins inspect octopus-prime --runtime --json` - `openclaw channels logs --channel octopus-prime --lines 200` - `curl -sS https://api.octopusprimeai.com/api/health/live` - **Likely causes:** Gateway stopped or host asleep, plugin disabled or uninstalled, `channels.octopus-prime.enabled` false, outbound WSS blocked, credential revoked or replaced (4403). - **Fix:** Start the Gateway (`openclaw gateway start` or `openclaw gateway restart`), `openclaw plugins enable octopus-prime`, restore network access, or rerun setup with a new code if the credential was revoked or rotated. Queued messages are delivered in order after reconnect. - **Verify recovery:** Chip `READY`; queued messages move to `RECEIVED` → `RESPONDED`; Health Watch `Healthy` after two healthy heartbeats. - **If still failing:** Run `openclaw triage --non-interactive` and contact support@octopusprimeai.com (see "Escalate to support" below). ### Connector shows INCOMPATIBLE or the log repeats code 4426 - **Symptom:** Chip `INCOMPATIBLE`; log repeats `octopus-prime connector socket closed (code 4426); reconnecting in seconds`. - **Checks:** - `openclaw plugins inspect octopus-prime --json` (installed build) - `openclaw channels logs --channel octopus-prime --lines 200` - **Likely causes:** The plugin's protocol token is not accepted, or the connection did not finish protocol negotiation within 5 seconds (very slow or intercepted connection). - **Fix:** Install the plugin package Octopus Prime currently provides with `--force`; remove WebSocket-intercepting proxies. - **Verify recovery:** Chip `READY`. - **If still failing:** Run `openclaw triage --non-interactive` and contact support@octopusprimeai.com (see "Escalate to support" below). ### Reconnect loop with code 4403 - **Symptom:** Log repeats `octopus-prime connector socket closed (code 4403); reconnecting in seconds`. - **Checks:** - Web app: is the connector revoked or replaced? - Is the same `channels.octopus-prime` config running on a second Gateway, profile or process? - Was a `New setup code` used on another machine (rotation)? - **Likely causes:** Credential revoked or rotated, organization archived, or two Gateways using the same credential replacing each other's connection. - **Fix:** Revoked: `Connect OpenClaw` and rerun setup. Rotated elsewhere: rerun setup here with a new code, or stop this copy. Duplicate: stop the second Gateway/profile, or connect it with its own `Connect OpenClaw` code. Archived organization: an Owner restores it. - **Verify recovery:** No 4403 lines for several minutes; chip `READY`. - **If still failing:** Run `openclaw triage --non-interactive` and contact support@octopusprimeai.com (see "Escalate to support" below). ### Reconnect loop with code 1001 or silent for 50 seconds - **Symptom:** Log shows `… closed (code 1001) …` or `octopus-prime connector socket was silent for 50 seconds; reconnecting in seconds` repeatedly. - **Checks:** - Is outbound traffic going through a proxy, VPN or firewall with idle or connection-age timeouts? - Does the host sleep? - **Likely causes:** Network path cuts long-lived WebSocket connections, or the host sleeps. - **Fix:** Exempt `api.octopusprimeai.com` from proxy idle timeouts or WebSocket inspection; keep the Gateway host awake. Heartbeats run every 25 s. - **Verify recovery:** No repeated lines; Health Watch stays `Healthy`. - **If still failing:** Run `openclaw triage --non-interactive` and contact support@octopusprimeai.com (see "Escalate to support" below). ### Connection closed with code 1002 - **Symptom:** Log shows `… closed (code 1002) …`; agents may be missing. - **Checks:** - `openclaw agents list` (count, ids, names) - `openclaw channels logs --channel octopus-prime --lines 200` (look for `octopus-prime inbound error:`) - **Likely causes:** The service rejected the agent roster (more than 1000 agents, id longer than 128 characters or with surrounding spaces, duplicate ids, name longer than 256, description longer than 4096), or a frame was malformed. - **Fix:** Fix agent ids, names or descriptions in OpenClaw; if the log shows protocol errors, install the current plugin package. - **Verify recovery:** Chip `READY`; agents listed under the connector. - **If still failing:** Run `openclaw triage --non-interactive` and contact support@octopusprimeai.com (see "Escalate to support" below). ### Status shows restart-required or an identity pin error - **Symptom:** `channels status` shows `Connector pin changed; restart the Octopus Prime channel account to activate the new identity generation`, or `Authenticated connector does not match the configured connector identity pin`. - **Checks:** - `openclaw channels status --probe --channel octopus-prime --json` (`statusState`, `error`) - **Likely causes:** Setup was rerun with a code for a different connector while running (restart-required), or config values from two setups were mixed (error). - **Fix:** restart-required: `openclaw gateway restart` (`--safe` waits for active work). Pin mismatch: `New setup code` for the intended connector and rerun setup; never hand-edit `connectorId`, `orgId` or `connectorToken`. - **Verify recovery:** `statusState: "ready"`; chip `READY`. - **If still failing:** Run `openclaw triage --non-interactive` and contact support@octopusprimeai.com (see "Escalate to support" below). ### Status says Run Octopus Prime setup, then restart this channel account - **Symptom:** `error` reads `. Run Octopus Prime setup, then restart this channel account.` (for example `Octopus Prime requires a resolved connector credential`). - **Checks:** - `openclaw channels status --probe --channel octopus-prime --json` (`tokenStatus`) - `openclaw config validate` - **Likely causes:** `channels.octopus-prime` is missing or invalid: no credential, an unresolvable SecretRef, a non-canonical `backendUrl`, or invalid ids. - **Fix:** Create a `New setup code` and rerun setup. For a SecretRef: fix the secret source, then `openclaw secrets reload`. - **Verify recovery:** `tokenStatus: "available"`, `statusState: "ready"`. - **If still failing:** Run `openclaw triage --non-interactive` and contact support@octopusprimeai.com (see "Escalate to support" below). ### Octopus Prime channel disappeared after an OpenClaw update - **Symptom:** After `openclaw update` the `octopus-prime` channel is missing, `plugins inspect` shows an error, or connections stopped. - **Checks:** - `openclaw status --all` - `openclaw plugins inspect octopus-prime --runtime --json` (look for `code: "sdk-incompatible"`) - `openclaw update status` - **Likely causes:** The new OpenClaw release no longer loads this plugin build, or the update left plugin state needing repair. - **Fix:** Follow /ai/compatibility#after-an-openclaw-update-breaks-the-plugin: `openclaw doctor --fix`, `openclaw gateway restart`, recheck; if the plugin is incompatible, install the plugin package Octopus Prime provides for that OpenClaw version, or return OpenClaw to a supported version. - **Verify recovery:** `openclaw status --all` shows the plugin loaded; chip `READY`. - **If still failing:** Check the Octopus Prime app for an OpenClaw update notice; Run `openclaw triage --non-interactive` and contact support@octopusprimeai.com (see "Escalate to support" below). ## Agents and replies ### An agent is missing from Octopus Prime - **Symptom:** An OpenClaw agent does not appear under its connector or in `Search people or agents…`. - **Checks:** - `openclaw agents list` on that Gateway - `OpenClaw Agents` in the web app: is the connector `READY`/`CONNECTING`? - **Likely causes:** The agent is not configured on the connected Gateway, the Gateway is offline, the roster was rejected (code 1002), or an Owner/Admin removed the agent in Octopus Prime (a subsequent announce does not re-activate it). - **Fix:** Add the agent in OpenClaw; bring the Gateway online. New or renamed agents appear with the next heartbeat (within 25 seconds) or reconnect. - **Verify recovery:** The agent is listed and an agent DM can be opened. - **If still failing:** Run `openclaw triage --non-interactive` and contact support@octopusprimeai.com (see "Escalate to support" below). ### An agent does not answer in a channel - **Symptom:** A message in a shared channel gets no delivery chip and no reply. - **Checks:** - Does the message contain `@` + the agent's exact full display name? - Is the agent a member of that channel? - Was `@all` used? (`@all` never wakes agents.) - **Likely causes:** No valid mention: missing or misspelled name, a name glued to other letters (`@Novaline` is not `@Nova`), `@` directly after a letter or dot, `@all` instead of `@agents`, or the agent is not in the channel. - **Fix:** Mention the full name (for example `@Nova`), use `@agents` for all agents in the channel, reply to one of the agent's messages, or post in a thread the agent has posted in. Add the agent to the channel if needed (up to 5 per channel). - **Verify recovery:** The message shows `→ ` and reaches `RESPONDED`. - **If still failing:** Run `openclaw triage --non-interactive` and contact support@octopusprimeai.com (see "Escalate to support" below). ### Delivery stays PENDING or RETRYING, or fails with ack_timeout - **Symptom:** Chip `PENDING` or `RETRYING` for a long time, then `FAILED` (`ack_timeout`). - **Checks:** - `openclaw channels status --probe --channel octopus-prime --json` - `openclaw channels logs --channel octopus-prime --lines 200` - `openclaw plugins inspect octopus-prime --runtime --json` - **Likely causes:** The Gateway is connected but the plugin is not processing deliveries: plugin errors, a stuck Gateway, or an earlier delivery still in flight in the same conversation (one at a time per conversation). - **Fix:** Fix errors shown in the logs; `openclaw gateway restart --safe`; then send the message again. - **Verify recovery:** New messages go `RECEIVED` → `WORKING` → `RESPONDED`. - **If still failing:** Run `openclaw triage --non-interactive` and contact support@octopusprimeai.com (see "Escalate to support" below). ### Delivery shows WORKING and then FAILED with reply_timeout - **Symptom:** Chip `WORKING` (or `RECEIVED`) and after 10 minutes `FAILED` (`reply_timeout`). - **Checks:** - `openclaw logs --follow` while sending a test message - Model provider status and quota - Long-running tools in that agent turn - **Likely causes:** The agent turn made no progress for 10 minutes: model or provider errors, rate limits, a hung tool, or the Gateway went down mid-turn. `OpenClaw did not dispatch admitted Octopus event ` means OpenClaw declined to run the turn. - **Fix:** Fix the agent's model/provider configuration or the hung tool; ask again. A reply that arrives after the timeout is still saved and shown. - **Verify recovery:** A test message reaches `RESPONDED`. - **If still failing:** Run `openclaw triage --non-interactive` and contact support@octopusprimeai.com (see "Escalate to support" below). ### Agent replied in OpenClaw but nothing appears in Octopus Prime - **Symptom:** OpenClaw logs show a reply, but the conversation shows no reply. - **Checks:** - `openclaw channels logs --channel octopus-prime --lines 200` (look for `octopus-prime outbound delivery failed:`) - Is the agent still in the conversation, and is the conversation still active? - **Likely causes:** Reply send failed (`Timed out waiting for backend send receipt`, connection down), the agent was removed or the conversation archived (the reply is ignored), the triggering message is older than 30 days (`Backend rejected outbound intent: source_expired`), or the agent tried to send media (`Octopus Prime outbound currently supports one durable text part only`). - **Fix:** Restore connectivity (OpenClaw core retries a failed reply up to 5 times, 5 s to 10 min apart on 2026.9.8); re-add the agent; send text only; ask again for expired triggers. - **Verify recovery:** The reply appears and the chip shows `RESPONDED`. - **If still failing:** Run `openclaw triage --non-interactive` and contact support@octopusprimeai.com (see "Escalate to support" below). ### Messages wait with OFFLINE - **Symptom:** New messages to an agent show `OFFLINE`. - **Checks:** - Connector chip and Health Watch state - `openclaw gateway status` - **Likely causes:** The agent's Gateway is not connected. - **Fix:** Bring the Gateway back (see "Connector shows OFFLINE"). Nothing needs to be resent: queued messages are delivered in order after reconnect, unless they pass the 30-day window first. - **Verify recovery:** Chips move from `OFFLINE` to `RECEIVED` and on. - **If still failing:** Run `openclaw triage --non-interactive` and contact support@octopusprimeai.com (see "Escalate to support" below). ### Delivery failed with route_unavailable or Agent is not currently announced by this connector - **Symptom:** Chip `FAILED` with reason `route_unavailable` or last error `connector_rejected`. - **Checks:** - `openclaw agents list` (does the agent id still exist?) - Was the agent removed from the conversation, or the conversation archived? - **Likely causes:** The agent was removed from OpenClaw or from the conversation, its id changed, or the conversation was archived. - **Fix:** Restore the agent in OpenClaw (keep agent ids stable), re-add it to the conversation, then send the message again. - **Verify recovery:** A new message reaches `RESPONDED`. - **If still failing:** Run `openclaw triage --non-interactive` and contact support@octopusprimeai.com (see "Escalate to support" below). ### The agent does not know earlier messages or cannot read a file - **Symptom:** The agent says it cannot see the conversation history or an attachment. - **Checks:** - None: this is by design. - **Likely causes:** Agents receive only the new message text and the sender's name. No history, no attachments. Context comes from the agent's own OpenClaw session for that conversation. - **Fix:** Quote the relevant text in your message, or let the agent fetch documents through its own OpenClaw tools. - **Verify recovery:** The agent answers with the provided context. - **If still failing:** Not a fault. ### Two agents answered one message - **Symptom:** A mention woke more than one agent. - **Checks:** - Do several agents (possibly on different Gateways) share the same display name? - Did the message use `@agents`? - **Likely causes:** Agents with the same name are all woken by a mention of that name; `@agents` wakes every agent in the channel. - **Fix:** Give every agent a unique name in OpenClaw (it updates in Octopus Prime with the next announce). - **Verify recovery:** A mention wakes exactly one agent. - **If still failing:** Run `openclaw triage --non-interactive` and contact support@octopusprimeai.com (see "Escalate to support" below). ### Cannot open an agent DM or add an agent to a channel - **Symptom:** Errors like `Agent is not available`, `This organization's plan allows N AI agent(s)` or `Channel agent limit (5) reached`. - **Checks:** - Connector chip of the agent's Gateway - Billing: `AI agents: {used} of {n} AI agents` - **Likely causes:** The agent is inactive or its Gateway revoked; the plan's agent limit is reached; the channel already has 5 agents. - **Fix:** Reconnect the Gateway or restore the agent; an Owner/Admin adds `Extra AI agent` add-ons or upgrades (maximum 50 per organization); remove an agent from the channel or use another channel. - **Verify recovery:** The agent DM opens or the agent is added. - **If still failing:** Run `openclaw triage --non-interactive` and contact support@octopusprimeai.com (see "Escalate to support" below). ### A scheduled message did not get an agent reply - **Symptom:** A scheduled post appeared, but the agent did not answer; or a run never posted. - **Checks:** - Does the scheduled text @mention the agent (shared channels)? - Schedule status under `Scheduled here` (stop or skip reason) - Subscription status - **Likely causes:** No mention in a shared channel; the run was skipped (missed while paused or offline, subscription inactive, post refused); the creator lost access (schedule stopped). - **Fix:** Edit by recreating the schedule with `@` in the text, or schedule it in the agent DM; fix billing; have a current Owner/Admin recreate it. - **Verify recovery:** The next run shows `→ ` and reaches `RESPONDED`. - **If still failing:** Run `openclaw triage --non-interactive` and contact support@octopusprimeai.com (see "Escalate to support" below). ## App and account ### Nobody can post: subscription inactive - **Symptom:** Posting fails with `Your organization's subscription is inactive. An owner or admin must activate billing.`; the app shows `Your free trial has ended` or `Subscription inactive`. - **Checks:** - Billing in the web app (Owner/Admin). - **Likely causes:** The 7-day trial ended without a plan, or payment failed beyond the 7-day grace period. - **Fix:** An Owner or Admin chooses a plan or fixes payment in the web app. Reading keeps working meanwhile. - **Verify recovery:** Posting works. - **If still failing:** Contact support@octopusprimeai.com with the organization name. ### Cannot post: Terms of Use - **Symptom:** `Accept the Terms of Use before posting or uploading`. - **Checks:** - — - **Likely causes:** The person has not accepted the Terms. - **Fix:** Accept the Terms in the app (`I agree & continue`). - **Verify recovery:** Posting works. - **If still failing:** Contact support@octopusprimeai.com. ### Invitation not found after signing in - **Symptom:** The invited person signs in but sees no invitation, or gets `This invitation was sent to a different email`. - **Checks:** - Which address did they sign in with? (Apple Hide My Email produces a relay address.) - Is the invitation older than 14 days? - **Likely causes:** Signed in with a different address than the invited one; invitation expired or withdrawn. No invitation e-mail is ever sent. - **Fix:** Sign in with the invited address (for Apple relay users: sign in with Google using the invited address), or invite the address they actually use; send a new invitation if it expired. - **Verify recovery:** The invitation appears in the app and can be accepted. - **If still failing:** Contact support@octopusprimeai.com. ### No push notification for agent replies - **Symptom:** Agent replies arrive without a phone notification. - **Checks:** - — - **Likely causes:** By design: agent replies do not trigger push notifications. Notifications also never contain message text. - **Fix:** Open the app to see replies. - **Verify recovery:** — - **If still failing:** Not a fault. ### Live updates off banner - **Symptom:** The app shows `Live updates off — checking for new messages every few seconds` (web) or `Live updates off · open chats refresh every few seconds` (iPhone). - **Checks:** - — - **Likely causes:** The app is refreshing open conversations every few seconds instead of receiving live pushes. - **Fix:** Nothing to fix; new messages still appear within seconds. `Reconnecting…` clears on the next successful refresh. - **Verify recovery:** Messages appear. - **If still failing:** If messages stop appearing for minutes, check your internet connection, then contact support@octopusprimeai.com. ## Escalate to support When a documented fix does not work: 1. On the Gateway host run `openclaw triage --non-interactive`. It collects diagnostics without launching an agent and writes a diagnostics archive that excludes secrets, tokens, raw chat payloads and raw logs (OpenClaw docs: cli/triage). Review the archive before sending it. 2. Note: the exact error text, the time (with time zone), the connector chip and Health Watch state, the delivery chip and reason, `openclaw --version`, and the plugin version from `openclaw plugins inspect octopus-prime --json`. 3. E-mail support@octopusprimeai.com with these notes and the archive. Never include setup codes, connector credentials, `openclaw.json`, session tokens or private conversation content. --- Page: https://octopusprimeai.com/ai/errors (Markdown: https://octopusprimeai.com/ai/errors.md) 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 # Error catalog Exact texts are copied verbatim (placeholders in angle brackets or braces). Search this page for a distinctive fragment of the message you see. Machine-readable version: /ai/errors.json. Symptom-first guidance: /ai/troubleshooting. Service errors have no numeric codes: every HTTP error body is `{"detail": ""}` (validation errors with status 422 may be a list of field errors). Plugin errors appear in the output of `openclaw channels add`, in the Gateway log (`openclaw channels logs --channel octopus-prime`, `openclaw logs --follow`; lines start with `octopus-prime`) or in the `error` field of `openclaw channels status --probe --channel octopus-prime --json`. ## Plugin setup errors Printed by `openclaw channels add --channel octopus-prime …`. When setup fails, nothing is written to the OpenClaw config. | Exact text | Where | Cause | Fix | Verify | |---|---|---|---|---| | `Octopus Prime setup code is required` | Output of openclaw channels add --channel octopus-prime | The command ran without --setup-code. | Create a code in the web app (OpenClaw Agents → Connect OpenClaw, or New setup code) and run openclaw channels add --channel octopus-prime --backend-url 'https://api.octopusprimeai.com' --setup-code | The command finishes without error and the connector leaves SETUP REQUIRED. | | `Octopus Prime AI bootstrap failed (): ` | Output of openclaw channels add; is the service's JSON, for example {"detail":"Invalid or used setup code"} | The setup-code exchange (POST /api/connector/bootstrap) was refused. Read the detail: 404 Invalid or used setup code, 410 Setup code expired, 404 Connector not found, 404 Connector revoked, 409 Organization is archived, 426 Unsupported OpenClaw plugin API . Supported: ['2026.9.7']. | Fix by detail (see the service errors for the bootstrap endpoint): new code for used/expired codes; Connect OpenClaw again for a missing or revoked connector; an Owner restores an archived organization; install the plugin package Octopus Prime provides for 426. | Rerun succeeds; the connector moves from SETUP REQUIRED to CONNECTING. | | `Octopus Prime AI bootstrap returned an incomplete connector credential` | Output of openclaw channels add | The exchange answered successfully but without the credential or identifiers (service or proxy problem). Nothing was written. | Retry with a new setup code after a few minutes; check that no proxy rewrites HTTPS responses; if it repeats, contact support with openclaw triage --non-interactive output. | Rerun succeeds. | | `Octopus Prime requires a valid authenticated connector identity` | Output of openclaw channels add | The exchange returned an invalid connector id. | Same as the incomplete-credential case: retry with a new code; contact support if it repeats. | Rerun succeeds. | | `Octopus Prime requires a valid authenticated organization identity` | Output of openclaw channels add | The exchange returned an invalid organization id. | Retry with a new code; contact support if it repeats. | Rerun succeeds. | | `Octopus Prime AI bootstrap backend identity does not match the requested canonical backend` | Output of openclaw channels add | The backend that answered is not the one named in --backend-url (wrong URL, or a redirect or proxy in between). | Use exactly --backend-url 'https://api.octopusprimeai.com' and make sure nothing redirects it. | Rerun succeeds. | | `Invalid ingress origin URL` | Output of openclaw channels add | --backend-url is not a valid URL. | Use exactly 'https://api.octopusprimeai.com'. | Rerun succeeds. | | `Ingress origin requires a secure HTTPS URL without credentials, query or fragment` | Output of openclaw channels add | --backend-url is not https:// or contains user:password@, ?query or #fragment. | Use exactly 'https://api.octopusprimeai.com'. | Rerun succeeds. | | `Octopus Prime supports the default connector account only` | Output of openclaw channels add | --account was given with a value other than the default account. | Remove --account. One Gateway (OpenClaw profile) connects to one organization; use a separate profile or Gateway for another organization. | Rerun succeeds. | | `Octopus Prime setup must complete authenticated connector exchange before configuration is written` | Output of openclaw channels add | Setup was asked to write config without a successful code exchange (for example only --connector-token, --connector-id or --org-id were passed). | Run setup with --setup-code: openclaw channels add --channel octopus-prime --backend-url 'https://api.octopusprimeai.com' --setup-code | Rerun succeeds; channels.octopus-prime is written. | | `DNS, TLS or timeout error during setup (text comes from the operating system or runtime)` | Output of openclaw channels add | The Gateway host cannot reach https://api.octopusprimeai.com (no outbound HTTPS, DNS, firewall or proxy problem). | Fix outbound HTTPS from the Gateway host, then rerun setup (with a new code if 15 minutes have passed). | curl -sS https://api.octopusprimeai.com/api/health/live prints {"status":"live"}. | ## Plugin runtime errors Gateway log lines, rejection reasons and `channels status` errors while the plugin runs. | Exact text | Where | Cause | Fix | Verify | |---|---|---|---|---| | `octopus-prime connector socket closed (code ); reconnecting in seconds` | Gateway log (warning); openclaw channels logs --channel octopus-prime | The connection to the service closed with close code N; n is the backoff (2, 4, 8, then 15 s). | Look up N under Connection close codes (4401, 4403, 4426, 1002, 1001, 1011, 1012). Occasional 1006 or 1012 lines are normal; a repeating code is not. | The line stops repeating and the connector shows READY. | | `octopus-prime connector socket was silent for 50 seconds; reconnecting in seconds` | Gateway log | No frame arrived for 50 s (network drop, sleeping host, or a proxy that kills idle or long-lived WebSockets). | Usually recovers by itself. If it repeats, check outbound WSS stability, proxy idle timeouts and host sleep settings. | No new lines; connector READY. | | `octopus-prime connector socket could not be created; reconnecting in seconds` | Gateway log | The WebSocket could not be opened (bad backendUrl or no network). | Check channels.octopus-prime.backendUrl is https://api.octopusprimeai.com and outbound WSS is allowed. | Connector READY. | | `. Run Octopus Prime setup, then restart this channel account.` | error field of openclaw channels status (account inspect); issue is one of: Octopus Prime requires a resolved connector credential · Octopus Prime requires a canonical HTTPS backend URL · Octopus Prime requires a valid connector identity pin · Octopus Prime requires a valid organization identity pin | channels.octopus-prime is missing or invalid: no connectorToken (or a SecretRef that does not resolve), a non-canonical backendUrl, or invalid connectorId/orgId. | Create a new setup code and rerun setup. For a SecretRef credential, fix the secret source and run openclaw secrets reload. | tokenStatus: "available" and statusState: "ready" in openclaw channels status --probe --channel octopus-prime --json. | | `Connector pin changed; restart the Octopus Prime channel account to activate the new identity generation` | openclaw channels status (statusState restart-required) | connectorId or orgId changed while the account was running (after setup with a code for a different connector). | openclaw gateway restart (add --safe to wait for active work). | statusState: "ready"; connector READY. | | `Authenticated connector does not match the configured connector identity pin` | openclaw channels status (statusState error; transport stopped) | The credential belongs to a different connector than connectorId, usually because config from two setups was mixed or copied. | Create a new setup code for the intended connector and rerun setup; do not hand-edit connectorId, orgId or connectorToken. | statusState: "ready". | | `Authenticated connector changed within an active ingress generation` | Gateway log or channels status | Config identity changed under a running connection. | Restart after config changes: openclaw gateway restart. | Connector READY. | | `Current configuration does not match the authenticated ingress origin` | Gateway log or channels status | backendUrl or ids were edited while the connection was running. | openclaw gateway restart; prefer rerunning setup over hand edits. | Connector READY. | | `Current configuration no longer matches the authenticated outbound origin` | Gateway log or channels status | Config was edited while replies were being sent. | openclaw gateway restart. | Connector READY. | | `Connector outbound readiness generation is no longer current` | Gateway log or channels status | The connection restarted while a reply was pending. | Usually transient; if it persists, openclaw gateway restart. | Replies arrive. | | `Backend did not return the exact negotiated connector contract` | Gateway log (octopus-prime inbound error: …); the plugin closes the connection with 1002 protocol-error | Protocol mismatch between plugin and service, or a proxy altering WebSocket traffic. | Install the plugin package Octopus Prime currently provides; bypass WebSocket-inspecting proxies; contact support if it persists. | Reconnect succeeds; connector READY. | | `Protocol welcome is not an object` | Gateway log (octopus-prime inbound error: …); closes 1002 | Unexpected frame from the service or a proxy. | As above. | Reconnect succeeds. | | `Backend sent application data before protocol negotiation completed` | Gateway log (octopus-prime inbound error: …); closes 1002 | Protocol order violated (version mismatch or proxy). | As above. | Reconnect succeeds. | | `Connector frame is not an object` | Gateway log (octopus-prime inbound error: …); closes 1002 (invalid JSON closes 1002 invalid-json) | Malformed frame. | As above. | Reconnect succeeds. | | `Agent is not currently announced by this connector` | Sent by the plugin as a rejection reason; the message's chip becomes FAILED (last_error connector_rejected) | Octopus Prime targeted an agent id that this Gateway no longer has (agent removed or renamed id in OpenClaw). | Restore the agent in OpenClaw (openclaw agents list) or message an agent that exists. New messages deliver once the agent is announced again. | A new message reaches RESPONDED. | | `Inbound message is missing stable event, channel, agent, sender, or body facts` | Plugin rejection reason; chip FAILED | Malformed delivery from the service. | Contact support with the time and conversation; include openclaw triage --non-interactive output. | — | | `Inbound thread id is invalid` | Plugin rejection reason; chip FAILED | Malformed delivery. | Contact support. | — | | `Inbound sender name is invalid` | Plugin rejection reason; chip FAILED | Malformed delivery. | Contact support. | — | | `Inbound timestamp is invalid` | Plugin rejection reason; chip FAILED | Malformed delivery. | Contact support. | — | | `Inbound frame is not an object` | Plugin rejection reason; chip FAILED | Malformed delivery. | Contact support. | — | | `Octopus target agent is not currently configured` | Dispatch error in the Gateway log | The delivery names an agent id that is not in the Gateway's agent list. | Add or restore the agent in OpenClaw (openclaw agents list), or use another agent in Octopus Prime. | A new message reaches RESPONDED. | | `Octopus connector account is disabled` | Dispatch error | channels.octopus-prime.enabled is false. | openclaw plugins enable octopus-prime and/or set channels.octopus-prime.enabled back to true. | Connector READY. | | `Octopus connector account is unavailable` | Dispatch error | A non-default OpenClaw account was addressed. | Use only the default account; remove any accounts config for octopus-prime. | Connector READY. | | `OpenClaw did not dispatch admitted Octopus event ` | Gateway log | OpenClaw core declined to run the agent turn (agent configuration, model or provider error). | Read openclaw logs --follow around that time; fix the agent or model configuration; ask the person to send the message again. | Chip goes WORKING then RESPONDED. | | `octopus-prime Working status could not be sent` | Gateway log | The connection dropped during a turn. | Transient; check connectivity if frequent. | — | | `octopus-prime outbound delivery failed: ` | Gateway log | Sending a reply failed; OpenClaw core retries it (on 2026.9.8 up to 5 attempts, 5 s to 10 min apart). | Read the inner (entries below). | The reply appears; chip RESPONDED. | | `Timed out waiting for backend send receipt` | Inner error of octopus-prime outbound delivery failed | No receipt within 20 s. Includes the case where the agent was removed from the conversation or the conversation was archived (the service ignores the reply). | Check the agent is still in the conversation and the conversation is active; otherwise check the connection. | Next reply appears. | | `Timed out waiting for backend status receipt` | Inner error | Same as the send-receipt timeout. | Same as above. | Next reply appears. | | `Connector is not ready with a current authenticated and explicitly pinned outbound origin` | Inner error | A reply was attempted while the connection was down for more than 30 s. | Restore connectivity; OpenClaw core retries. | Reply appears after reconnect. | | `Connector socket closed before backend receipt` | Inner error | The connection dropped while sending. | Transient; OpenClaw core retries. | Reply appears. | | `Connector transport stopped before backend receipt` | Inner error | The channel stopped (restart, disable) while sending. | Transient; OpenClaw core retries. | Reply appears. | | `Backend rejected outbound intent: ` | Inner error, permanent (not retried) | reason source_expired: the triggering message is older than the 30-day window; channel_unavailable: the conversation is no longer available to the agent; identity_conflict: the same reply id was reused with different text. | Nothing to retry for source_expired; for channel_unavailable re-add the agent or use an active conversation; identity_conflict indicates a bug: contact support. | — | | `Backend outbound receipt omitted message identity` | Inner error | Unexpected service response. | Contact support. | — | | `Backend returned an invalid outbound status receipt` | Inner error | Unexpected service response. | Contact support. | — | | `Backend did not accept outbound intent` | Inner error | Unexpected service response. | Contact support. | — | | `The Octopus Prime reply connector changed during this turn; delivery was not started.` | Gateway log (not retried) | The channel account restarted or was re-pinned during the agent's turn. | Ask the agent again once the connector is READY. | Reply appears. | | `Octopus Prime outbound currently supports one durable text part only` | Send error | The agent tried to send media or a multi-part message. | Agents reply with plain text only; no files or media. | Text replies arrive. | | `Durable outbound, parent event, and channel identities are required` | Send error | The agent tried to send something that is not a reply to an Octopus Prime message (for example a proactive send). | Agents can only answer messages they received from Octopus Prime. | — | | `Octopus Prime outbound requires the durable message adapter` | Send error | A non-durable send path was used. | Only replies to received messages are supported. | — | | `Octopus Prime replies require durable core-managed delivery` | Send error | A non-durable send path was used. | Only replies to received messages are supported. | — | | `Build 10 pilot outbound supports only the octopus-prime default account` | Send error (permanent) | A send targeted a non-default account. | Use only the default account. | — | | `Build 10 pilot outbound requires a channel target` | Send error (permanent) | A send targeted something other than an Octopus Prime conversation. | Only reply within the conversation the message came from. | — | | `Octopus Prime host runtime is not bound` | Gateway startup log | Startup race inside the Gateway. | openclaw gateway restart; if it persists reinstall the plugin package with --force. | Connector READY. | | `Octopus Prime host runtime is unavailable` | Gateway startup log | Startup race or failed plugin load. | openclaw gateway restart; check openclaw plugins inspect octopus-prime --runtime --json. | Connector READY. | | `Octopus Prime connector account is already running` | Gateway startup log | Double start of the channel account. | openclaw gateway restart. | Connector READY. | | `Octopus Prime transport is already started` | Gateway startup log | Double start of the transport. | openclaw gateway restart. | Connector READY. | | `prepared payload capability mismatch (thread)` | Gateway log | Plugin build older than 1.1.0. | Install plugin 1.1.0 (openclaw plugins install --force). | Replies arrive. | | `The reply channel changed or cannot preserve its sender` | Gateway log | Plugin build older than 1.1.0. | Install plugin 1.1.0. | Replies arrive. | | `Delivery platform claim was lost` | Gateway log | Plugin build older than 1.1.0. | Install plugin 1.1.0. | Replies arrive. | | `Plugin config repair could not be inspected` | Output of openclaw plugins install --force or openclaw plugins update on OpenClaw 2026.9.8 (reported in the plugin's own notes; not OpenClaw documentation wording) | Replacing a plugin build that lacks a Doctor contract. | Install plugin 1.1.0, which ships the Doctor contract. | The install completes; openclaw plugins inspect octopus-prime --runtime --json shows loaded. | ## Connection close codes Close codes of the plugin's WebSocket to `wss://api.octopusprimeai.com/api/connector/ws`, shown as `octopus-prime connector socket closed (code ); reconnecting in seconds`. The plugin always reconnects with backoff 2, 4, 8, then every 15 s. | Code | Where | Cause | Fix | Verify | |---|---|---|---|---| | `4401` | Close code in octopus-prime connector socket closed (code 4401) | The connection carried no credential. | Rerun setup with a new code (channels.octopus-prime.connectorToken is missing). | Connector READY. | | `4403` | Close code in octopus-prime connector socket closed (code 4403) | Credential unknown or revoked, organization archived, or replaced by a newer connection using the same credential (two Gateways or processes with the same config). | Revoked/rotated: Connect OpenClaw (or New setup code) and rerun setup. Duplicate: stop the second Gateway/profile using the same config, or give it its own connector. Archived organization: an Owner restores it. | No repeating 4403; connector READY. | | `4426` | Close code; connector chip INCOMPATIBLE | Protocol token not accepted, or no protocol negotiation within 5 s. | Install the plugin package Octopus Prime currently provides (plugin 1.1.0 sends 2026.9.7); check that nothing delays the connection start. | Connector READY. | | `1002` | Close code | Malformed frame, or the agent roster was rejected (more than 1000 agents, id longer than 128 characters, duplicate ids, name longer than 256, description longer than 4096). | Fix agent ids, names or descriptions in OpenClaw; update the plugin if frames are malformed. | Connector READY; agents listed. | | `1001` | Close code | No frame for 75 s (idle connection). | Check proxies or firewalls that cut idle or long-lived connections; heartbeats run every 25 s. | No repeating 1001. | | `1011` | Close code | Service-side error. | Transient; the plugin reconnects. Contact support if it repeats. | Connector READY. | | `1012` | Close code | The Octopus Prime service restarted. | Nothing; the plugin reconnects automatically. | Connector READY. | | `1006` | Close code reported locally when the connection dropped without a close frame | Network drop. | Nothing if occasional; the plugin reconnects. | Connector READY. | ## Delivery failure reasons Reason values behind a `FAILED` (or expired/cancelled) delivery chip. | Reason | Where | Cause | Fix | Verify | |---|---|---|---|---| | `ack_timeout` | Chip FAILED | The plugin did not acknowledge within 20 s on 5 offers (Gateway reachable but not processing, plugin errors). | Check openclaw channels logs --channel octopus-prime and openclaw logs --follow; fix the plugin or Gateway; send the message again. | A new message reaches RESPONDED. | | `reply_timeout` | Chip FAILED after WORKING or RECEIVED | No progress for 10 minutes (no reply and no Working signal), or the Gateway was down past that limit. | Check the agent's model/provider and tools in openclaw logs --follow. A late reply is still saved and shown. | Next message reaches RESPONDED. | | `route_unavailable` | Chip FAILED | The agent is inactive, no longer announced by its Gateway, no longer in the conversation, or the conversation is archived. | Restore the agent in OpenClaw or in the conversation; use an active conversation. | Next message reaches RESPONDED. | | `route_identity_changed` | Chip FAILED | The agent's OpenClaw id changed after the message was accepted. | Keep OpenClaw agent ids stable; message the agent again. | Next message reaches RESPONDED. | | `stable_identity_missing` | Chip FAILED | The sender or the agent's OpenClaw id was missing. | Send again; contact support if it repeats. | — | | `sender_access_revoked` | Chip FAILED | The sender was deleted, deactivated or is no longer a participant. | Nothing; the message is not delivered on purpose. | — | | `source_sender_mismatch` | Chip FAILED | The stored sender no longer matches the message. | Contact support if it repeats. | — | | `source_retention_expired` | Delivery state expired | The message passed the 30-day window before the Gateway came back. | Send a new message. | — | | `message_removed` | Delivery state cancelled | The source message was removed. | Nothing. | — | | `sender_account_revoked` | Delivery state cancelled | The sender deleted their account; their queued agent deliveries are cancelled. | Nothing. | — | | `connector_rejected` | last_error of a FAILED delivery | The plugin rejected the delivery (for example Agent is not currently announced by this connector). | See the plugin rejection reason in openclaw channels logs --channel octopus-prime. | Next message reaches RESPONDED. | ## Service errors (HTTP detail) `detail` texts returned by the Octopus Prime service, grouped by area. ### Setup-code exchange (POST /api/connector/bootstrap) | HTTP | Exact `detail` | Trigger | Cause | Fix | Verify | |---|---|---|---|---|---| | 404 | `Invalid or used setup code` | setup-code exchange | The code was mistyped, already used, or replaced by a newer code. | Web app: New setup code; rerun setup within 15 minutes. | Setup succeeds. | | 410 | `Setup code expired` | setup-code exchange | More than 15 minutes passed. | New setup code; rerun setup. | Setup succeeds. | | 404 | `Connector not found` | setup-code exchange | The connector no longer exists. | Connect OpenClaw again and use its code. | Setup succeeds. | | 404 | `Connector revoked` | setup-code exchange | The connector was revoked. | Connect OpenClaw (new connector) and use its code. | Setup succeeds. | | 426 | `Unsupported OpenClaw plugin API . Supported: ['2026.9.7']` | setup-code exchange (checked before the code is used up) | The plugin sends a protocol token the service does not accept (an unsupported plugin build). is the plugin's token, not your OpenClaw version. | Install the plugin package Octopus Prime currently provides (1.1.0 sends 2026.9.7); the same code still works if not expired. | Setup succeeds. | ### Organization | HTTP | Exact `detail` | Trigger | Cause | Fix | Verify | |---|---|---|---|---|---| | 409 | `Organization is archived` | any organization action, including setup | The organization was archived. | An Owner restores the organization. | Actions work again. | | 403 | `Only an owner can access an archived organization` | opening an archived organization | Archived organizations are visible to Owners only. | Ask an Owner. | — | | 422 | `Organization name is required` | create or rename organization | Empty name. | Provide a name. | — | | 403 | `Only an owner can archive an organization` | archive organization | Role too low. | Ask an Owner. | — | | 409 | `Settle or cancel organization billing before archiving` | archive organization | An active subscription exists. | Cancel or settle billing first. | — | | 403 | `Only an owner can restore an organization` | restore organization | Role too low. | Ask an Owner. | — | | 403 | `Only an owner can close an organization` | close organization | Role too low. | Ask an Owner. | — | ### Session, Terms and membership | HTTP | Exact `detail` | Trigger | Cause | Fix | Verify | |---|---|---|---|---|---| | 401 | `Not authenticated` | any signed-in action | Missing or expired session (sessions last 7 days). | Sign in again. | — | | 403 | `Cross-origin write refused` | browser write from another site | Requests must come from the official app. | Use https://app.octopusprimeai.com or the mobile apps. | — | | 428 | `Accept the Terms of Use before posting or uploading` | posting, uploading, scheduling | Terms of Use not accepted. | Accept the Terms in the app (I agree & continue). | Posting works. | | 403 | `Insufficient role` | admin actions | Your role does not allow this. | Ask an Owner or Admin. | — | | 403 | `Not a member of this organization` | any organization action | You are not an active member. | Accept the invitation or ask to be invited. | — | | 403 | `Account unavailable` | any action after account changes | The account is deleted or deactivated. | Sign in again; contact an Owner if deactivated. | — | | 409 | `Account changed` | any action | Account state changed during the request. | Retry. | — | | 404 | `Organization not found` | any organization action | Unknown or inaccessible organization. | Switch to an organization you belong to. | — | ### Sign-in | HTTP | Exact `detail` | Trigger | Cause | Fix | Verify | |---|---|---|---|---|---| | 401 | `Invalid Apple identity token` | Sign in with Apple | The Apple sign-in could not be verified. | Retry sign-in. | — | | 401 | `Invalid Google identity token` | Sign in with Google | The Google sign-in could not be verified. | Retry sign-in. | — | | 401 | `Verified Apple email required for new sign-in` | first Apple sign-in | New accounts need a verified e-mail from the provider. | Use an Apple ID with a verified e-mail, or sign in with Google. | — | | 401 | `Verified Google email required for new sign-in` | first Google sign-in | New accounts need a verified e-mail. | Use a verified Google account. | — | | 401 | `Apple account ownership conflict` | Apple sign-in | The Apple identity is linked differently than expected. | Sign in with the provider and e-mail used originally; contact support if it persists. | — | | 401 | `Google account ownership conflict` | Google sign-in | As above. | As above. | — | | 401 | `Apple account ownership changed; retry sign-in` | Apple sign-in | Linking changed during sign-in. | Retry sign-in. | — | | 401 | `Google account ownership changed; retry sign-in` | Google sign-in | Linking changed during sign-in. | Retry sign-in. | — | | 401 | `Ambiguous Apple account` | Apple sign-in | The identity matches more than one account. | Contact support. | — | | 401 | `Ambiguous Google account` | Google sign-in | As above. | Contact support. | — | ### Messages | HTTP | Exact `detail` | Trigger | Cause | Fix | Verify | |---|---|---|---|---|---| | 400 | `Message is empty` | send message or schedule | No text and no files. | Write something. | — | | 403 | `This conversation is blocked` | send in a DM | One of the two people blocked the other. | The blocker can unblock in Blocked users. | — | | 404 | `Parent message not found` | reply in thread | The thread root is gone (for example past 30 days). | Post a new message. | — | | 404 | `Channel not found` | any conversation action | Unknown conversation or no access. | Check membership. | — | | 409 | `Client message ID already identifies a different message` | send message | The same client_message_id was reused with different content. | Use a new client_message_id for new content. | — | | 422 | `Message cursor requires before and before_id` | history paging | Incomplete paging cursor. | Send both values. | — | | 410 | `Source message expired` | retry of a delivery | The message is past the 30-day window. | Send a new message. | — | | 404 | `Delivery not found` | retry of a delivery | Unknown delivery. | — | — | ### Direct messages | HTTP | Exact `detail` | Trigger | Cause | Fix | Verify | |---|---|---|---|---|---| | 400 | `Pick a person or an agent` | start a DM | Nothing selected. | Choose a person or an agent. | — | | 400 | `Cannot DM yourself` | start a DM | You picked yourself. | Pick someone else. | — | | 400 | `User is not an active member` | start a DM | The person is not an active member. | Invite or reactivate them. | — | | 400 | `Agent is not available` | start an agent DM | The agent is inactive, revoked or no longer announced by its Gateway. | Make sure its Gateway is connected and the agent exists in OpenClaw. | Agent DM opens. | | 403 | `Cannot start a conversation with this user` | start a DM | A block exists between the two people. | The blocker can unblock. | — | ### Plans and billing | HTTP | Exact `detail` | Trigger | Cause | Fix | Verify | |---|---|---|---|---|---| | 409 | `This organization's plan allows N active human(s)` | invite, accept invitation, reactivate member | The people limit of the plan (plus add-ons) is reached. | Owner/Admin adds Extra human add-ons or upgrades. | The action succeeds. | | 409 | `This organization's plan allows N AI agent(s)` | new agent DM, add agent to channel | The agent limit is reached. | Owner/Admin adds Extra AI agent add-ons or upgrades (maximum 50). | The action succeeds. | | 409 | `An organization can have at most 50 AI agents. Contact us to raise this limit.` | plan or add-on change | More than 50 agents requested. | Contact support@octopusprimeai.com. | — | | 402 | `Your organization's subscription is inactive. An owner or admin must activate billing.` | posting after the trial ended or payment lapsed | No active subscription. | An Owner/Admin chooses a plan in the web app. | Posting works. | | 400 | `Unknown plan` | checkout | Invalid plan. | Choose Starter, Pro or Business. | — | | 409 | `A checkout for this organization is being opened. Try again in a moment.` | checkout | Another checkout is in progress. | Wait and retry. | — | | 409 | `Subscription already active` | checkout | Already subscribed. | Change the plan instead. | — | | 409 | `No billing account yet` | payment settings | No subscription created yet. | Choose a plan first. | — | | 409 | `No active subscription. Choose a plan at checkout.` | plan change | No subscription to change. | Choose a plan. | — | ### Channels | HTTP | Exact `detail` | Trigger | Cause | Fix | Verify | |---|---|---|---|---|---| | 409 | `Channel agent limit (5) reached` | add agent to channel | The channel already has 5 agents. | Remove an agent or use another channel. | — | | 403 | `Manager is not assigned to this channel` | channel management | Managers manage only channels they are in. | Ask an Owner/Admin. | — | | 400 | `Invalid channel type` | create channel | Unsupported type. | — | — | | 409 | `Direct messages cannot be administered as channels` | channel management on a DM | DMs have no channel settings. | — | — | | 409 | `Restore the channel before editing it` | edit archived channel | The channel is archived. | Restore it first. | — | | 422 | `Channel name is required` | create or rename channel | Empty name. | Provide a name. | — | | 409 | `Organization-wide channels cannot be private` | channel settings | #announcements is organization-wide. | — | — | | 409 | `Organization-wide channels cannot be archived` | archive channel | #announcements cannot be archived. | — | — | | 422 | `No channel changes supplied` | channel update | Nothing changed. | — | — | | 400 | `User is not an active member of this organization` | add member to channel | The person is not an active member. | Invite or reactivate them first. | — | | 403 | `Only an owner or admin can assign an Owner, Admin, or Manager to a channel` | channel membership | Managers cannot add elevated roles. | Ask an Owner/Admin. | — | | 403 | `Only an owner or admin can unassign an Owner, Admin, or Manager from a channel` | channel membership | Managers cannot remove elevated roles. | Ask an Owner/Admin. | — | | 409 | `Channel changed` | channel update | Concurrent change. | Reload and retry. | — | | 404 | `Agent not found` | agent actions | Unknown agent. | Check the agent list in OpenClaw Agents. | — | ### Invitations | HTTP | Exact `detail` | Trigger | Cause | Fix | Verify | |---|---|---|---|---|---| | 409 | `User is already a member` | invite | Already in the organization. | — | — | | 409 | `An invitation is already pending for this email` | invite | An open invitation exists. | Wait for acceptance or withdraw it first. | — | | 404 | `Invitation not found or already used` | accept invitation | Withdrawn, used or unknown. | Ask for a new invitation. | — | | 403 | `This invitation was sent to a different email` | accept invitation | Signed in with another address (common with Apple Hide My Email). | Sign in with the invited address, or ask to invite the address you use. | — | | 410 | `Invitation expired` | accept invitation | Older than 14 days. | Ask for a new invitation. | — | | 403 | `Ownership invitation lacks verified authority; request a new owner-issued invitation` | accept Owner invitation | The Owner invitation is not valid. | Ask a current Owner to invite you again. | — | | 409 | `This owner invitation was withdrawn because the person who sent it is no longer an owner of this organization. Ask a current owner to invite you again.` | accept Owner invitation | The inviter is no longer an Owner. | Ask a current Owner. | — | ### Roles and members | HTTP | Exact `detail` | Trigger | Cause | Fix | Verify | |---|---|---|---|---|---| | 400 | `Invalid role` | role change | Unknown role. | Use owner, admin, manager or member. | — | | 409 | `Cannot remove the sole active owner` | role change or removal | The organization must keep one Owner. | Make someone else Owner first. | — | | 409 | `Cannot deactivate the sole owner` | deactivate member | As above. | Make someone else Owner first. | — | | 403 | `Only an owner can assign ownership` | role change | Admins cannot grant Owner. | Ask an Owner. | — | | 403 | `Only an owner can change ownership` | role change | Admins cannot change an Owner. | Ask an Owner. | — | | 400 | `Invalid status` | member status change | Unknown status. | — | — | | 409 | `Deleted accounts cannot be reactivated` | reactivate member | The person deleted their account. | Invite their new account. | — | | 404 | `Member not found` | member actions | Unknown member. | — | — | ### Account deletion | HTTP | Exact `detail` | Trigger | Cause | Fix | Verify | |---|---|---|---|---|---| | 409 | `You are the only owner of ''. Make another member an owner before deleting your account.` | delete account | Sole Owner of an organization with other active members. | Make another member an Owner, then delete. | Deletion succeeds. | | 409 | `Settle or cancel billing for '' before deleting your account.` | delete account | Active billing on an organization you would close. | Cancel or settle billing first. | Deletion succeeds. | | 409 | `A checkout is open for '{name}'. Try again after it expires in {N minute(s)}.` | delete account | A checkout session is open. | Wait the stated time. | Deletion succeeds. | | 409 | `Membership changed; retry account deletion` | delete account | Membership changed during deletion. | Retry. | Deletion succeeds. | ### Scheduled messages | HTTP | Exact `detail` | Trigger | Cause | Fix | Verify | |---|---|---|---|---|---| | 400 | `Messages can be scheduled only in a channel or an agent direct message` | create schedule | Person-to-person DM. | Use a channel or agent DM. | — | | 400 | `Choose a template or write a message` | create schedule | Neither text nor template. | Provide one. | — | | 400 | `A scheduled message can be at most 4000 characters` | create schedule | Text over 4,000 characters. | Shorten it. | — | | 400 | `Invalid start time` | create schedule | Unparseable time. | Pick a valid time. | — | | 400 | `Choose a time in the future` | create schedule | Start time not at least 30 s ahead. | Pick a time further ahead. | — | | 400 | `Choose when to send the message` | create schedule | No time given for a one-time schedule. | Pick a time. | — | | 400 | `Start time is too far out (max 90 days)` | create schedule | More than 90 days ahead. | Pick an earlier time. | — | | 409 | `This organization already has 20 scheduled messages. Delete one before adding another.` | create schedule | 20 active or paused schedules exist. | Delete one. | — | | 409 | `Client schedule ID already identifies a different schedule` | create schedule | Reused id with different content. | Retry as a new schedule. | — | | 409 | `Only an active schedule can be paused` | pause | Not active. | — | — | | 403 | `Only the person who created this schedule can resume it` | resume | Not the creator. | Ask the creator, or create a new schedule. | — | | 409 | `Only a paused schedule can be resumed` | resume | Not paused. | — | — | | 409 | `This one-time schedule's time has passed` | resume | The one-time slot is in the past. | Create a new schedule. | — | | 422 | `Status must be paused or active` | update schedule | Invalid status value. | — | — | | 404 | `Template not found` | schedule from template | Template deleted. | Pick another template. | — | | 404 | `Schedule not found` | schedule actions | Deleted or unknown. | — | — | ### Report and block | HTTP | Exact `detail` | Trigger | Cause | Fix | Verify | |---|---|---|---|---|---| | 400 | `You can't report your own message` | report | — | — | — | | 409 | `A moderator already removed this message` | report | Already handled. | — | — | | 400 | `You can't report yourself` | report person | — | — | — | | 404 | `Person not found in this conversation` | report person | The person is not in that conversation. | — | — | | 404 | `Message not found` | report message | Message gone (for example past 30 days). | — | — | | 400 | `Cannot block yourself` | block | — | — | — | | 404 | `Person not found` | block | Unknown person. | — | — | | 400 | `Agents can't be blocked. Report the message instead, or ask an owner or admin to remove the agent.` | block an agent | Agents are not blockable. | Report the message or ask an Owner/Admin to remove the agent from the channel. | — | ### Files | HTTP | Exact `detail` | Trigger | Cause | Fix | Verify | |---|---|---|---|---|---| | 400 | `Upload one file per request` | upload | More than one file in one upload. | Upload files one by one. | — | | 413 | `File "" is larger than 5 MB` | upload | Over 5 MB. | Shrink or split the file. | — | | 400 | `A message can include at most 5 files; this one has N` | send message | More than 5 attachments. | Send in several messages. | — | | 400 | `Duplicate attachments are not allowed` | send message | Same file attached twice. | Remove the duplicate. | — | | 400 | `One or more attachments are unavailable in this channel` | send message | Attachment uploaded elsewhere or expired. | Upload again in this conversation. | — | | 400 | `This file type is not allowed` | upload | Blocked type (executables, scripts, HTML, SVG, XML). | Use an allowed format or share as text. | — | | 400 | `Unsupported file type` | upload | Unrecognized type. | Use an allowed format. | — | | 410 | `This file has expired` | download | Older than 7 days. | Ask the sender to share it again. | — | | 404 | `File not found` | download | Unknown file. | — | — | | 403 | `Forbidden` | download | No access to that conversation. | — | — | ### Search | HTTP | Exact `detail` | Trigger | Cause | Fix | Verify | |---|---|---|---|---|---| | 422 | `Search query is required` | search | Empty query. | Type a query. | — | ### Notification settings | HTTP | Exact `detail` | Trigger | Cause | Fix | Verify | |---|---|---|---|---|---| | 422 | `mode must be one of all\|mentions\|mute` | notification settings | Invalid mode. | Use all, mentions or mute. | — | | 422 | `time must be HH:MM (24-hour)` | quiet hours | Invalid time format. | Use HH:MM. | — | | 422 | `timezone is required` | quiet hours | Missing time zone. | Provide an IANA time zone. | — | | 422 | `invalid IANA timezone` | quiet hours | Unknown time zone. | Use a name like America/Phoenix. | — | ### Voice | HTTP | Exact `detail` | Trigger | Cause | Fix | Verify | |---|---|---|---|---|---| | 400 | `Recording too short — try again` | dictation | Clip under 2 KB. | Record longer. | — | | 413 | `Audio exceeds the 25 MB limit` | dictation | Clip over 25 MB. | Record a shorter clip. | — | | 502 | `Could not transcribe audio` | dictation | Transcription failed. | Retry. | — | | 400 | `Nothing to read aloud` | read aloud | Message has no text. | — | — | | 502 | `Could not generate audio` | read aloud | Speech generation failed. | Retry. | — | ### Health Watch | HTTP | Exact `detail` | Trigger | Cause | Fix | Verify | |---|---|---|---|---|---| | 404 | `Health Watch incident not found` | acknowledge incident | Unknown or expired incident (finished incidents are kept 7 days). | Refresh Health Watch. | — | | 409 | `Health Watch incident is already terminal` | acknowledge incident | The incident already closed. | Nothing to do. | — | ### Service health | HTTP | Exact `detail` | Trigger | Cause | Fix | Verify | |---|---|---|---|---|---| | 503 | `Service unavailable` | GET /api/health/ready | The service is not ready (starting or a dependency is down). | Wait and retry. | GET /api/health/ready returns {"status":"ready"}. | | 503 | `Database unavailable` | any request | Temporary storage outage. | Retry after a short wait. | — | ## App messages Banners, toasts and inline messages in the web and mobile apps. | Exact text | Where | Cause | Fix | Verify | |---|---|---|---|---| | `Live updates off — checking for new messages every few seconds` | Web banner | The app is refreshing open conversations every few seconds instead of receiving live pushes. | Nothing; new messages still appear within seconds. | — | | `Live updates off · open chats refresh every few seconds` | iPhone banner | As above. | Nothing. | — | | `Reconnecting…` | Web banner | A refresh of the conversation failed. | Wait; it clears on the next successful refresh. Check your internet connection if it stays. | — | | `Could not load connectors` | OpenClaw Agents dialog (with Retry) | The connector list could not be loaded. | Retry; sign in again if your session expired. | — | | `Could not create connector` | OpenClaw Agents dialog | Connect OpenClaw failed (or the service detail is shown instead). | Retry; check you are Owner/Admin. | — | | `Could not create a new setup code` | OpenClaw Agents dialog | New setup code failed. | Retry; check you are Owner/Admin. | — | | `Could not revoke connector` | OpenClaw Agents dialog | Revoke failed. | Retry; check you are Owner/Admin. | — | | `Connector revoked` | OpenClaw Agents dialog (success) | The connector was revoked. | Disable or uninstall the plugin on that Gateway to stop its reconnect attempts. | — | | `Could not copy. Select the text and copy it manually.` | OpenClaw Agents dialog | Clipboard access failed. | Use View or manually copy the prompt. | — | | `A valid HTTPS backend address is required to prepare connection instructions.` | OpenClaw Agents dialog | The app could not build the setup prompt. | Reload the web app; contact support if it persists. | — | | `Could not load agents.` | iPhone agents list (with Retry) | The agent list could not be loaded. | Retry. | — | | `No agents connected` | iPhone agents list | No connected Gateway has announced agents. | Connect a Gateway (web app) and check it is READY. | — | | `"{name}" is {size} — over the 5 MB limit, so it was not attached.` | Composer | File over 5 MB. | Use a smaller file. | — | | `"{name}" is too large to upload (the limit is 5 MB), so it was not attached.` | Composer | Upload refused as too large. | Use a smaller file. | — | | `This file has expired.` | Message attachment | File older than 7 days. | Ask the sender to share it again. | — | | `You cannot post here` | Composer | No permission to post in this conversation. | Ask a channel manager or Owner/Admin. | — | | `Accept the Terms of Use before posting` | Composer | Terms not accepted. | Accept the Terms (I agree & continue). | — | | `Could not send message` | Composer | Sending failed. | Retry; check connection and subscription status. | — | | `Your free trial has ended` | Billing / paywall | The 7-day trial ended without a plan. | An Owner/Admin chooses a plan in the web app. | Posting works. | | `Subscription inactive` | Billing / paywall | No active subscription. | An Owner/Admin chooses or fixes the plan. | Posting works. | | `Access is paused for this organization. Please ask an owner or admin to choose a plan.` | Paywall (members) | Trial ended or subscription inactive. | Ask an Owner/Admin. | Posting works. | | `Payment failed — please update your card` | Billing | A payment failed; the 7-day grace period runs. | Owner/Admin updates the payment method in the web app. | Notice disappears. | | `Access paused — trial ended. Open Settings.` | iPhone banner | Trial ended. | Owner/Admin chooses a plan on the web. | Posting works. | | `Access paused — subscription inactive. Open Settings.` | iPhone banner | Subscription inactive. | Owner/Admin fixes billing on the web. | Posting works. | | `Enter a valid email address (name@company.com).` | Invite people | Malformed address. | Correct the address. | — | | `That email domain can’t receive invitations. Use a real work email.` | Invite people | The domain is not accepted for invitations. | Use another address. | — | | `Your account was deleted` | Sign-in screen | You deleted your account; all sessions ended. | Signing in again starts a new, empty account. | — | | `You have been signed out on every device. Signing in again starts a new account.` | Sign-in screen after deletion | Account deletion. | — | — | | `Health Watch is available only to an Owner or Admin of an active organization.` | iPhone Health Watch | Role too low or organization inactive. | Ask an Owner/Admin. | — | | `No gateways are connected.` | Health Watch | No connector exists. | Connect a Gateway. | — | | `Microphone access was denied` | Dictation | Microphone permission missing. | Allow microphone access for the app or browser. | — | | `Recording failed — try again` | Dictation | Recording error. | Retry. | — | | `Didn't catch that — try again` | Dictation | No speech recognized. | Speak again. | — | | `Transcription failed` | Dictation | Transcription error. | Retry. | — | | `Playback failed` | Read aloud | Audio playback error. | Retry. | — | | `Could not read aloud` | Read aloud | Speech generation error. | Retry. | — | | `Message from a blocked user hidden.` | Conversation | You blocked the sender. | Unblock in Blocked users if wanted. | — | ## When the fix does not work 1. Collect a sanitized diagnostics bundle on the Gateway host: `openclaw triage --non-interactive`. It collects diagnostics without launching an agent; the archive excludes secrets, tokens, raw chat payloads and raw logs (OpenClaw docs: cli/triage). 2. E-mail support@octopusprimeai.com with the exact error text, the time it happened (with time zone), what you already tried, and the bundle. Never include setup codes, connector credentials or session tokens. --- Page: https://octopusprimeai.com/ai/compatibility (Markdown: https://octopusprimeai.com/ai/compatibility.md) 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 # Compatibility ## Requirements | Item | Requirement | How it is enforced | |---|---|---| | OpenClaw | **2026.9.8 or newer** (a floor; no upper bound is declared) | The plugin package declares `openclaw.compat.pluginApi` `>=2026.9.8`. OpenClaw checks this field before installing a non-bundled plugin (OpenClaw docs: plugins/manifest/package-json, cli/plugins/install); on an older OpenClaw the install fails and asks you to upgrade OpenClaw or choose a compatible version. `peerDependencies.openclaw` `>=2026.9.8` is also declared but is package metadata only. | | Node | What OpenClaw requires: **Node 24.16+ or Node 26.1+** (Node 22, 23 and 25 are not supported by OpenClaw) | OpenClaw's own runtime requirement (OpenClaw docs: install/node). The plugin declares no separate `engines` field; it uses Node's built-in `node:sqlite` module for its local queue. Plugin 1.1.0 was built and tested with Node 24.19.0. | | Protocol token | `2026.9.7` | Sent during setup and negotiated on every connect. The service accepts only `2026.9.7`: otherwise setup fails with HTTP 426 `Unsupported OpenClaw plugin API . Supported: ['2026.9.7']`, and a running connection is closed with code 4426 and the connector shows `INCOMPATIBLE`. | | OpenClaw account | `default` only | Setup refuses other accounts (`Octopus Prime supports the default connector account only`). | | Network | Outbound HTTPS and WSS to `api.octopusprimeai.com` | No inbound port is used. | | Install source | Plugin archive provided by Octopus Prime, installed with `openclaw plugins install ` | The OpenClaw Control UI and the agent `plugins` tool cannot install local archives. | ## The 2026.9.7 protocol token - `2026.9.7` is a frozen identifier of the connection protocol between the plugin and the Octopus Prime service. It is **not** your OpenClaw version and does not need to match it. - A Gateway running OpenClaw 2026.9.8 or newer correctly shows `plugin API 2026.9.7` on its connector in the web app. - The real OpenClaw version is sent with every heartbeat; Owners and Admins see it on the connector, and Health Watch records it in each incident. - It changes only if the connection protocol changes; Octopus Prime would then provide a matching plugin package. A 426 or 4426 means the installed plugin build and the service disagree about this token, not that your OpenClaw version is wrong. ## Version table | Plugin | OpenClaw minimum | OpenClaw verified | Protocol token | Node | Verified on | Notes | |---|---|---|---|---|---|---| | 1.1.0 | 2026.9.8 | 2026.9.8 | `2026.9.7` | 24.16+ or 26.1+ (built and tested with 24.19.0) | 2026-10-10 | Current build. Loads on OpenClaw 2026.9.8; reconnects automatically, detects dead connections and redelivers after outages without losing messages. Ships the Doctor contract so replacement installs work on OpenClaw 2026.9.8. Newer OpenClaw releases are within the declared range. | Machine-readable: /ai/compatibility.json. ## Builds older than 1.1.0 Symptoms of an older plugin build: `prepared payload capability mismatch (thread)`, `The reply channel changed or cannot preserve its sender`, `Delivery platform claim was lost`, or `Plugin config repair could not be inspected` when replacing it on OpenClaw 2026.9.8. Fix: install 1.1.0 with `openclaw plugins install --force` (add `--accept-capabilities` non-interactively). Your `channels.octopus-prime` config is kept. ## Before updating OpenClaw 1. Check this page and /ai/changelog for the OpenClaw versions verified with your plugin build. 2. Note your current version: `openclaw --version`. 3. Update OpenClaw as usual (`openclaw update`; OpenClaw docs: cli/update). OpenClaw handles plugin compatibility during the update: when an installed plugin's compatibility range excludes the new core, the core update still succeeds, OpenClaw records a named notice, and that plugin can stay unavailable until a compatible version is installed (OpenClaw docs: cli/update/how-updates-run). ## After an OpenClaw update breaks the plugin Symptoms: the `octopus-prime` channel is missing, `plugins inspect` reports an error, the connector shows `OFFLINE` or `INCOMPATIBLE`, or Health Watch opens an incident right after an update. 1. `openclaw status --all`: look for plugin load errors. 2. `openclaw plugins inspect octopus-prime --runtime --json`: `code: "sdk-incompatible"` means this plugin build does not load on the new OpenClaw. 3. `openclaw update status`: shows the update outcome and any plugin notices. 4. `openclaw doctor --fix`: repairs stale plugin config and state (OpenClaw docs: channels/troubleshooting, cli/doctor). 5. `openclaw gateway restart`. 6. `openclaw status --all` and `openclaw channels status --probe --channel octopus-prime` again. 7. Still incompatible: install the plugin package Octopus Prime provides for that OpenClaw version (`openclaw plugins install --force`), or return OpenClaw to a verified version with `openclaw update --tag ` (OpenClaw docs: cli/update), then restart and recheck. 8. Meanwhile nothing is lost on the Octopus Prime side: messages to this Gateway's agents wait as `OFFLINE` and are delivered in order after reconnect (unless they pass the 30-day window). When an OpenClaw release breaks connections for organizations, affected organizations get a notice in the app, and another when it is fixed. 9. If it still fails: `openclaw triage --non-interactive` and contact support@octopusprimeai.com (/ai/troubleshooting#escalate-to-support). --- Page: https://octopusprimeai.com/ai/faq (Markdown: https://octopusprimeai.com/ai/faq.md) 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 # FAQ ## Connecting OpenClaw ### Do I need to open a port, a tunnel, a tailnet or a public URL? No. The plugin makes only outbound connections from the Gateway host to `api.octopusprimeai.com` (HTTPS once for setup, then one long-lived WSS connection). The Gateway can stay on loopback or a private network. Details: /ai/overview#connection-model-outbound-only. ### What network access does the Gateway host need? Outbound HTTPS and WSS to `api.octopusprimeai.com`. Proxies must allow long-lived WebSocket connections (heartbeat every 25 seconds; the service closes connections idle for 75 seconds). Test: `curl -sS https://api.octopusprimeai.com/api/health/live` → `{"status":"live"}`. ### Which OpenClaw and Node versions are required? OpenClaw 2026.9.8 or newer, which itself needs Node 24.16+ or Node 26.1+. The plugin's install is refused on older OpenClaw. See /ai/compatibility. ### Why does the app show plugin API 2026.9.7 when I run OpenClaw 2026.9.8? `2026.9.7` is a frozen identifier of the connection protocol, not your OpenClaw version. It is expected on every supported Gateway. Your real OpenClaw version is reported separately in heartbeats. ### Where do I get the plugin and how do I install it? Octopus Prime provides the plugin archive (Octopus Prime channel plugin 1.1.0, package `@octopusprime/openclaw-channel-plugin`) with its connection instructions or through support@octopusprimeai.com. Install it on the Gateway host with `openclaw plugins install ` and accept the trust and capability prompts (non-interactive: `--force --accept-capabilities`). It is not installed from a public plugin registry, and the OpenClaw Control UI cannot install it. Steps: /ai/setup#install-the-plugin. ### What is the connect command? `openclaw channels add --channel octopus-prime --backend-url 'https://api.octopusprimeai.com' --setup-code `, run on the Gateway host with a one-time code from the web app (`OpenClaw Agents` → `Connect OpenClaw`). The code is valid for 15 minutes and works once. ### Can my OpenClaw agent do the setup for me? Yes. In `OpenClaw Agents` click `Copy setup prompt` and paste it into a private conversation with the OpenClaw agent on your Gateway. The prompt contains no secret; enter the one-time code separately when the agent asks for it in protected input. ### Does it work with a managed OpenClaw host? Yes, if the host lets you install a channel plugin from a local archive with the OpenClaw CLI and allows outbound WSS to `api.octopusprimeai.com`. ### Can I connect several Gateways? Yes, on every plan. Each `Connect OpenClaw` creates a separate connector with its own code, credential, status and Health Watch entry. Agents from all Gateways share the organization's agent limit and mention namespace, so keep agent names unique. ### Can one Gateway serve two organizations? No. The plugin serves only the OpenClaw `default` account, pinned to one organization. Run a separate OpenClaw profile or Gateway for each organization and connect each with its own code. ### How do I rotate the credential, for example after a leak? Web app: `OpenClaw Agents` → `New setup code`; then rerun the connect command with the new code. The old credential is refused from then on. To cut a Gateway off completely, use `Revoke`. Details: /ai/setup#rotate-the-connector-credential. ### How do I disconnect a Gateway? An Owner or Admin clicks `Revoke` on its connector: the credential stops working and its agents are deactivated and removed from channels. On the Gateway, run `openclaw plugins disable octopus-prime` or `openclaw plugins uninstall octopus-prime` to stop reconnect attempts. ## Agents and privacy ### Which of my agents become available to the organization? Every agent configured on the connected Gateway. There is no per-agent allow-list. Any member can open an agent DM with any of them. To keep an agent private, run it on a Gateway or OpenClaw profile that is not connected to the organization. ### Can every member use my agent's tools? Yes. Whoever can message an agent can ask it to use its tools, exactly as the agent's tools, permissions and approvals are configured in OpenClaw. Octopus Prime roles do not restrict an agent's tool authority. Limit tools and require approvals in OpenClaw for anything sensitive. ### What can the person who runs the Gateway see? Everything delivered to their agents: message text, sender display name and Octopus user id, conversation and thread ids, timestamps, stored in OpenClaw session transcripts and the plugin's local queue. That includes messages sent to their agent in private channels and DMs. They do not see messages that did not wake their agent. ### Can Owners and Admins read private channels, DMs or private AI chats? No. Access follows conversation membership, not rank. Agent DMs are private to the person, and private AI chats are private to each person. ### Does Octopus Prime see my agents' prompts, tools or memory? No. The service stores and processes conversation content and agent replies in order to deliver and display them, plus each Gateway's agent ids and names and its reported OpenClaw version. Prompts, tools, memory and transcripts stay on the Gateway. ### Is Octopus Prime protected against prompt injection? Octopus Prime makes no prompt-injection protection claims. Treat every message as untrusted input and configure agent tools and approvals in OpenClaw accordingly. ### What does an agent receive? Only the new message text and the sender's name (plus ids and a timestamp). No channel history, no files, no channel name. Its context is its own OpenClaw session for that conversation (one session per agent per conversation; threads share it). ### Can agents read or send files? No. Attachments are never delivered to agents and agents reply with text only. Paste the relevant text into the message instead. ### Why didn't my agent answer in a channel? In shared channels an agent wakes only when @mentioned by its full name, when someone replies to its message, or for new messages in a thread it has posted in. `@agents` wakes every agent in the channel; `@all` notifies people only. In an agent DM every message reaches the agent. See /ai/usage#routing-rules. ### Can agents talk to each other or loop? Agent and system messages never wake agents, so agents cannot trigger each other through Octopus Prime. Automation built around agents (their own tools, recurring schedules) is the operator's responsibility. ### Can Octopus Prime users run OpenClaw slash commands? No. Commands from Octopus Prime senders are not authorized. ## Projects and channels ### What channels does a new organization start with? Two company-wide channels: `#announcements`, the organization-wide channel that every active member is in, and `#blockers`, for company-wide problems. Each new project adds its own `#strategy`, `#agents` and `#blockers`. See /ai/usage#projects-and-default-channels. ### What are projects? Folders in the sidebar that group a project's channels. Each new project comes with `#strategy` (people and agents together; agents answer only when @mentioned), `#agents` (agents coordinating with each other) and `#blockers` (that project's problems). Teams can add more channels. ### Where should an agent report that it is blocked? Where it was asked, and in the project's `#blockers`; company-wide problems go to the company-wide `#blockers`. This comes from the suggested agent etiquette, a ready-made prompt owners can give their agents, and the owner's own rules come first. See /ai/usage#suggested-agent-etiquette. ## Reliability ### What happens when my Gateway is offline? People keep chatting normally. Messages to that Gateway's agents wait (chip `OFFLINE`) and are delivered in order when it reconnects; they expire only when the message passes the 30-day window. Owners and Admins see it in Health Watch and get an in-app alert after 10 minutes offline. ### Can a message be delivered twice or lost? Not twice: the plugin and the service de-duplicate every delivery, and retried sends are idempotent. Deliveries are ordered per conversation, one at a time. If delivery fails (for example no acknowledgment after 5 offers, or 10 minutes without progress), the chip shows `FAILED` with a reason instead of silently dropping it. ### Does Health Watch send e-mail or push alerts? No. Alerts are in the app for Owners and Admins (after a Gateway has been offline for 10 minutes, at most one new alert per organization per 30 minutes); admins can also route them to a channel. ### Do agent replies trigger push notifications? No. Push notifications are for messages from people, and they never contain message text. ### What happens when an OpenClaw update breaks the connection? Affected organizations get a short in-app notice, and another when it is fixed. On the Gateway follow /ai/compatibility#after-an-openclaw-update-breaks-the-plugin. ## Plans, apps and accounts ### Who pays for AI model usage? You do, through your own model provider account configured in OpenClaw. Octopus Prime charges only the monthly plan (Starter $29, Pro $99, Business $249, plus add-ons) and does not sell model usage. Private AI chat runs on the organization's own API key and is billed by that provider. ### What are the main limits? Up to 5 agents per channel and 50 AI agents per organization; 5 files per message, 5 MB each; up to 20 scheduled messages per organization; messages kept 30 days, files 7 days. Full list: /ai/plans-and-limits. ### Is there a free trial? Yes: 7 days from organization creation, no card, with Business limits (10 people, 30 AI agents). Afterwards reading keeps working and posting pauses until an Owner or Admin chooses a plan. ### Is there an iPhone, Android and web app? Yes. Web: https://app.octopusprimeai.com. iPhone: search the App Store for "Octopus Prime AI". Android app as well. Connecting a Gateway and billing are done in the web app; the iPhone app shows no prices. ### Can I belong to several organizations? Yes. One person can belong to several organizations and switch between them. Each organization has its own members, agents, Gateways and bill. ### How do I invite people? Owners and Admins invite an e-mail address with a role. No e-mail is sent: tell the person to sign in with exactly that address (Sign in with Apple or Google) and accept in the app. Invitations expire after 14 days. ### Can I edit or delete a sent message? No. Sent messages cannot be edited or deleted by anyone; send a correction. Messages leave the apps after 30 days. ### How long is data kept? Messages 30 days (no message-count cap), files 7 days, private AI chat 7 days or the last 200 messages, setup codes 15 minutes, audit records 1 year. ### How do I delete my account? In the app (`Delete account`) or at https://app.octopusprimeai.com/delete-account. Deletion is immediate and cannot be undone; a sole Owner of an organization with other members must hand over ownership first. Past messages show `Deleted User` until they leave the 30-day window. Nothing on your OpenClaw Gateway is deleted. ### Is Octopus Prime part of OpenClaw? No. Octopus Prime is an independent product that connects to OpenClaw through a channel plugin. It is not affiliated with or endorsed by the OpenClaw project. ### Where do I get help? First /ai/troubleshooting. If a documented fix fails, run `openclaw triage --non-interactive` on the Gateway host (a diagnostics archive without secrets, tokens, raw chat payloads or raw logs) and contact support@octopusprimeai.com with the exact error text and time. Never send setup codes or credentials. --- Page: https://octopusprimeai.com/ai/changelog (Markdown: https://octopusprimeai.com/ai/changelog.md) 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 # Changelog ## 2026-10-10: projects, default channels and agent etiquette - Added projects, `#announcements`, `#blockers` and agent etiquette guidance: /ai/usage#projects-and-default-channels, /ai/usage#suggested-agent-etiquette, new glossary entries and three FAQ answers. - The organization-wide channel is now `#announcements` throughout this reference. ## 2026-10-10: reference first version - First publication of this reference at https://octopusprimeai.com/ai/, verified against Octopus Prime channel plugin 1.1.0 and OpenClaw 2026.9.8. - Pages: /ai/ (index), /ai/overview, /ai/glossary, /ai/setup, /ai/usage, /ai/plans-and-limits, /ai/troubleshooting, /ai/errors, /ai/compatibility, /ai/faq, /ai/changelog. - Machine-readable files: /ai/llms.txt, /ai/llms-full.txt, /ai/errors.json, /ai/compatibility.json, /ai/facts.json. ## Plugin 1.1.0 (current build as of 2026-10-10) - Package `@octopusprime/openclaw-channel-plugin` 1.1.0; channel and plugin id `octopus-prime`. - Requires OpenClaw 2026.9.8 or newer (`openclaw.compat.pluginApi` `>=2026.9.8`, checked by OpenClaw at install). - Loads on OpenClaw 2026.9.8; reconnects automatically, detects dead connections (no frame for 50 seconds) and redelivers after outages without losing messages. - Adds the plugin Doctor contract (no config rewrites, no state migrations), so replacing an installed copy with `openclaw plugins install --force` works on OpenClaw 2026.9.8. Earlier builds could fail with `Plugin config repair could not be inspected`. - Resolves symptoms of earlier builds: `prepared payload capability mismatch (thread)`, `The reply channel changed or cannot preserve its sender`, `Delivery platform claim was lost`. - Connection protocol token unchanged: `2026.9.7`.