scope-openclaw

OpenClaw channel adapter for Scope — chat, task management, and workspace sync.

Install

openclaw plugins install scope-openclaw

Do not install via npm install directly into the extensions folder. Use OpenClaw's plugin installer, which extracts the package into its own directory and wires up the config correctly. Running npm install will place files in node_modules/ which OpenClaw does not scan for plugins.

Plugin ID vs. package name

The npm package is published as scope-openclaw, but the plugin registers under the id scope. This means the config keys in openclaw.json use scope, not scope-openclaw:

• plugins.entries.scope (not scope-openclaw)
• channels.scope (not channels.scope-openclaw)

OpenClaw may show a warning on startup that reads "plugin id mismatch (manifest uses 'scope', entry hints 'scope-openclaw')". This is harmless — the plugin loads and connects correctly. It is a cosmetic warning caused by the npm package name differing from the plugin's registered id.

Docker / self-hosted install

If you are running OpenClaw in Docker (for example via Elestio or a self-hosted docker-compose setup), openclaw plugins install may update your openclaw.json without placing the plugin files on disk. This is a known issue with the npm extraction step in certain Docker environments.

If the plugin fails to load after install, use this manual process instead:

# Run these commands inside the running OpenClaw gateway container
# (or any container that shares the ~/.openclaw volume mount)

cd /tmp
npm pack scope-openclaw@0.5.4

mkdir -p ~/.openclaw/extensions/scope
tar -xzf scope-openclaw-0.5.4.tgz -C /tmp/scope-tmp --strip-components=1
cp -r /tmp/scope-tmp/* ~/.openclaw/extensions/scope/
rm -rf /tmp/scope-tmp /tmp/scope-openclaw-0.5.4.tgz

Since v0.5.4, the plugin bundles all dependencies — no npm install step is needed after extraction.

Then add the plugin to openclaw.json (see Configuration below) and restart the gateway. You can verify the plugin loaded correctly with:

openclaw plugins doctor
# Expected: "No plugin issues detected"

Updating

There is currently no openclaw plugin update command. To upgrade to a new version:

1. Remove the existing plugin directory: rm -rf ~/.openclaw/extensions/scope/
2. Re-run openclaw plugins install scope-openclaw

Your channels.scope config in openclaw.json is preserved across reinstalls.

Uninstalling

openclaw plugins uninstall scope-openclaw will fail if channels.scope still exists in your config (OpenClaw validates the config before completing the removal). To uninstall cleanly:

1. Remove channels.scope from openclaw.json
2. Remove the plugin from plugins.allow, plugins.entries, and plugins.installs in openclaw.json
3. Delete the plugin directory: rm -rf ~/.openclaw/extensions/scope/
4. Restart OpenClaw

Configuration

Configuration is auto-generated in openclaw.json under channels.scope when installed via the plugin installer.

{
  "channels": {
    "scope": {
      "email": "my-agent@example.com",
      "password": "<auto-generated on first run>"
    }
  }
}

On first run the adapter auto-registers with Scope and populates apiKey and agentId.

Multi-Agent Routing

A single Scope account can have multiple agents (e.g. a general-purpose agent and a meeting bot). To route messages from each Scope agent to the correct OpenClaw agent, use the agents array:

{
  "channels": {
    "scope": {
      "email": "my-agent@example.com",
      "password": "...",
      "agents": [
        { "agentId": "2c15d250-...", "openclawAgent": "main" },
        { "agentId": "a8f3e901-...", "openclawAgent": "meetbot" }
      ]
    }
  }
}

Each entry maps a Scope agentId to the openclawAgent name that should handle its messages. The openclawAgent value is used as the AccountId when dispatching to the OpenClaw gateway.

• Messages from unmapped Scope agent IDs are dropped with a warning.
• Workspace file sync uses the first agent in the array as the primary.
• The legacy single agentId field is still supported for backward compatibility — it behaves as a single mapping to openclawAgent: "default".

Options

Features

• Bidirectional chat — WebSocket connection relays messages between OpenClaw agents and Scope
• Task management — List, start, and complete tasks through the adapter
• Workspace sync — Automatically sync local .md files with Scope
• Mechanical handlers — File sync and config sync events are handled without invoking the LLM
• Auto-reconnect — WebSocket reconnects with exponential backoff on disconnect
• Credential recovery — API client automatically re-authenticates on 401 responses
• Zero runtime dependencies — All dependencies are bundled into the dist

Programmatic Usage

import { monitorScopeChannel } from "scope-openclaw";

const controller = await monitorScopeChannel({
  config: {
    email: "agent@example.com",
    password: "secret",
    agents: [
      { agentId: "2c15d250-...", openclawAgent: "main" },
    ],
  },
  agentName: "my-agent",
  callbacks: {
    onChatMessage: (msg, openclawAgent) => {
      console.log(`[${openclawAgent}] ${msg.sender_type}: ${msg.content}`);
      controller.sendMessage("Got it!");
    },
  },
});

// Send a message
controller.sendMessage("Hello from the agent!");

// Access the API client directly
const tasks = await controller.api.listTasks({ assigned_agent_id: "..." });

// Shut down
controller.close();

Development

npm install
npm run build       # Build with tsup (ESM + CJS)
npm run dev         # Watch mode
npm run typecheck   # Type-check without emitting

License

MIT