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:

Projects are folders in the sidebar. Each new project comes with three channels, and teams can add more:

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

#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:<Octopus user id> 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:

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.

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 #<channel>.
• 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.).

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

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