Skip to content

GETTING-STARTED.md

Latest commit

 

History

History
953 lines (676 loc) · 19.9 KB

GETTING-STARTED.md

File metadata and controls

953 lines (676 loc) · 19.9 KB

OGP Getting Started Guide

This comprehensive guide covers everything you need to get started with OGP, from basic single-framework setup to advanced multi-framework configurations.

Table of Contents

Prerequisites

Before installing OGP, ensure you have:

  • Node.js 18 or higher - Check with node --version
  • An AI framework installed (one or more):
    • OpenClaw - Get it at https://openclaw.ai
    • Hermes - Contact your Hermes provider
    • Or run standalone (no framework required)
  • API credentials for your framework (generated during framework setup)

Quick Start: Single Framework

If you're using only one AI framework (e.g., OpenClaw), setup is straightforward.

1. Install OGP

npm install -g @dp-pcs/ogp

2. Install Skills (Optional)

Install OGP skills for Claude Code integration:

ogp-install-skills

Verify the installed copies after an upgrade:

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

For the current 0.4.2 release line, the changed skills should report ogp 2.6.0, ogp-agent-comms 0.6.0, and ogp-project 2.2.0.

3. Run Setup

ogp setup

The wizard will:

  1. Detect installed frameworks
  2. Prompt for framework configuration
  3. Create config directory (e.g., ~/.ogp-openclaw/)
  4. Generate cryptographic keypair
  5. Create meta-config at ~/.ogp-meta/config.json

Example Setup Session:

=== OGP Setup ===

🔍 Detecting installed AI frameworks...
  ✓ Found OpenClaw at ~/.openclaw/

Which frameworks do you want to enable OGP for?
  [x] OpenClaw (Junior @ OpenClaw)
  [ ] Standalone (no framework)

=== Configuring OpenClaw ===

Available agents:
  1. 🦝 Junior (main)
  2. ✍️ Scribe (scribe)

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

