@ihazz/bitrix24

OpenClaw channel plugin for Bitrix24 Messenger based on Bot Platform 2.0 (imbot.v2.* / im.v2.*).

This is the official, Bitrix24-certified OpenClaw plugin for Bitrix24 Messenger.

Providers

The plugin supports two providers for connecting to Bitrix24:

| Provider | Description | Recommended | |---|---|---| | VibeCode | Connects through the VibeCode Bot API proxy. Simpler setup, no webhook URL management. | Yes | | Native REST | Connects directly to Bitrix24 REST API via an inbound webhook. Full control, requires webhook URL and scopes. | For advanced use cases |

VibeCode (recommended)

VibeCode is the recommended provider for most deployments. It requires only an API key obtained from the VibeCode developer portal. No inbound webhook setup is needed.

Native REST

The native provider connects directly to Bitrix24 REST API using an inbound webhook URL. Use this when you need full control over API scopes or are running in an environment that cannot reach the VibeCode proxy.

Installation

openclaw plugins install @ihazz/bitrix24

Allow the plugin in openclaw.json:

{
  "plugins": {
    "allow": ["bitrix24"]
  }
}

Configuration

VibeCode provider (recommended)

{
  "channels": {
    "bitrix24": {
      "provider": "vibecode",
      "providerConfig": {
        "apiKey": "your-vibecode-api-key"
      }
    }
  }
}

Native REST provider

{
  "channels": {
    "bitrix24": {
      "provider": "native",
      "providerConfig": {
        "webhookUrl": "https://your-portal.bitrix24.com/rest/1/abc123xyz456/"
      }
    }
  }
}

The botToken is auto-derived from md5(webhookUrl). Set it explicitly in providerConfig.botToken only if your webhook URL may change and you want to preserve bot identity.

SecretRef for production secrets

In production, avoid placing raw API keys or webhook URLs in config files. Use a SecretRef to reference environment variables:

{
  "channels": {
    "bitrix24": {
      "provider": "vibecode",
      "providerConfig": {
        "apiKey": { "source": "env", "id": "B24_VIBE_API_KEY" }
      }
    }
  }
}

A SecretRef object has source (currently only "env") and id (the environment variable name). The plugin resolves the value at startup.

Multi-account configuration

Multiple accounts can run within a single OpenClaw instance. This is useful for testing different providers side-by-side on the same Bitrix24 portal or for running multiple bots with different roles.

The root-level config defines the primary account. Additional accounts go into the accounts block and inherit root-level defaults (they can override any setting):

{
  "channels": {
    "bitrix24": {
      "provider": "vibecode",
      "providerConfig": {
        "apiKey": "your-vibecode-api-key"
      },
      "botName": "Main Bot",
      "agentMode": true,
      "accounts": {
        "native": {
          "provider": "native",
          "providerConfig": {
            "webhookUrl": "https://your-portal.bitrix24.com/rest/1/abc123/"
          },
          "botName": "Native Bot",
          "agentMode": false
        }
      }
    }
  }
}

Important: Agent Mode is portal-wide. When using multiple accounts on the same Bitrix24 portal, enable agentMode on only one account. The user event subscription is shared at the portal level — if one account subscribes and another unsubscribes, the subscription will be revoked for both.

Recommendation: For production with different Bitrix24 portals, use a separate OpenClaw installation per portal. Multi-account in a single instance shares the LLM workspace, session history, and file storage between accounts, which may lead to unintended cross-talk. Separate installations provide full isolation.

Configuration Options

