Ogp

Prerequisites#

OGP must be installed and running:

bash

npm install -g @dp-pcs/ogp
ogp setup          # interactive first-time setup
ogp agent-comms interview  # revisit delegated-authority / human-delivery behavior
ogp config show    # verify enabled frameworks + default
ogp start          # starts the default framework
ogp status         # verify daemon is running

If ogp: command not found, install it first.

---

Framework Selection (Mandatory in Multi-Framework Setups)#

When more than one framework is enabled, always choose the correct one explicitly:

bash

ogp --for openclaw status
ogp --for hermes status
ogp --for openclaw federation list
ogp --for hermes federation list

• openclaw usually uses ~/.ogp
• hermes usually uses ~/.ogp-hermes
• ogp config show is the first command to run if the active framework is unclear

If you are testing unreleased changes from a local repo checkout, prefer the local CLI:

bash

node dist/cli.js --for openclaw status
node dist/cli.js --for hermes federation list

CLI Discovery Shortcuts#

When the user is unsure which command to run, teach the built-in CLI discovery path before inventing custom guidance:

bash

ogp ?                         # top-level command map
ogp federation approve ?      # contextual help for approval
ogp config show               # inspect configured/default framework
ogp config set-default openclaw
ogp completion install zsh    # or bash

• Prefer ogp config show first when framework context is unclear.
• Prefer ogp config set-default <framework> when the user keeps forgetting --for.
• Mention ogp completion install <shell> for users who will work with OGP often.

---

Canonical Public Endpoint Rule#

Use one canonical public gateway URL per framework. The recommended production setup is a stable HTTPS hostname, typically behind a named Cloudflare tunnel or other reverse proxy.

• Keep gatewayUrl pointed at the stable public hostname
• Do not leave stale temporary tunnel residue in config
• Verify the public discovery card matches the local framework you intend to use

bash

curl -s https://ogp.example.com/.well-known/ogp
curl -s https://hermes.example.com/.well-known/ogp

The public key on each discovery card must match the intended framework identity. If two frameworks advertise the same key unexpectedly, stop and fix framework selection/state isolation before federating.

---

Optional Rendezvous Discovery (v0.2.14+)#

The rendezvous server ( rendezvous.elelem.expert) is an optional discovery/invite service. Use it for pubkey lookup or short invite codes when peers are already publicly reachable. Do not treat it as NAT traversal or a substitute for a real public gateway URL.

Invite flow (easiest — v0.2.15+)#

To invite a peer (you generate the code):

bash

ogp federation invite
# Output: Your invite code: a3f7k2  (expires in 10 minutes)
# Share this with your peer — they run: ogp federation accept a3f7k2

To accept a peer's invite:

bash

ogp federation accept <token>
# Output: Connected to a3f7k2... via rendezvous ✅

Connect by public key (v0.2.14+)#

bash

ogp federation connect <pubkey>
# Looks up the peer's current connection hints from rendezvous, then connects directly

Enable rendezvous in config#

Add to ~/.ogp/config.json:

json

{
  "rendezvous": {
    "enabled": true,
    "url": "https://rendezvous.elelem.expert"
  }
}

When enabled, your daemon auto-registers on startup and heartbeats every 30 seconds.

---

Configuration#

Agent ID (v0.2.28+)#

The agentId field identifies which OpenClaw agent owns this OGP gateway. During ogp setup, the wizard auto-discovers available agents from your OpenClaw configuration:

text

Available agents:
  1. 🦝 Junior (main)
  2. ✍️ Scribe (scribe)
  3. ⚡ Optimus (optimus)

Which agent owns this gateway? (number or ID) [1]:

Example config with agentId:

json

{
  "daemonPort": 18790,
  "openclawUrl": "http://localhost:18789",
  "openclawToken": "your-token",
  "gatewayUrl": "https://your-gateway.example.com",
  "displayName": "Alice",
  "email": "alice@example.com",
  "stateDir": "~/.ogp",
  "agentId": "main"
}

Notification Routing — notifyTargets (v0.2.28+)#

The notifyTargets field enables per-agent notification routing. When OGP sends notifications to your OpenClaw instance, it routes to specific agents based on the message context.

For OpenClaw specifically, human-facing federated work is now handled primarily through POST /hooks/agent, not by guessing the "current" session. notifyTargets answers "which local agent owns this work?" while humanDeliveryTarget answers "where should the human-facing followup go?"