Daemon port [18790]: <enter>
OpenClaw URL [http://localhost:18789]: <enter>
OpenClaw API token: your-token-here
Gateway URL (your public URL): https://ogp.example.com
Display name: Alice
Email: alice@example.com

Enable optional rendezvous for invite codes / pubkey discovery? [y/N]: n
Rendezvous server URL [https://rendezvous.elelem.expert]: <enter>

✓ OpenClaw configured
  Config: ~/.ogp-openclaw/
  Port: 18790
  Agent: Junior (main)

✓ OGP setup complete!
  Default framework: openclaw

4. Start the Daemon

ogp start --background

Check status:

ogp status

Output:

OGP Daemon Status:
  Framework: openclaw
  Status: ● Running
  Port: 18790
  PID: 12345
  Uptime: 5 minutes
  Public Key: 302a300506032b6570032100...
  Gateway URL: https://ogp.example.com

5. Test Your Gateway

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

You should see your gateway metadata (public key, capabilities, endpoints).

That's it! Your single-framework OGP gateway is running. Skip to Common Workflows to start federating.

Quick Start: Multiple Frameworks

If you're using multiple AI frameworks (e.g., OpenClaw and Hermes), OGP can manage separate gateways for each.

1. Install OGP

npm install -g @dp-pcs/ogp

2. Run Setup

ogp setup

The wizard will detect all installed frameworks:

=== OGP Setup ===

🔍 Detecting installed AI frameworks...
  ✓ Found OpenClaw at ~/.openclaw/
  ✓ Found Hermes at ~/.hermes/

Which frameworks do you want to enable OGP for?
  [x] OpenClaw (Junior @ OpenClaw)
  [x] Hermes (Apollo @ Hermes)
  [ ] Standalone (no framework)

Select all frameworks you want to enable (use space to toggle, enter to confirm).

3. Configure Each Framework

The wizard will prompt for configuration for each selected framework:

=== Configuring OpenClaw ===

Available agents:
  1. 🦝 Junior (main)

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

Daemon port [18790]: <enter>
OpenClaw URL [http://localhost:18789]: <enter>
OpenClaw API token: your-openclaw-token
Gateway URL: https://ogp.example.com
Display name: Junior @ OpenClaw
Email: alice@example.com

=== Configuring Hermes ===

Available agents:
  1. 🌟 Apollo (main)

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

Daemon port [18793]: <enter>
Hermes webhook URL [http://localhost:18792/webhooks/ogp]: <enter>
Hermes webhook secret: your-hermes-secret
Gateway URL: https://hermes.example.com
Display name: Apollo @ Hermes
Email: alice@example.com

✓ OGP configured for 2 frameworks
  OpenClaw: ~/.ogp-openclaw/
  Hermes:   ~/.ogp-hermes/

Default framework: openclaw

Tip: Use `ogp --for openclaw <command>` or `ogp --for hermes <command>`
     Or set a default: `ogp config set-default openclaw`

4. Start Daemons

Start daemons for each framework:

# Start OpenClaw daemon
ogp --for openclaw start --background

# Start Hermes daemon
ogp --for hermes start --background

Or start all at once:

ogp --for all start --background

5. Check Status

ogp --for all status

Output:

=== OpenClaw (Junior @ OpenClaw) ===
OGP Daemon Status:
  Framework: openclaw
  Status: ● Running
  Port: 18790
  PID: 12345
  Uptime: 2 minutes

=== Hermes (Apollo @ Hermes) ===
OGP Daemon Status:
  Framework: hermes
  Status: ● Running
  Port: 18793
  PID: 12346
  Uptime: 2 minutes

Now you have two independent OGP gateways running, one for each framework.

Framework Detection and Selection

Automatic Detection

During setup, OGP automatically detects installed frameworks by checking:

  1. Framework directories:

    • OpenClaw: ~/.openclaw/
    • Hermes: ~/.hermes/

  2. Framework commands:

    • openclaw command available
    • hermes command available

Manual Selection

If auto-detection doesn't find your framework:

  1. Select "Standalone (no framework)" during setup
  2. Manually configure OGP_HOME before running commands:
export OGP_HOME=~/.ogp-custom
ogp setup

Framework Configuration Directories

Each framework gets its own config directory:

Framework Directory Default Port
OpenClaw ~/.ogp-openclaw/ 18790
Hermes ~/.ogp-hermes/ 18793
Standalone ~/.ogp/ 18790

All configs are managed from ~/.ogp-meta/config.json.

Using the --for Flag

The --for flag specifies which framework configuration to use for a command.

Basic Usage

# Use OpenClaw config
ogp --for openclaw federation list

# Use Hermes config
ogp --for hermes federation list

# Run on all frameworks
ogp --for all federation list

When --for is Required

The --for flag is required when:

  1. Multiple frameworks are configured and no default is set
  2. You want to override the default framework
  3. You want to run on all frameworks (--for all)

When --for is Optional

The --for flag is optional when:

  1. Only one framework is configured (auto-selected)
  2. A default framework is set (uses default)

Examples

# Start specific framework daemon
ogp --for openclaw start --background

# Request federation from specific framework
ogp --for openclaw federation request https://peer.example.com

# Send message from Hermes gateway
ogp --for hermes federation send apollo message '{"text":"Hello from Hermes!"}'

# Check status of all frameworks
ogp --for all status

# List all peers across all frameworks
ogp --for all federation list

--for all Behavior

When using --for all, OGP runs the command on all enabled frameworks and aggregates results:

$ ogp --for all federation list

=== OpenClaw (Junior @ OpenClaw) ===
PEERS:
  apollo (Apollo @ Hermes) - approved
  bob (Bob @ OpenClaw) - approved

=== Hermes (Apollo @ Hermes) ===
PEERS:
  junior (Junior @ OpenClaw) - approved
  charlie (Charlie @ Hermes) - pending

Setting a Default Framework

Set a default framework to avoid using --for on every command.

Set Default

ogp config set-default openclaw

Output:

✓ Default framework: openclaw

Check Default

ogp config list

Output:

Configured frameworks:
  openclaw  [default]  ● Enabled  ~/.ogp-openclaw/  18790
  hermes               ● Enabled  ~/.ogp-hermes/    18793

Using the Default

Once set, commands automatically use the default framework:

# No --for needed, uses openclaw (default)
ogp federation list
ogp start --background
ogp status

Override the Default

Use --for to override the default for a single command:

# Uses hermes instead of default (openclaw)
ogp --for hermes federation list

Tab Completion Setup

Tab completion makes command entry faster and helps discover available commands, peers, and frameworks.

Install Completion

Bash

ogp completion install bash

Reload your shell:

source ~/.bashrc

Zsh

ogp completion install zsh

Reload your shell:

source ~/.zshrc

Using Completion

Once installed, press TAB to complete commands:

# Complete commands
ogp fed<TAB>
# → ogp federation

# Complete subcommands
ogp federation <TAB>
# → list  request  approve  reject  remove  send  agent  scopes  alias

# Complete --for flag
ogp --for <TAB>
# → openclaw  hermes  all

# Complete peer names
ogp federation send <TAB>
# → apollo  bob  charlie

# Complete intents
ogp federation send apollo <TAB>
# → message  task-request  status-update  agent-comms  project.*

Completion Features

  • Command completion: Top-level commands and subcommands
  • Framework completion: Framework names for --for flag
  • Peer completion: Peer aliases from current framework config
  • Intent completion: Available intents for send command
  • Flag completion: Available flags for each command

Using ? Style Help

OGP provides Cisco IOS-style context-sensitive help with the ? operator.

Top-Level Help

ogp ?

Output:

Available commands:
  setup           Initialize OGP configuration
  start           Start OGP daemon
  stop            Stop OGP daemon
  status          Show daemon status
  federation      Manage federation
  agent-comms     Configure agent-to-agent messaging
  project         Manage projects
  intent          Manage custom intents
  config          Manage configuration
  expose          Manage public tunnel
  install         Install LaunchAgent (macOS)
  uninstall       Remove LaunchAgent (macOS)
  completion      Manage shell completion

Use `ogp <command> ?` for more details.

Command-Level Help

ogp federation ?

Output:

Available federation commands:
  list            List all peers
  request         Send federation request
  approve         Approve pending peer
  reject          Reject pending peer
  remove          Remove peer
  send            Send message to peer
  agent           Send agent-comms message
  scopes          View/update scopes
  alias           Manage peer aliases
  ping            Test connectivity
  invite          Generate invite code
  accept          Accept invite
  connect         Connect by public key

Use `ogp federation <command> ?` for usage.

Command Usage Help

ogp federation send ?

Output:

Usage: ogp federation send <peer> <intent> <payload>

Arguments:
  peer     Peer ID, alias, or display name
  intent   Intent type (message, task-request, status-update, agent-comms, project.*)
  payload  JSON payload

Available peers (openclaw):
  - apollo (Apollo @ Hermes) - approved
  - bob (Bob @ OpenClaw) - approved

Example:
  ogp federation send apollo message '{"text":"Hello from OGP!"}'
  ogp federation send bob agent-comms '{"topic":"memory","message":"How do you persist context?"}'

Parameter Help

ogp federation approve ?

Output:

Usage: ogp federation approve <peer-id> [options]

Options:
  --intents <list>    Comma-separated intents (message,agent-comms)
  --rate <limit>      Rate limit as requests/seconds (100/3600)
  --topics <list>     Topics for agent-comms (memory-management,task-delegation)

Examples:
  # Approve without restrictions
  ogp federation approve apollo

  # Approve with scope grants
  ogp federation approve apollo \
    --intents message,agent-comms \
    --rate 100/3600 \
    --topics memory-management,task-delegation

Common Workflows

Single Framework Workflow

If you're using only one framework:

# Setup (once)
ogp setup
ogp start --background

# Daily usage (no --for needed)
ogp federation request https://peer.example.com
ogp federation list
ogp federation send apollo message '{"text":"Hello!"}'
ogp status

Multi-Framework Workflow

If you're using multiple frameworks:

# Setup (once)
ogp setup
ogp --for all start --background
ogp config set-default openclaw

# Daily usage with default
ogp federation list                    # Uses openclaw (default)
ogp federation send apollo message '{"text":"Hello!"}'

# Explicit framework selection
ogp --for hermes federation list       # Uses hermes
ogp --for hermes federation send bob message '{"text":"Hi from Hermes!"}'

# Cross-framework operations
ogp --for all status                   # Check all daemons
ogp --for all federation list          # List all peers

Federation Setup Workflow

Setting up federation between two peers:

Alice (OpenClaw):

# 1. Start daemon and expose
ogp start --background
ogp expose --background

# 2. Share gateway URL with Bob
# Gateway: https://alice.example.com

# 3. Request federation with Bob
ogp federation request https://bob.example.com --alias bob

# 4. Wait for Bob's approval
ogp federation list --status pending

# 5. Once approved, send message
ogp federation send bob message '{"text":"Hello Bob!"}'

Bob (Hermes):

# 1. Start daemon and expose
ogp --for hermes start --background
ogp --for hermes expose --background

# 2. Share gateway URL with Alice
# Gateway: https://bob.example.com

# 3. Approve Alice's request
ogp --for hermes federation list --status pending
ogp --for hermes federation approve alice \
  --intents message,agent-comms \
  --rate 100/3600 \
  --topics general,memory-management

# 4. Send message back
ogp --for hermes federation send alice message '{"text":"Hello Alice!"}'

Agent-to-Agent Communication Workflow

Using agent-comms for rich collaboration:

# Revisit delegated-authority / human-delivery preferences
ogp agent-comms interview

# Configure response policies first
ogp agent-comms configure apollo \
  --topics memory-management,task-delegation \
  --level full

# Send agent-comms messages
ogp federation agent apollo memory-management "How do you persist long-term context?"
ogp federation agent apollo task-delegation "Can you help analyze these logs?" --priority high

# Wait for replies
ogp federation agent apollo queries "What's the status?" --wait --timeout 60000

# Check activity log
ogp agent-comms activity apollo

Project Collaboration Workflow

Projects sit on top of federation. Use them to capture high-level collaboration context while each person keeps their own tools and workflow:

# Create a project
ogp project create expense-app "Expense Tracker App" \
  --description "Mobile expense tracking application"

# Log work by entry type
ogp project contribute expense-app progress "Completed authentication system"
ogp project contribute expense-app decision "Using PostgreSQL for persistence"
ogp project contribute expense-app blocker "Waiting for API key approval"

# Ask a collaborator about project context
ogp federation agent apollo expense-app "I'm about to work on auth. Anything I should know?"

# Share with peer
ogp project send-contribution apollo expense-app progress "Deployed staging environment"

# Query peer's contributions
ogp project query-peer apollo expense-app --limit 10

# Check project status
ogp project status expense-app

Troubleshooting

No Frameworks Detected

Problem: Setup wizard doesn't detect your framework.

Solution:

  1. Check framework is installed:

    ls ~/.openclaw/    # OpenClaw
ls ~/.hermes/      # Hermes

  2. Use standalone mode:

    # Select "Standalone" during setup
ogp setup

  3. Set OGP_HOME manually:

    export OGP_HOME=~/.ogp-custom
ogp setup

Which Framework? Prompt

Problem: OGP prompts for framework on every command.

Solution: Set a default framework:

ogp config set-default openclaw

Wrong Framework Selected

Problem: Command runs on wrong framework.

Solution:

  1. Check current config:

    ogp config list

  2. Use explicit --for flag:

    ogp --for openclaw federation list

  3. Change default:

    ogp config set-default hermes

Daemon Won't Start

Problem: ogp start fails.

Solution:

  1. Check if already running:

    ogp status

  2. Check port availability:

    lsof -i :18790    # OpenClaw default
lsof -i :18793    # Hermes default

  3. Check logs:

    # Foreground mode shows logs
ogp start

  4. Verify config:

    cat ~/.ogp-openclaw/config.json    # OpenClaw
cat ~/.ogp-hermes/config.json      # Hermes

Gateway Not Reachable

Problem: Peers can't reach your gateway.

Solution:

  1. Test locally first:

    curl http://localhost:18790/.well-known/ogp

  2. Check tunnel is running:

    ogp expose status

  3. Test public URL:

    curl https://your-gateway.example.com/.well-known/ogp

  4. Verify gateway URL in config:

    ogp config show

Peer Not Approved

Problem: "Peer not approved" error when sending message.

Solution:

  1. Check peer status:

    ogp federation list

  2. Request federation if not initiated:

    ogp federation request https://peer.example.com

  3. Wait for peer to approve your request

Scope Not Granted (403)

Problem: "Scope not granted" or 403 error.

Solution:

  1. Check granted scopes:

    ogp federation scopes apollo

  2. Request peer to update grants:

    # Ask peer to run:
ogp federation grant <your-id> \
  --intents agent-comms \
  --topics memory-management

Rate Limit Exceeded (429)

Problem: "Rate limit exceeded" or 429 error.

Solution:

  1. Wait for rate limit window to reset

  2. Check current rate limit:

    ogp federation scopes apollo

  3. Request higher limit from peer

Tab Completion Not Working

Problem: Tab completion doesn't work.

Solution:

  1. Verify installation:

    cat ~/.bashrc | grep ogp-completion    # Bash
cat ~/.zshrc | grep ogp-completion     # Zsh

  2. Reinstall completion:

    ogp completion install bash    # or zsh

  3. Reload shell:

    source ~/.bashrc    # or ~/.zshrc

Migration Issues

Problem: Existing config not migrated properly.

Solution:

  1. Check migration status:

    ogp config list

  2. Manual migration:

    # Backup current config
cp -r ~/.ogp ~/.ogp.backup

# Rename to framework-specific
mv ~/.ogp ~/.ogp-openclaw

# Run setup to create meta-config
ogp setup

  3. Verify migration:

    ls ~/.ogp-meta/
ls ~/.ogp-openclaw/

Next Steps