openclaw-channel-octo

OpenClaw channel plugin for Octo. Connects via WebSocket for real-time messaging.

Prerequisites

• Node.js >= 22 (OpenClaw >= 2026.4.15 requires Node 22)
• OpenClaw installed and configured (npm i -g openclaw)
• A bot created via BotFather in Octo (send /newbot to BotFather)

Install

This plugin is published exclusively on ClawHub for fresh installs:

openclaw plugins install clawhub:octo

Configure a bot account

After installing, use OpenClaw's standard channels add flow.

Non-interactive (recommended for scripts and CI):

openclaw channels add --channel octo \
  --account my_bot \
  --bot-token bf_your_token_here \
  --http-url https://your-server.example/api

Interactive (prompts for token and API URL):

openclaw channels add

After the account is written, restart the gateway (openclaw gateway run --force) or wait for the next auto-reload — the plugin watches channels.octo and reconnects on changes.

Configuration

Bot accounts are stored in ~/.openclaw/openclaw.json under channels.octo.accounts:

{
  "channels": {
    "octo": {
      "enabled": true,
      "accounts": {
        "my_bot": {
          "enabled": true,
          "botToken": "bf_your_token_here",
          "apiUrl": "https://your-server.example/api"
        }
      }
    }
  }
}

Configuration fields per account:

cardProgress, cardDisplay, and cardInteraction may also be set directly under channels.octo as defaults for every account. An explicit per-account true or false overrides the corresponding top-level value.

• botToken (required): Bot token. Either a User Bot token from BotFather (bf_ prefix, full group + thread access) or an App Bot token from the Octo admin console (app_ prefix, direct-message only — server-enforced).
• apiUrl (required): Octo server REST API base URL (e.g. https://your-server/api). The default http://localhost:8090/api only works for a local Octo dev server with the standard /api mount.
• wsUrl (optional): WebSocket URL. Auto-detected from apiUrl if omitted.
• cdnUrl (optional): CDN base URL for media files
• requireMention (optional): Only respond when @mentioned in groups
• pollIntervalMs (optional): Short-poll interval for card_action callbacks after this account sends an interactive card (default 2000, minimum 500).
• cardProgress (optional): Set false to force-disable automatic progress cards for this account. Omitted or true follows the server card capability gate.
• cardDisplay (optional): Set false to hide and reject the octo_send_display_card tool for this account. Omitted or true follows the server card capability gate.
• cardInteraction (optional): Set false to hide octo_send_card and prevent new interactive-card callback polling for this account. Omitted or true follows the server octo/v2 capability gate.
• historyLimit (optional): Group chat history message limit (default: 20)
• dispatchTimeoutMs (optional): Per-inbound dispatch timeout in milliseconds — an infrastructure backstop that releases the per-group message queue if an upstream dispatch hangs. When unset, it is derived from OpenClaw's agents.defaults.timeoutSeconds (600 if unset) as timeoutSeconds * 1000 + 60000, so it always fires after the agent-run timeout: the agent terminates gracefully first, and this timeout only catches genuinely hung dispatches. Set explicitly only if you need to decouple it from the agent timeout.

For example, to suppress intermediate progress frames while keeping final display cards available:

{
  "channels": {
    "octo": {
      "accounts": {
        "my_bot": {
          "cardProgress": false,
          "cardDisplay": true,
          "cardInteraction": true
        }
      }
    }
  }
}

Agent tools

This plugin registers three agent tools:

• octo_management covers group/thread/member management, GROUP.md and THREAD.md, voice-correction context, and write-secret.
• octo_send_display_card sends structured, non-callback octo/v1 cards to the current trusted Octo conversation.
• octo_send_card sends octo/v2 confirmation, menu, or short-form cards. Controlled section/options blocks produce structured body sections and Input.ChoiceSet choices instead of one dense text paragraph. A submit click is polled from /v1/bot/events, preserves the original card body while showing the selected result, and continues the same conversation as a new agent turn. Unsupported deployments receive the choices as plain text.

These are plugin tools, and OpenClaw's tools.profile presets (minimal, coding, messaging, full) decide which tools the model sees before it sees them. Only full (allow: ["*"]) admits plugin tools; the three restrictive presets exclude plugin tools by default. So under minimal, coding, or messaging, they are filtered out unless explicitly allowed.

This matters because a fresh OpenClaw install defaults tools.profile to coding, not full — so out of the box an Octo bot cannot use management, display-card, or interactive-card tools until they are allowed.

To keep the Octo tools available under a restricted profile, add them via tools.alsoAllow (additive on top of the profile, the same way the bundled browser tool is enabled):

{
  tools: {
    profile: "coding",
    alsoAllow: ["octo_management", "octo_send_display_card", "octo_send_card"],
  },
}

For a single agent, use the same names under agents.list[].tools.alsoAllow.

When octo_management is filtered out, the plugin injects a short system-prompt note so the agent attributes the gap correctly (a tools-profile restriction, not a missing Octo feature) instead of suggesting another platform or asking the user to paste a secret in plaintext. Whether to adjust the configuration is up to you.

Security note: write-secret exists precisely so users never have to paste a plaintext key into chat. If the tool is unavailable because of the profile, enable octo_management as above — do not work around it by pasting the secret in plaintext.

What it does

1. Registers the bot with the Octo server via REST API
2. Connects to WebSocket for real-time message receiving
3. Auto-reconnects on disconnection
4. Sends a greeting to the bot owner on connect
5. Dispatches incoming messages to OpenClaw's message handler
6. Supports typing indicators and read receipts
7. Sends display and submit-interactive cards with negotiated fallback
8. Polls durable card_action events only after an interactive card is sent

Architecture

index.ts is a standard OpenClaw plugin entry. When loaded:

• api.registerChannel(octoPlugin) registers the Octo channel runtime
• The bundled setupEntry exposes defineBundledChannelSetupEntry(...) so openclaw channels add works without first enabling the plugin
• setupWizard + setup adapters on octoPlugin cover both interactive and CLI-flag setup paths
• Configuration is read from channels.octo in OpenClaw's config; the plugin hot-reloads when that block changes

Disconnect

To disconnect a bot, send /disconnect to BotFather in Octo. This invalidates the IM token and kicks the WebSocket connection.