Configuration fields:

• notifyTarget (legacy, string): Single notification target for all messages. Maintained for backward compatibility.
• notifyTargets (object): Map of agent names to notification targets. Example: {"main": "telegram:...", "scribe": "telegram:..."}
• humanDeliveryTarget (preferred for human-facing followups): Explicit destination for OGP-triggered relay obligations and summaries.

Example configuration with multiple agents:

json

{
  "daemonPort": 18790,
  "openclawUrl": "http://localhost:18789",
  "openclawToken": "your-token",
  "gatewayUrl": "https://your-gateway.example.com",
  "displayName": "Alice",
  "email": "alice@example.com",
  "stateDir": "~/.ogp",
  "agentId": "main",
  "notifyTarget": "telegram:123456789",
  "humanDeliveryTarget": "telegram:123456789",
  "inboundFederationPolicy": {
    "mode": "summarize"
  },
  "notifyTargets": {
    "main": "telegram:123456789",
    "scribe": "telegram:987654321",
    "optimus": "telegram:555666777"
  }
}

Resolution priority:

When routing notifications, OGP resolves the target in this order:

1. humanDeliveryTarget — If set, use it as the explicit human-facing OGP destination
2. notifyTargets[agent] — If the agent is specified and exists in notifyTargets, use that target
3. notifyTarget — Fall back to the legacy single target for backward compatibility
4. Default — If none are set, OGP falls back to the agent's default session

This allows you to:

• Route federation messages to different agents based on context
• Explicitly separate "the agent that owns this gateway" from "the human-facing channel for OGP followups"
• Maintain backward compatibility with existing single-agent setups
• Gradually migrate to multi-agent routing without breaking existing configurations

Human Delivery Preferences (v0.4.2+)#

Do not assume that "whatever conversation is currently active" is the right place to satisfy a peer's request to notify the human.

Use these config fields to separate routing from behavior:

• humanDeliveryTarget: Explicit human-facing destination for OGP-triggered followups.

  • Example: "telegram:123456789"
  • Or a raw session key: "agent:main:telegram:direct:123456789"

• inboundFederationPolicy.mode: Default handling mode for inbound federated requests.

Supported modes:

• forward — Tell me everything
• summarize — Tell me only important/actionable items
• autonomous — Act autonomously unless blocked or explicitly asked to relay something
• approval-required — Do not act or reply until the human approves

Example:

json

{
  "humanDeliveryTarget": "telegram:123456789",
  "inboundFederationPolicy": {
    "mode": "summarize"
  }
}

For OpenClaw specifically:

• OGP uses POST /hooks/agent as the primary delivery path for inbound federated work that the local agent should interpret and handle.
• If OGP needs direct session injection, it uses Gateway RPC with wss:// when the OpenClaw gateway is TLS-enabled.
• Do not claim delivery unless you actually used the configured human-facing channel or the platform confirmed the hook task completed.

OGP now resolves delegated-authority rules when deciding how to treat a federated request: global defaults, peer defaults, message-class rules ( human-relay, agent-work, approval-request, status-update), and topic overrides each layer in to determine whether to forward, summarize, act autonomously, or wait for approval. Hooks will only run with the exact human session key when OpenClaw has hooks.allowRequestSessionKey=true and the requested key matches hooks.allowedSessionKeyPrefixes; otherwise OGP logs a warning and runs in the default hook session, meaning Telegram delivery still looks like injected/ cli content, which is the accepted v0.4.2 limitation documented in the README/changelog.

For first-time configuration, use ogp setup. To revisit only the delegated-authority / human-delivery interview later, use:

bash

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

When a peer says "tell David X", that is a delivery obligation. Do not treat it as satisfied just because the information appeared in some other active session.

---

Federation Management#

List all peers#

bash

ogp --for openclaw federation list
ogp --for openclaw federation list --status pending
ogp --for hermes federation list --status approved

Request federation with a new peer#

bash

ogp --for <framework> federation request <peer-gateway-url> [--alias <name>]
# Example:
ogp --for openclaw federation request https://hermes.example.com --alias apollo

# Alias auto-resolves from gateway's display name if omitted:
ogp --for openclaw federation request https://hermes.example.com

Approve an inbound federation request#

bash

# Auto-grants scopes that mirror peer's offered intents (symmetric federation)
ogp --for hermes federation approve <peer-id>

