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:

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

Agent tools

This plugin registers one agent tool, octo_management, covering all Octo management actions: listing groups, reading/updating GROUP.md and THREAD.md, managing threads and members, voice-correction context, and write-secret (writing a user's stored API key into a local file by alias, without ever exposing the plaintext to the model).

octo_management is a plugin tool, 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, octo_management is filtered out and every action it provides — creating groups, threads, GROUP.md edits, and write-secret — becomes unavailable at once (the agent simply does not see the tool).

This matters because a fresh OpenClaw install defaults tools.profile to coding, not full — so out of the box, an Octo bot cannot use any octo_management action until the tool is allowed.

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

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

For a single agent, use agents.list[].tools.alsoAllow: ["octo_management"].

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

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.