| Parameter | Default | Description | |---|---|---| | provider | "native" | Provider to use: "vibecode" or "native". | | providerConfig | -- | Provider-specific credentials. For vibecode: { apiKey }. For native: { webhookUrl, botToken? }. | | botName | "OpenClaw" | Bot display name. | | botCode | auto | Optional explicit bot code. If omitted, the plugin registers the bot as openclaw_<webhookUserId> and falls back to _2, _3, etc. | | botAvatar | -- | Optional base64 avatar override. | | allowFrom | -- | Sender allowlist for dmPolicy: "allowlist" and as an approved-sender source for pairing/group overrides. | | dmPolicy | "keyOwner" | Direct-message access policy: keyOwner, pairing, allowlist, open. | | groupPolicy | "keyOwner" | Group-chat access policy: disabled, keyOwner, pairing, allowlist, open. | | groupAllowFrom | -- | Allowlist for group chats themselves. Values may be dialogId like "chat208" or numeric chatId like "208". | | requireMention | true | When true, the bot answers in groups only when mentioned. Group messages are still added to RAM history. | | historyLimit | 100 | Maximum number of RAM history entries kept per conversation. | | groups | -- | Per-group overrides keyed by dialogId, numeric chatId, or "*". Each override may set groupPolicy, requireMention, allowFrom, and watch. | | showTyping | true | Sends typing indicator before response. | | enabled | true | Enables or disables the account. | | agentMode | false | Enables combined polling with user-visible events and stores them in RAM history. Requires im scope for native provider. | | agentWatch | -- | Watch rules for user-visible events captured through agentMode. | | pollingIntervalMs | 3000 | Base poll interval for fetch mode. | | pollingFastIntervalMs | 100 | Fast follow-up poll interval when more events are pending. | | verboseLog | false | Enables detailed info and debug logs for development. | | urlRewriteMap | -- | Origin rewrite map for file download URLs. Keys are source origins (e.g. "https://internal.host"), values are replacement origins. Useful when Bitrix24 returns hostnames unreachable from the bot server. |

Vibe Platform access (curl-based)

