name: openclaw-setup description: >- This skill should be used when the user asks to "install openclaw", "set up openclaw", "configure openclaw", "openclaw with telegram", "openclaw with slack", "openclaw with lark", "connect lark to openclaw", "openclaw launchagent", "openclaw lark webhook bridge", "reinstall openclaw", "openclaw multi-channel setup", or mentions setting up an AI assistant gateway with messaging channel integrations. Provides automated setup for OpenClaw with Telegram, Slack, and Lark (International) channels on macOS, including gateway daemon configuration, channel credential provisioning, and the Lark webhook bridge. version: 1.0.0

OpenClaw Multi-Channel Setup

Automated installation and configuration of OpenClaw gateway with Telegram, Slack, and Lark (International) channel integrations on macOS.

Architecture Overview

Telegram ──polling──────────────────────► OpenClaw Gateway (:18789)
Slack    ──socket-mode──────────────────►       │
Lark App ──webhook──► Bridge (:3000) ──ws──►    │
                        ▲                       ▼
                      ngrok              Anthropic Claude API
                                                │
Feishu plugin ──wiki/docs API──────────────────►│

• Telegram: Polling mode — no public endpoint needed
• Slack: Socket mode — no public endpoint needed
• Lark International: HTTP webhook via standalone Node.js bridge — requires public endpoint (ngrok for dev)

Lark International (larksuite.com) does NOT support WebSocket for event subscriptions. Only HTTP webhook delivery works. The bridge receives webhooks and forwards to the gateway over a local WebSocket connection. The Lark SDK domain must be Lark.Domain.Lark (not Lark.Domain.Feishu).

Dual setup: The built-in feishu channel plugin is enabled with the same app credentials (channels.feishu.enabled: true) to provide wiki and docs API access. The standalone bridge handles all messaging. Both use the same Lark app.

Prerequisites

• macOS with Homebrew
• Node.js >= 18
• ngrok (for Lark only, unless a public IP is available)
• Credentials: Anthropic API key, plus tokens for each channel

Setup Workflow

Step 1: Install OpenClaw

brew install openclaw
openclaw onboard --mode local

This creates ~/.openclaw/ with default configuration.

Step 2: Run the Setup Script

Execute scripts/setup.sh from this skill's directory. It supports full or per-channel setup:

./scripts/setup.sh              # Full interactive setup
./scripts/setup.sh gateway      # Gateway + LaunchAgent only
./scripts/setup.sh telegram     # Telegram channel
./scripts/setup.sh slack        # Slack channel
./scripts/setup.sh lark         # Lark webhook bridge

The script prompts for all credentials at runtime — no secrets are stored in the skill.

Step 3: Post-Setup

After running the script:

1. Restart gateway: launchctl kickstart -k gui/$(id -u)/ai.openclaw.gateway
2. For Lark: start ngrok (ngrok http 3000), set Request URL in Lark console
3. Start Lark bridge: ~/.openclaw/skills/lark-integration/scripts/start.sh
4. DM each bot, then approve pairing in OpenClaw Control UI (openclaw control-ui)

Key Configuration Details

Gateway Auth Token

The gateway uses token-based auth on port 18789 (loopback only). The token is auto-generated during onboard and stored in ~/.openclaw/openclaw.json at gateway.auth.token. The same token is injected into the LaunchAgent plist.

Anthropic API Key

The gateway reads ANTHROPIC_API_KEY from the environment. The setup script injects it into the LaunchAgent plist at ~/Library/LaunchAgents/ai.openclaw.gateway.plist.

Lark Bridge — Gateway Scope Workaround

The gateway clears all operator scopes for WebSocket connections without device identity (clearUnboundScopes() in gateway source). The Lark bridge is a headless backend with no device identity, so its scopes get stripped — causing missing scope: operator.write when calling the agent method.

Workaround (applied by setup script):

1. Set gateway.controlUi.dangerouslyDisableDeviceAuth: true in openclaw.json
2. Bridge connects with client.id: 'openclaw-control-ui'
3. Bridge sets Origin: http://127.0.0.1:{port} header on WebSocket

This preserves operator.write scope through the control-UI bypass path. See references/architecture.md for full technical explanation.

File Locations After Setup

| File | Purpose | |------|---------| | ~/.openclaw/openclaw.json | Main config (channels, gateway, plugins) | | ~/.openclaw/secrets/feishu_app_secret | Lark app secret (chmod 600) | | ~/.openclaw/workspace/.env | FEISHU_APP_ID env var | | ~/Library/LaunchAgents/ai.openclaw.gateway.plist | Gateway daemon | | ~/.openclaw/skills/lark-integration/scripts/ | Lark bridge + start.sh | | ~/.openclaw/logs/gateway.log | Gateway stdout log |

Firewall Requirements

Outbound access required on port 443:

• api.telegram.org (Telegram)
• wss-primary.slack.com (Slack)
• open.larksuite.com (Lark API)
• api.anthropic.com (Claude API)

Bundled Resources

Scripts

• scripts/setup.sh — Main interactive setup script (full or per-channel)
• scripts/bridge-webhook.mjs — Lark webhook-to-gateway bridge
• scripts/package.json — Bridge npm dependencies

References

• references/architecture.md — Gateway auth internals, scope workaround details, troubleshooting
• references/channel-setup.md — Per-channel credential creation walkthroughs (Telegram BotFather, Slack App Console, Lark Developer Console)

Asset Templates

• assets/templates/openclaw.json — Config template with placeholders
• assets/templates/ai.openclaw.gateway.plist — LaunchAgent template with placeholders