npm package: @nfshanq/webex
Description: Standalone Webex channel plugin for OpenClaw
Latest version: 0.1.0

# 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`](./docs/runtime-behavior.md).
- Load only the page needed for the current task.
- Use [`docs/runtime-behavior.md`](./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:

```bash
openclaw plugins install @nfshanq/webex
```

Install a local checkout for development:

```bash
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`](./docs/runtime-behavior.md).

## Development

Install dependencies:

```bash
npm install
```

Run tests:

```bash
npm test
```

Type-check the plugin:

```bash
npm run build
```

## Quick Start

Minimal config:

```json5
{
  channels: {
    webex: {
      enabled: true,
      defaultTo: "someone@example.com",
      dmPolicy: "allowlist",
      allowFrom: ["someone@example.com"],
      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:

```bash
openclaw channels status --probe
openclaw channels resolve --channel webex --kind user someone@example.com
openclaw channels resolve --channel webex --kind group "webex:space:<room-id-or-public-id>"
```

## Features

- Direct realtime runtime built on `webex@3.11.x`
- 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`