The plugin gives the LLM direct access to Bitrix24 REST data through the Vibe Platform /v1/* proxy without registering a custom tool. At plugin register time, credentials from the default account's providerConfig.apiKey and providerConfig.baseUrl are exported into the host process environment as VIBE_KEY and VIBE_BASE_URL (matching the canonical naming used in the public VibeCode docs). The bundled vibe-platform skill then teaches the agent to make calls with the runtime's standard exec tool and curl:

BASE="${VIBE_BASE_URL:-https://vibecode.bitrix24.tech/v1}"
curl -sS --max-time 30 -H "X-Api-Key: $VIBE_KEY" "$BASE/guide"

Requirements

• provider: "vibecode" with a valid providerConfig.apiKey on the default account. If the account is not configured or uses a different provider, no env vars are injected and the skill cannot run.
• An OpenClaw runtime that exposes an exec-style tool to the agent (the standard config). The plugin does not register any tool of its own for /v1/* access.

Confirmation discipline (writes & batch)

The runtime no longer enforces a confirmation gate for write methods. The vibe-platform skill (skills/vibe-platform/SKILL.md) Rule 3 makes confirmation a soft rule: before running curl with POST / PATCH / PUT / DELETE, or before any /v1/batch call, the agent must show the user a one-sentence business-language preview, wait for explicit yes/no, and only then execute.

Multi-account

The auto-injection covers only the default account. For multi-account setups, declare per-skill envs explicitly:

{
  "skills": {
    "entries": {
      "vibe-platform": {
        "env": {
          "VIBE_KEY": "vibe_api_...",
          "VIBE_BASE_URL": "https://vibecode.bitrix24.tech/v1"
        }
      }
    }
  }
}

Bundled skills

Two skills ship with this package:

• skills/bitrix24/ — developer-facing reference for the channel itself.
• skills/vibe-platform/ — end-user LLM behaviour for Bitrix24 data workflows: discovery via /v1/guide, common entity recipes, the confirmation-before-write rule, and the canonical curl shape.

The end-user skill replaces the standalone rsv-bitrix24-skill ClawHub package, which is now frozen.

Access Policies

Direct Messages

• keyOwner (recommended): only the key owner (webhook user or VibeCode API key owner) may talk to the bot
• pairing: user must be approved through the OpenClaw pairing flow
• allowlist: user must be present in allowFrom
• open: any direct-message sender is allowed

Group Chats

• disabled: bot sends a short notice and leaves the chat
• keyOwner (recommended): only the key owner may use the bot in that group
• pairing: sender must be approved; the public group receives only a short notice and never a pairing code
• allowlist: sender must be allowed by merged allowFrom and per-group groups.<key>.allowFrom
• open: any sender in the allowed group may use the bot

groupAllowFrom controls whether the group itself is allowed at all. A matching explicit entry in groups also enables that group even if the top-level groupAllowFrom is set to a different list.

Group Message Memory

All delivered group messages are added to RAM history, even when the sender is not allowed to use the bot or when requireMention: true prevents an answer. RAM-backed context and cross-chat lookup still see the delivered group history regardless of reply rules.

Group Watches

Per-group watch rules let the bot react to a specific user and only on selected topics:

{
  "groups": {
    "chat615": {
      "watch": [
        { "userId": "77", "topics": ["secret", "contract"], "mode": "reply" }
      ]
    }
  }
}

• mode: "reply" answers in the group even if the normal group policy would otherwise require a mention
• mode: "notifyOwnerDm" sends the key owner a DM notice with a deep link, then tries a native forward and falls back to a quoted copy
• groups["*"].watch applies to every allowed group chat as a fallback

Bitrix24 Setup (VibeCode Provider)

1. Go to vibecode.bitrix24.tech
2. Sign in with your Bitrix24 account
3. Click Create Bot
4. Fill in the bot details:
   • Name -- display name for your bot in Bitrix24 Messenger
   • Portal -- select the Bitrix24 portal where the bot will be installed
5. After creation, copy the API Key from the bot settings page
6. Add the API key to your OpenClaw config:

{
  "channels": {
    "bitrix24": {
      "provider": "vibecode",
      "providerConfig": {
        "apiKey": "your-api-key-here"
      }
    }
  }
}

For production, use a SecretRef instead of a plain key (see SecretRef above).

The VibeCode portal also shows bot activity logs and lets you manage installed bots across portals.

Bitrix24 Setup (Native Provider)

Create an inbound webhook in Bitrix24:

1. Open Apps > Developer resources > Other > Inbound webhook
2. Create a webhook for your OpenClaw bot
3. Grant scopes:
   • imbot for normal bot operation
   • im if you enable agentMode
   • add any extra scopes required by your Bitrix24 scenario
4. Save the webhook and copy the URL

The webhook URL contains credentials. Do not publish it or commit it to a repository.

Agent Mode

When agentMode: true is enabled, the plugin:

• subscribes the key owner to im.v2 event recording
• polls events with withUserEvents: true
• receives both normal bot events and additional user-visible message events
• stores those additional user-visible messages in RAM history
• never answers user-visible events directly as the bot

Combined with agentWatch rules, this enables the bot to monitor group chats for specific topics and notify the owner or respond when relevant messages appear.

Inline Buttons

Add inlineButtons to channel capabilities:

{ "capabilities": ["inlineButtons"] }

The plugin supports native Bitrix24 keyboard payload via channelData.bitrix24.keyboard and generic OpenClaw button rows via channelData.telegram.buttons (auto-converted). Markdown action links (send:, put:, tel:, user:, chat:, context:, timestamp:) are converted to native Bitrix24 BBCode.

Rich Attachments

For Bitrix24 rich ATTACH blocks, pass a native payload through channelData.bitrix24.attach or channelData.bitrix24.attachments. This is separate from normal file upload via mediaUrl / mediaUrls.

Verification

1. Start OpenClaw with the plugin enabled.
2. Open a direct chat with the bot in Bitrix24 and send a message.
3. Verify the bot shows typing and returns a response.
4. If dmPolicy is keyOwner, verify that only the key owner can use direct messages.
5. Add the bot to an allowed group and mention it.
6. Verify the bot answers when mentioned and stays silent when requireMention: true and no mention is present.

Local development checks:

npm test
npm run build

Troubleshooting

• If the bot leaves a group immediately, check groupPolicy, groupAllowFrom and groups.
• If the bot stays in the group but does not answer, check requireMention.
• If the bot does not answer a user in group chat, check groupPolicy, allowFrom, and per-group overrides.
• If agentMode is enabled but user-visible events never appear, verify the webhook has the im scope (native provider).
• If file transfer fails, verify file size and that local uploads come from the OpenClaw workspace or managed media directory. If downloads fail with an unreachable host, add a urlRewriteMap entry to rewrite the origin.
• If using multi-account with agentMode, ensure only one account has it enabled per portal.

Compatibility

| OpenClaw Version | Status | |---|---| | v2026.4.1 | ✅ Recommended — fully tested, all features working | | v2026.4.5 | ⚠️ Known issues — plugin skills not resolved from extensions directory, bot may fail to respond to messages |

Use OpenClaw v2026.4.1 until the skill resolution issue in v2026.4.5 is fixed.

Development

npm install
npm test
npm run build

License

MIT