# Or approve with specific custom scopes (asymmetric):
ogp --for hermes federation approve <peer-id> --intents "message,agent-comms,project.join,project.contribute,project.query,project.status"

Note (OGP 0.2.24+): Peer IDs are now public key prefixes (e.g., 302a300506032b65). Intent Negotiation: Approval automatically mirrors the intents the peer offered, creating symmetric capabilities by default. Both sides can call the same intents on each other.

Grant or update scopes for an existing peer#

bash

ogp --for openclaw federation grant <peer-id> --intents "message,agent-comms,project.join,project.contribute,project.query,project.status"

Check what scopes are granted to/from a peer#

bash

ogp --for openclaw federation scopes <peer-id>
# Shows:
# - GRANTED TO PEER (what they can call on your gateway)
# - RECEIVED FROM PEER (what you can call on theirs)

Ping a peer#

bash

ogp --for openclaw federation ping <peer-gateway-url>

Send a raw federation message#

bash

ogp --for openclaw federation send <peer-id> <intent> '<json-payload>'

Send an agent-to-agent message (agent-comms)#

bash

ogp --for openclaw federation agent <peer-id> <topic> "<message>"
# Example:
ogp --for openclaw federation agent apollo general "Hey, can you check on project synapse?"

Manage agent-comms policies (what topics you'll respond to)#

Federation scopes and agent-comms policies are two separate layers. Approval handles scopes automatically. Agent-comms policies control what your agent actually responds to — general is auto-enabled at approval, everything else is off by default.

bash

# Status page — shows what's allowed, blocked, and what to do about it
ogp --for openclaw agent-comms policies <peer-id>

# Global view of all peers
ogp --for openclaw agent-comms policies

# Allow a topic
ogp --for openclaw agent-comms add-topic <peer-id> <topic> --level summary

# Block a topic
ogp --for openclaw agent-comms set-topic <peer-id> <topic> off

# Open all topics by default for a peer
ogp --for openclaw agent-comms set-default <peer-id> summary

# View activity log
ogp --for openclaw agent-comms activity [peer-id]

Response levels: full (full content passed to agent), summary (condensed), escalate (route to user), off (blocked — sender gets a witty non-answer)

---

Scope Reference#

ScopeWhat it allowsmessageBasic gateway-to-gateway messagesagent-commsAgent-to-agent messages (natural language)project.joinPeer can join your projectsproject.contributePeer can push contributions to your projectsproject.queryPeer can query your project dataproject.statusPeer can check your project status

Default grant includes all of the above. Customize with --intents if needed.

---

Federation Workflow#

New way — invite flow (v0.2.15+, recommended)#

text

1. Run: ogp federation invite → get a 6-char code
2. Share the code with your peer (Telegram, Slack, etc.)
3. They run: ogp federation accept <code>
4. Scopes auto-granted + "general" topic auto-enabled ✓
5. Test: ogp --for <framework> federation agent <peer-id> general "hello"

Old way — manual URL exchange (still works)#

text

1. Get peer's gateway URL (they share it with you)
2. Check their card: curl -s <url>/.well-known/ogp | python3 -m json.tool
3. Request federation: ogp --for <framework> federation request <url>
4. They approve on their side (or you approve if they requested)
   → Scopes auto-granted + "general" topic auto-enabled ✓
5. Check agent-comms status: ogp --for <framework> agent-comms policies <peer-id>
6. Add more topics if needed: ogp --for <framework> agent-comms add-topic <peer-id> <topic>
7. Test: ogp --for <framework> federation ping <url>
8. Test agent-comms: ogp --for <framework> federation agent <peer-id> general "hello"
9. (Optional) Create or join a shared project

---

Project Collaboration (via OGP)#

For full project management, use the ogp-project skill. Quick reference:

bash

# Create a project
ogp --for openclaw project create <id> "<name>" --description "<description>"

# Invite a peer to join
ogp --for openclaw project request-join <peer-id> <project-id> "<project-name>"

# Log a contribution
ogp --for openclaw project contribute <project-id> <type> "<summary>"
# Types: progress, decision, blocker, context, idea, context.description, context.repository

# Query project activity
ogp --for openclaw project query <project-id> [--type <type>] [--limit 10]
ogp --for openclaw project status <project-id>

# Query a peer's project data
ogp --for openclaw project query-peer <peer-id> <project-id>

---

Troubleshooting#

ErrorLikely CauseFixPeer not foundNot yet federatedRun ogp federation request <url>``Peer not approvedRequest pendingCheck ogp federation list --status pending``400 Bad Request on pushPeer hasn't granted you scopesAsk peer to run ogp federation grant <your-peer-id> or update to OGP 0.2.7Invalid signatureVersion mismatch on messageStr fieldPeer needs OGP 0.2.7+ ( npm install -g @dp-pcs/ogp@latest)Send failed on agent-commsTopic blocked on receiver's sideReceiver runs ogp agent-comms policies <peer-id> — look for blocked/missing topicsAgent-comms silently ignoredReceiver's default is off, topic not allowedReceiver runs ogp agent-comms add-topic <your-peer-id> <topic> --level summary``ogp: command not foundNot installednpm install -g @dp-pcs/ogpDaemon not runningProcess died or wrong framework selectedogp config show, then ogp --for <framework> start --backgroundPublic discovery card shows the wrong identityWrong framework home or stale daemonStop daemons, verify ogp config show, restart each framework explicitly with --forPeer list is obviously stale or cross-contaminatedWrong framework state file or old federation residueBack up then clear the relevant peers.json for the affected framework and re-form federation

Check OGP daemon status#

bash

ogp config show
ogp --for openclaw status
ogp --for hermes status
# Or check the logs:
tail -f ~/.ogp/daemon.log
tail -f ~/.ogp-hermes/daemon.log

Restart the daemon#

bash

ogp --for openclaw stop
ogp --for openclaw start --background
ogp --for hermes stop
ogp --for hermes start --background

Clean federation state for one framework#

bash

cp ~/.ogp/peers.json ~/.ogp/peers.json.backup.$(date +%Y%m%d-%H%M%S)
printf '[]\n' > ~/.ogp/peers.json

cp ~/.ogp-hermes/peers.json ~/.ogp-hermes/peers.json.backup.$(date +%Y%m%d-%H%M%S)
printf '[]\n' > ~/.ogp-hermes/peers.json

---

State Files#

FilePurpose~/.ogp-meta/config.jsonEnabled frameworks, aliases, and default framework~/.ogp/config.jsonOpenClaw gateway config~/.ogp-hermes/config.jsonHermes gateway config~/.ogp/keypair.jsonOpenClaw public key cache on macOS; full keypair file on non-macOS~/.ogp-hermes/keypair.jsonHermes public key cache on macOS; full keypair file on non-macOS~/.ogp/peers.jsonOpenClaw federation peers + scopes~/.ogp-hermes/peers.jsonHermes federation peers + scopes~/.ogp/projects.jsonOpenClaw project data + contributions~/.ogp-hermes/projects.jsonHermes project data + contributions~/.ogp/daemon.logOpenClaw daemon log~/.ogp-hermes/daemon.logHermes daemon log~/.ogp/activity.logOpenClaw agent-comms activity log~/.ogp-hermes/activity.logHermes agent-comms activity log

---

Design Notes#

• Peer Identity (OGP 0.2.24+): Peers are identified by the first 16 characters of their Ed25519 public key (e.g., 302a300506032b65). This is stable even when tunnel URLs rotate — the public key is the identity, the URL is just the address.
• Framework isolation matters: In multi-framework mode, OpenClaw and Hermes must keep distinct state directories, keypairs, peers, projects, and logs. Always use --for when the active framework is not obvious.
• macOS key storage: The private key source of truth is the instance-specific Keychain entry derived from the framework config dir. Deleting keypair.json alone does not rotate identity; use ogp setup --reset-keypair when you actually want a new keypair.
• Intent Negotiation (OGP 0.2.24+): Federation requests include offeredIntents. Approval automatically mirrors those intents back to the requester, creating symmetric capabilities by default.
• Scopes are bilateral: Each side independently grants what the other can call. OGP 0.2.24+ auto-mirrors offered intents on approval.
• Project isolation: Projects are scoped to their member list. Full mesh federation does NOT give all peers access to all projects. A peer only sees projects they are a member of.
• Signatures: All federation messages are signed with Ed25519. Peer's public key is stored in peers.json at federation time.
• Rendezvous is optional: Peers with a static IP or existing tunnel continue working unchanged. Rendezvous is an additional discovery path, not a requirement.
• Notification Routing: The notifyTargets config enables multi-agent setups where different agents handle different types of federation messages.
• Stable public URLs win: Use a canonical public hostname per framework. Treat ephemeral tunnel URLs as temporary diagnostics, not long-term identity.