开源AI工作流：Open Gateway Protocol

Prerequisites

• Node.js 18 or higher
• OpenClaw installed and running - Get it at https://openclaw.ai
• OpenClaw API token - Generated during OpenClaw setup

Installation

npm install -g @dp-pcs/ogp

Or from GitHub:

npm install -g github:dp-pcs/ogp

After installation, install the OGP skills for Claude Code:

ogp-install-skills

This auto-discovers and installs all OGP skills from the skills/ directory. The installer now replaces each installed skill directory wholesale on upgrade so stale files from older package versions do not survive.

Verify the installed copies after an upgrade:

rg -n '^version:' ~/.openclaw/skills/ogp*/SKILL.md ~/.claude/skills/ogp*/SKILL.md 2>/dev/null

The installed skill versions should match the skills bundled with the @dp-pcs/ogp version you have installed (run ogp completion install / ogp-install-skills after upgrading to refresh them). If the reported versions are older than the bundled skills/*/SKILL.md in this package, re-run the skill installer.

1. Setup

Run the interactive setup wizard:

ogp setup

The wizard automatically detects installed frameworks and guides you through configuration. You'll be prompted for: - Framework Selection - Which AI frameworks to enable (OpenClaw, Hermes, or standalone) - Agent ID - Which agent owns each gateway (auto-discovers from framework config) - Daemon port (default: 18790 for OpenClaw, 18793 for Hermes) - Framework URL and API credentials - Your public gateway URL (can update later; rendezvous is optional discovery/invite sugar, not a replacement for reachability) - Rendezvous configuration (optional, v0.2.14+) - Display name and email

Working with Multiple Frameworks:

When multiple frameworks are configured, use the --for flag to specify which framework:

```bash

5. Install as a system service

cloudflared service install

Set identity during setup (auto-prompted)

ogp setup

Register a deployment intent

ogp intent register deployment \ --description "Deployment notifications"

Register deployment intent

ogp intent register deployment \ --session-key "agent:main:main" \ --description "Deployment notifications"

Getting Started

• Getting Started Guide - Comprehensive setup guide for single and multi-framework setups
• Quick Start Guide - Fast-track setup for single framework
• CLI Reference - Complete command reference with examples
• Migration Guide - Upgrading from single to multi-framework setup

Build from Source

git clone https://github.com/dp-pcs/ogp.git
cd ogp
npm install
npm run build
npm link

Quick Start

Federation Examples

```bash

Project Examples (v0.2.0+)

```bash

Custom Intent Examples (v0.2.0+)

```bash

Agent-Comms Policy Examples (v0.2.0+)

```bash

4. Create config file at ~/.cloudflared/config.yml

cat > ~/.cloudflared/config.yml <<EOF tunnel: <TUNNEL_ID_FROM_STEP_2> credentials-file: ~/.cloudflared/<TUNNEL_ID>.json

ingress: - hostname: ogp.yourdomain.com service: http://localhost:18790 - service: http_status:404 EOF

6. Update your OGP config

ogp stop

Edit ~/.ogp/config.json and set "gatewayUrl": "https://ogp.yourdomain.com"

ogp start --background

Your URL is now `https://ogp.yourdomain.com` and will persist across restarts.

#### Option 2: ngrok (Good — Free tier available)

Good fallback if you don't have a domain on Cloudflare. The free tier gives you a stable subdomain that persists across restarts IF you're logged in with an ngrok account.

**Setup:**

5. Update your OGP config

ogp stop

Edit ~/.ogp/config.json and set "gatewayUrl": "https://abc123.ngrok-free.app"

ogp start --background

Your ngrok URL will be stable as long as you're authenticated. You can also run `ngrok http 18790 --log stdout > ngrok.log 2>&1 &` to keep it running in the background.

#### Option 3: Cloudflare Anonymous Tunnel (Quick but Ephemeral)

Good for testing only. No account needed, but your URL changes every time you restart the tunnel, so peers need a new URL each time.

Copy the displayed URL and update your gatewayUrl. Not recommended for ongoing federation — use this only for quick tests.

Option 4: Port Forwarding

Forward port 18790 on your router to your machine running OGP. Set gatewayUrl to http://YOUR_PUBLIC_IP:18790.

This works but exposes your home IP address. Most users should prefer the tunnel options above.

Configuration Management

Scope Options (v0.2.0)

When approving or granting scopes: - --intents <list> - Comma-separated intents (e.g., message,agent-comms) - --rate <limit> - Rate limit as requests/seconds (e.g., 100/3600) - --topics <list> - Topics for agent-comms (e.g., memory-management,task-delegation)

Configure global defaults

ogp agent-comms configure --global \ --topics "general,testing" \ --level summary

Configure specific peer

ogp agent-comms configure stan \ --topics "memory-management" \ --level full \ --notes "Trusted collaborator"

Multi-peer configuration

ogp agent-comms configure stan,leo,alice \ --topics "testing,debugging" \ --level full

Rendezvous — Optional Discovery And Invite Layer (v0.2.14+)

Rendezvous is an optional convenience layer for pubkey lookup and short invite codes. It is useful when you want easier onboarding for gateways that are already publicly reachable.

Configuration

Add the rendezvous block to ~/.ogp/config.json:

{
  "daemonPort": 18790,
  "openclawUrl": "http://localhost:18789",
  "openclawToken": "your-token",
  "rendezvous": {
    "enabled": true,
    "url": "https://rendezvous.elelem.expert"
  }
}

Rendezvous is optional. OGP works without it if peers can share public URLs directly.

For cloud/ECS gateways behind load balancers, set the OGP_PUBLIC_URL environment variable to override automatic IP detection:

export OGP_PUBLIC_URL=https://your-gateway.example.com
ogp start

Or add publicUrl to the rendezvous config:

{
  "rendezvous": {
    "enabled": true,
    "url": "https://rendezvous.elelem.expert",
    "publicUrl": "https://your-gateway.example.com"
  }
}

Configure your identity

ogp config set-identity \ --human-name "David Proctor" \ --agent-name "Junior" \ --organization "Trilogy"

Setting or Changing an Alias

```bash

Configure global defaults

ogp agent-comms configure --global --topics "general,testing" --level summary

Configure specific peer(s)

ogp agent-comms configure stan --topics "memory-management" --level full --notes "Trusted" ogp agent-comms configure stan,leo,alice --topics "testing" --level full # Multi-select

Settings

ogp agent-comms default summary # Set default level ogp agent-comms logging on # Enable/disable logging ```

Configuration

Configuration is stored in ~/.ogp/config.json:

{
  "daemonPort": 18790,
  "openclawUrl": "http://localhost:18789",
  "openclawToken": "your-openclaw-api-token",
  "gatewayUrl": "https://your-public-url.com",
  "displayName": "Your Name",
  "email": "you@example.com",
  "stateDir": "~/.ogp",
  "agentId": "main",
  "humanDeliveryTarget": "telegram:123456789",
  "inboundFederationPolicy": {
    "mode": "summarize"
  },
  "notifyTarget": "telegram:123456789",
  "notifyTargets": {
    "main": "telegram:123456789",
    "scribe": "telegram:987654321"
  },
  "rendezvous": {
    "enabled": true,
    "url": "https://rendezvous.elelem.expert",
    "publicUrl": "https://your-gateway.example.com"
  }
}

Environment Variables

• OGP_PUBLIC_URL (v0.2.17+): Override automatic IP detection for rendezvous registration. Use this for cloud/ECS gateways behind load balancers where the detected IP differs from the public endpoint.

  export OGP_PUBLIC_URL=https://your-gateway.example.com
  ogp start
  

Takes precedence over rendezvous.publicUrl in config.json.

Or specify a custom alias for easier reference

ogp federation request https://peer.example.com --alias apollo

Human Delivery Preferences (v0.4.2+)

OGP has two separate questions to answer for inbound federation traffic:

1. Where should human-facing followups go?
2. How should the agent behave when a peer asks it to do something?

Those should not be inferred from the currently active conversation.

Configuration fields: - humanDeliveryTarget: Explicit human-facing destination for OGP-triggered followups. Examples: telegram:123456789 or a raw session key like agent:main:telegram:direct:123456789. - inboundFederationPolicy.mode: Default behavior for how the local agent should handle inbound federated requests.

For OpenClaw specifically, this configuration feeds the /hooks/agent delivery path. In other words: - humanDeliveryTarget tells OGP where human-facing followups should go - inboundFederationPolicy.mode tells the local agent how to treat federated requests once they arrive - OGP should not infer either of those from "whatever session is active right now"

Supported behavior modes: - forward: Tell me everything. Forward inbound federated items to my configured channel. - summarize: Summarize and surface only important, actionable, or uncertain items. - autonomous: Act autonomously when possible, but surface blockers, approvals, or explicit relay requests. - approval-required: Do not act on or reply to federated requests until I explicitly approve.

Example configuration:

{
  "agentId": "main",
  "humanDeliveryTarget": "telegram:123456789",
  "inboundFederationPolicy": {
    "mode": "autonomous"
  }
}

When you run ogp setup, the wizard asks for both: - the primary human delivery target for OGP followups - the default inbound federation handling mode

If the user wants to revisit just this part later, use:

ogp --for openclaw agent-comms interview
ogp --for hermes agent-comms interview

That command re-runs the delegated-authority / human-delivery interview for the active framework without repeating the rest of first-time setup.

What This Package Does

This is a companion daemon that adds federation capabilities to any standard OpenClaw installation. It runs alongside your OpenClaw instance on a separate port and handles:

• Cryptographically signed peer-to-peer messaging using Ed25519
• Peer relationship management (request, approve, reject)
• Identity attribution with separate human and agent names (v0.5.0+)
• Project collaboration with identity snapshots for historical accuracy (v0.6.0+)
• Per-contribution signatures — every project contribution is author-signed and verified on receipt, with a stable ULID id (v0.8.0+)
• Multi-agent personas — multiple local agents per gateway, listable via ogp config list-agents (v0.7.0+)
• Single-daemon stateDir lock preventing duplicate ogp start write-races (v0.8.0+)
• Message verification and relay to your OpenClaw agent
• Public tunnel support (cloudflared/ngrok) for internet accessibility, managed via ogp tunnel
• Optional macOS LaunchAgent for automatic startup

System Integration (macOS)

Peer Aliases vs Public Key IDs

OGP uses two different identifiers for peers: