OpenClaw & Airlock Gateway

Overview

The @airlockapp/openclaw-airlock package adds Airlock Gateway integration to an OpenClaw-compatible agent runtime. It can intercept configured tools before they run, send encrypted approval requests to the Airlock mobile app (Google Play), and verify signed decisions. Pairing uses pre-generated codes and X25519 ECDH; payloads use AES-256-GCM per the HARP model used across Airlock clients.

Prerequisites

OpenClaw — compatible agent runtime with plugin support.
Node.js — 18 or later.
Integrations Gateway — e.g. https://igw.airlocks.io for production.
Airlock account — developer programme approval to create an Agent enforcer app (client ID and secret).
Personal Access Token (PAT) — airpat_… from the platform or mobile app.
Pre-generated pairing code — six characters from the mobile app (expires in about 30 minutes until claimed).

For the developer programme, enforcer apps, and tokens, see the Developer Guide and Airlock Apps.

Install the plugin

From npm (recommended), add the package to your project:

npm install @airlockapp/openclaw-airlock

npm install @airlockapp/openclaw-airlock

From your OpenClaw workspace, install via the OpenClaw CLI:

openclaw plugins install @airlockapp/openclaw-airlock

openclaw plugins install @airlockapp/openclaw-airlock

To build from a clone of airlockapp/gateway-clients:

cd src/openclaw-airlock
npm install
npm run build

cd src/openclaw-airlock
npm install
npm run build

Configure the plugin

Add an airlock entry under OpenClaw plugin config (see openclaw.plugin.json for the schema). Example:

{
  "plugins": {
    "entries": {
      "airlock": {
        "enabled": true,
        "config": {
          "gatewayUrl": "https://igw.airlocks.io",
          "enforcerId": "my-enforcer-001",
          "pat": "airpat_your_token_here",
          "clientId": "YOUR_CLIENT_ID",
          "clientSecret": "YOUR_CLIENT_SECRET",
          "pairingCode": "A3K9X2",
          "workspaceName": "My AI Workspace",
          "failMode": "closed",
          "protectedTools": ["shell.exec", "deploy.run"],
          "timeoutMs": 300000,
          "executionMode": "poll"
        }
      }
    }
  }
}

{
  "plugins": {
    "entries": {
      "airlock": {
        "enabled": true,
        "config": {
          "gatewayUrl": "https://igw.airlocks.io",
          "enforcerId": "my-enforcer-001",
          "pat": "airpat_your_token_here",
          "clientId": "YOUR_CLIENT_ID",
          "clientSecret": "YOUR_CLIENT_SECRET",
          "pairingCode": "A3K9X2",
          "workspaceName": "My AI Workspace",
          "failMode": "closed",
          "protectedTools": ["shell.exec", "deploy.run"],
          "timeoutMs": 300000,
          "executionMode": "poll"
        }
      }
    }
  }
}

Config reference

gatewayUrl (required) — Integrations Gateway base URL.
enforcerId (required) — Stable ID for this OpenClaw instance.
pat — PAT for user identity; required for how the plugin authenticates.
clientId / clientSecret — Agent app credentials from the platform.
pairingCode — Pre-generated code until openclaw airlock pair completes.
workspaceName — Label in the mobile app (default OpenClaw Workspace).
timeoutMs — Approval wait timeout (default 300000).
pollIntervalMs — Decision poll interval, minimum 1000 (default 3000).
failMode — closed blocks on timeout/errors; open allows.
protectedTools — Tool names or globs (e.g. shell.*) gated by the hook; empty means no automatic gating.
executionMode — poll (supported); webhook reserved for future use.

Pair and verify

openclaw airlock setup
openclaw airlock pair

openclaw airlock setup
openclaw airlock pair

setup validates configuration and gateway reachability. pair claims the pre-generated code, completes ECDH, and writes secrets under .airlock/pairing-state.json (gitignored — do not commit). In chat, /airlock-status summarizes connectivity, pairing, and protected tools.

Usage

Hook enforcement

With protectedTools set, matching tool calls are held until the approver decides or timeout. Do Not Disturb policies on the gateway can auto-approve matching requests.

Explicit tools

The agent can call airlock_request_approval for a dedicated approval round-trip and airlock_check_status for a prior request ID.

Fail modes

With failMode: "closed", timeouts and gateway errors block execution; "open" allows through in those cases. Revoked or stale pairing, and quota errors, are blocked regardless of fail mode.

Security notes

E2EE uses X25519 + HKDF and AES-256-GCM; the gateway routes ciphertext only.
Approver decisions can be verified with Ed25519 when signatures are present.
Implementation relies on @airlockapp/gateway-sdk; see TypeScript SDK for the same APIs outside OpenClaw.

Troubleshooting

Not paired — Set a fresh pairingCode and run openclaw airlock pair.
Tools not intercepted — Confirm tool names match protectedTools or use explicit approval tools.
Gateway errors — Run openclaw airlock setup and check URL and network policy.

Full detail, architecture diagram, and development commands are in the package README on GitHub.