OpenClaw Integration

Connect Sigilum to OpenClaw agents with one command

OpenClaw Integration

Sigilum integrates with OpenClaw through hooks, skills, and a one-command installer that enables auditable, claim-gated API access for your AI agents.

Quick Start

Install Sigilum OpenClaw integration with a single command:

./sigilum openclaw install

The installer will prompt for:

• Namespace: Your Sigilum account identifier
• OpenClaw home: Path to .openclaw directory (default: ~/.openclaw)
• API URL: Sigilum API endpoint (default: https://api.sigilum.id)

1. Install integration

   Run the installer from your Sigilum source directory:

   ./sigilum openclaw install
   

   For local development with OSS mode:

   ./sigilum openclaw install --mode oss-local --api-url http://127.0.0.1:8787
   
2. Verify installation

   Check that hooks and skills were installed successfully:

   ./sigilum openclaw status
   
3. Configure provider access

   Add provider connections through the Sigilum gateway (see Provider Connectors).

What Gets Installed

The installer configures three main components:

1. Hooks

sigilum-plugin Hook

Bootstraps Sigilum identity and context for each OpenClaw agent.

What it does:

• Creates one Ed25519 keypair per agent ID under ~/.openclaw/.sigilum/keys/
• Injects gateway-first policy into agent context
• Lists active sigilum-secure-* gateway connections
• Captures sender identity hints for automatic sigilum-subject resolution
• Writes runtime credential discovery report

Events: gateway:startup, command:new, config:reload, message:received

Required environment:

• SIGILUM_NAMESPACE - Your Sigilum namespace

Optional environment:

• SIGILUM_GATEWAY_URL - Gateway base URL (default: http://localhost:38100)
• SIGILUM_API_URL - API base URL
• SIGILUM_KEY_ROOT - Agent key storage path
• SIGILUM_AUTO_BOOTSTRAP_AGENTS - Auto-create agent keys (default: true)

sigilum-authz-notify Hook

This hook is disabled by default and requires namespace owner credentials.

Optional notification hook for pending authorization requests.

What it does:

• Polls for pending authorization requests
• Sends in-channel reminders to operators

Security model:

• Requires SIGILUM_OWNER_TOKEN (namespace owner JWT)
• Only enable if you want to store owner credentials in OpenClaw runtime

Enable with explicit flag:

./sigilum openclaw install \
  --enable-authz-notify true \
  --owner-token '<namespace-owner-jwt>'

2. Skill

sigilum Skill

Gateway-first provider access workflow.

Default behavior:

• Checks sigilum-secure-* gateway connections first for all provider access
• Uses signed /mcp/{connection_id}/tools checks with per-agent key material
• Auto-resolves sigilum-subject from channel sender identity
• Treats 401/403 as authorization-required (not errors)
• Avoids asking for direct provider API keys unless gateway path fails

Gateway-first policy:

When an agent needs to access a provider (e.g., Linear, Slack, OpenAI):

1. Check if sigilum-secure-<provider> connection exists
2. Run signed capability check via gateway helper
3. Parse response:
   • 200 → Access granted, use gateway endpoint
   • 401/403 → Approval required, show user approval instructions
   • 404 → Connection not configured, guide user to add it
   • Other → Surface error and remediation

Helper commands:

# Check available tools for a connection
"${HELPER}" tools "sigilum-secure-linear" "${GATEWAY_URL}"

# Call an MCP tool
"${HELPER}" call "sigilum-secure-linear" "searchIssues" '{"query":"bug"}' "${GATEWAY_URL}"

# Make HTTP proxy request
"${HELPER}" proxy "sigilum-secure-slack" "POST" "/chat.postMessage" '{"channel":"..."}' "${GATEWAY_URL}"

3. Bundled Runtime

The installer bundles a lean Sigilum runtime to:

• <agent-workspace>/.sigilum/runtime (preferred)
• <openclaw-home>/skills/sigilum/runtime (fallback)

This includes:

• sigilum launcher binary
• Command scripts for gateway operations

Installation Modes

Managed Mode (Default)

Connects to hosted Sigilum API and dashboard.

./sigilum openclaw install --mode managed

Defaults:

• API: https://api.sigilum.id
• Gateway: http://localhost:38100 (runs locally)
• Dashboard: https://sigilum.id

After installation:

1. Navigate to https://sigilum.id
2. Sign in and reserve your namespace
3. Register a passkey for secure access

OSS-Local Mode

Runs full Sigilum stack locally from source.

./sigilum openclaw install --mode oss-local --api-url http://127.0.0.1:8787

Requires:

• Full Sigilum source checkout with apps/api directory
• Local Wrangler setup for Cloudflare Workers

Defaults:

• API: http://127.0.0.1:8787 (runs locally via Wrangler)
• Gateway: http://localhost:38100 (runs locally)

Auto-start behavior:

With --auto-start-sigilum=true (default), the installer will:

• Check if local API/gateway are already running
• Start them automatically if needed
• Wait for health checks to pass
• Log output to ~/.openclaw/logs/sigilum-up-<timestamp>.log

Passkey setup for seeded namespace:

1. Get your JWT token

   The installer auto-issues a namespace owner JWT and saves it to:

   ~/.openclaw/.sigilum/owner-token-<namespace>.jwt
   
2. Open passkey setup URL

   Navigate to the passkey setup URL shown in installer output:

   http://localhost:5173/bootstrap/passkey?namespace=<your-namespace>
   
3. Register passkey

   Paste your JWT token and register a passkey, then sign in.

Installer Options

Full command reference:

./openclaw/install-openclaw-sigilum.sh [options]

Core Options

• --openclaw-home PATH - OpenClaw installation directory (default: ~/.openclaw)
• --mode MODE - Installation mode: managed or oss-local
• --namespace VALUE - Your Sigilum namespace (default: $USER)
• --gateway-url URL - Gateway endpoint (default: http://localhost:38100)
• --api-url URL - API endpoint (default: https://api.sigilum.id)

Advanced Options

• --key-root PATH - Agent key storage path (default: ~/.openclaw/.sigilum/keys)
• --runtime-root PATH - Bundled runtime destination
• --enable-authz-notify BOOL - Enable authorization notification hook (default: false)
• --owner-token TOKEN - Namespace owner JWT (required if --enable-authz-notify)
• --auto-owner-token BOOL - Auto-issue JWT in oss-local mode (default: true)
• --auto-start-sigilum BOOL - Auto-start local stack (default: true)
• --interactive / --non-interactive - Control prompt behavior
• --force - Replace existing hooks/skills without backup
• --restart - Restart OpenClaw after installation

Uninstall

Remove Sigilum integration cleanly:

./sigilum openclaw uninstall

This removes:

• Sigilum hooks from ~/.openclaw/hooks/
• Sigilum skills from ~/.openclaw/skills/
• Workspace .sigilum runtime folder
• Agent key material from ~/.openclaw/.sigilum/keys/
• Sigilum entries from openclaw.json (with timestamped backup)
• CLI defaults from ~/.sigilum/config.env

Configuration Files

The installer modifies openclaw.json to enable hooks and skills:

{
  "hooks": {
    "internal": {
      "enabled": true,
      "entries": {
        "sigilum-plugin": {
          "enabled": true,
          "env": {
            "SIGILUM_NAMESPACE": "your-namespace",
            "SIGILUM_GATEWAY_URL": "http://localhost:38100",
            "SIGILUM_KEY_ROOT": "/Users/you/.openclaw/.sigilum/keys"
          }
        }
      }
    }
  },
  "skills": {
    "internal": {
      "enabled": true,
      "entries": {
        "sigilum": {
          "enabled": true,
          "env": {
            "SIGILUM_NAMESPACE": "your-namespace",
            "SIGILUM_GATEWAY_URL": "http://localhost:38100"
          }
        }
      }
    }
  }
}

Each install creates a timestamped backup:

openclaw.json.bak.<timestamp>

Key Management

Agent Keys

Each OpenClaw agent gets a unique Ed25519 keypair:

~/.openclaw/.sigilum/keys/
  <agent-id>/
    <fingerprint>.key  (mode 0600)
    <fingerprint>.pub

Key properties:

• Generated deterministically per agent ID
• Private keys never leave the OpenClaw runtime
• Used for signing all gateway requests
• Each agent’s claims are tracked separately

Key Custody

Important security boundaries:

• Agent signing keys: Stay in OpenClaw runtime
• Provider API credentials: Stay in Sigilum gateway (local BadgerDB)
• Channel credentials (Slack, Discord, etc.): Still required in OpenClaw for v1

Provider credentials:

• Moved to gateway via connector configuration
• Never sent to OpenClaw agents
• Injected by gateway before upstream forwarding

Channel credentials:

• Cannot be fully removed from OpenClaw in v1
• Core channel adapters need tokens for WebSocket/bootstrap flows
• Future: Dedicated channel adapter plugins that proxy through gateway

Subject Resolution

The sigilum-plugin hook captures sender identity hints for automatic sigilum-subject resolution:

Slack channels:

• Hook captures Slack user ID from message:received events
• Subject resolver attempts users.info email lookup (requires SLACK_BOT_TOKEN with users:read scope)
• Falls back to Slack user ID if email unavailable

Other channels:

• Uses channel-specific sender identifier
• Stored in ~/.openclaw/.sigilum/subject-hints.json

Manual override:

Set explicit subject for testing:

export SIGILUM_SUBJECT="[e-mail]"

Approval Flow

When an agent attempts to access a provider without approval:

1. Gateway returns 401 or 403 with AUTH_CLAIM_REQUIRED
2. Helper script parses response and extracts approval fields:
   • APPROVAL_REQUIRED=true
   • APPROVAL_NAMESPACE=<namespace>
   • APPROVAL_AGENT_ID=<agent-id>
   • APPROVAL_PUBLIC_KEY=<ed25519:...>
   • APPROVAL_SERVICE=<connection-id>
3. Agent shows user the approval instructions
4. User approves via dashboard
5. Agent retries request → Gateway allows access

Never infer “gateway restart bug” from 401/403 responses. These are expected authorization states managed through the claim approval system.

Proxy Wiring Examples

Model Provider

Route OpenAI requests through Sigilum gateway:

{
  "models": {
    "providers": {
      "sigilum-openai": {
        "baseUrl": "http://127.0.0.1:38100/proxy/sigilum-secure-openai/v1",
        "apiKey": "sigilum-provider-proxy-key",
        "api": "openai-completions",
        "models": [
          { "id": "gpt-4", "name": "GPT-4" }
        ]
      }
    }
  }
}

Channel Proxy

Some channels support proxy configuration:

{
  "channels": {
    "telegram": {
      "proxy": "http://localhost:38100/proxy/telegram-proxy"
    }
  }
}

CLI Commands

Status Check

./sigilum openclaw status

Shows:

• Installed hooks and skills
• Active configuration
• Key material locations

Token Management

Refresh local namespace owner token:

./sigilum auth refresh --mode oss-local --namespace johndee

Login with token from stdin:

./sigilum auth login --mode managed --namespace johndee --owner-token-stdin

Show current token:

./sigilum auth show --namespace johndee

Troubleshooting

OpenClaw doesn’t see new hooks/skills

OpenClaw usually hot-reloads config, but if changes don’t appear:

openclaw gateway restart

Gateway connection failures

Check that local gateway is running:

curl http://localhost:38100/health

If not running, start it:

sigilum up

Approval requests not working

Verify agent keys were created:

ls ~/.openclaw/.sigilum/keys/

Check gateway can reach API:

curl http://localhost:38100/health/ready

Subject resolution fails

For Slack email lookups, ensure bot token has correct scopes:

export SLACK_BOT_TOKEN="xoxb-..."
# Token needs users:read scope

Or set subject explicitly:

export SIGILUM_SUBJECT="[e-mail]"

Security Contract

Important security guarantees:

• No legacy X-Sigilum-* header workflow in new integration assets
• All hooks are source-controlled (no hidden logic)
• Owner-token notification hook is opt-in and disabled by default
• Agent private keys never transmitted over network
• All gateway requests signed with RFC 9421

Next Steps

Provider Connectors

Configure HTTP and MCP provider connections through the gateway

Gateway Configuration

Advanced gateway settings and environment variables