OpenClaw Webex Plugin

Standalone third-party Webex channel plugin for OpenClaw.

Built on the official webex JavaScript SDK, this plugin runs as a websocket-first Webex bot integration for OpenClaw. It does not require webhook ingress or a public callback URL, which makes local setup and private deployments simpler than channels that depend on externally reachable HTTP endpoints.

For teams already using Webex bots, the setup is also relatively direct: create a bot, copy the bot token, install the plugin, and configure channels.webex. In practice this is often lighter operationally than chat integrations that require separate app manifests, webhook hosting, or public tunnel infrastructure.

AI-First Docs

This repository ships task-oriented docs intended for AI agents that install and configure the plugin.

• Start with docs/runtime-behavior.md.
• Load only the page needed for the current task.
• Use docs/runtime-behavior.md as the primary AI doc for installation, config shape, ready-made snippets, field-by-field config explanations, and runtime semantics.

Install

Install from npm:

openclaw plugins install @nfshanq/webex

Install a local checkout for development:

openclaw plugins install -l /absolute/path/to/openclaw-webex-plugin

For installation details, config shape, target formats, and runtime behavior, use docs/runtime-behavior.md.

Development

Install dependencies:

npm install

Run tests:

npm test

Type-check the plugin:

npm run build

Quick Start

Minimal config:

{
  channels: {
    webex: {
      enabled: true,
      defaultTo: "[email protected]",
      dmPolicy: "allowlist",
      allowFrom: ["[email protected]"],
      groupPolicy: "allowlist",
      requireMention: true,
      groups: {
        "Y2lzY29zcGFyazovL3VzL1JPT00v...": {
          title: "Engineering Chat",
          requireMention: true,
        }
      }
    },
  },
}

Provide the bot token through WEBEX_BOT_TOKEN, or store it in channels.webex.botToken for the default account.

Room config keys under channels.webex.groups must use the exact Webex room ID seen by the runtime. The safest workflow is to resolve or copy the room ID first, then use that value as the map key.

Useful commands:

openclaw channels status --probe
openclaw channels resolve --channel webex --kind user [email protected]
openclaw channels resolve --channel webex --kind group "webex:space:<room-id-or-public-id>"

Features

• Direct realtime runtime built on [email protected]
• Multi-account config resolution with default-account env fallback
• Webex target parsing for webex:user:*, webex:space:*, and email targets
• Outbound text and file delivery through the Webex REST API
• Inbound DM and space normalization, mention gating, pairing gating, attachment action routing, and reply dispatch integration
• Optional receipt reactions and require-mention hinting
• Automated tests for config, targets, API behavior, runtime adapter, and inbound flow

Repository Layout

• index.ts registers the plugin with OpenClaw.
• docs/ contains AI-oriented install, config, and behavior docs.
• src/ contains channel implementation, runtime adapters, API helpers, and config handling.
• test/ contains unit and integration coverage.
• openclaw.plugin.json provides plugin discovery and config validation metadata.

Publishing Notes

• npm package name: @nfshanq/webex
• Repository: https://github.com/nfshanq/openclaw-webex-plugin