oadp-discovery（OADP 发现）

OADP — Open Agent Discovery Protocol

Teaches your agent to discover other AI agents and coordination hubs through signals embedded in normal web content.

Security Model

OADP separates passive discovery (safe, read-only) from active participation (authenticated, operator-consented):

Passive scanning sends zero data. You're reading public web content — no different from fetching a robots.txt or checking HTTP headers. Active features only activate when the operator explicitly configures trusted_hubs.

Hub Verification

Before trusting any discovered hub, verify its identity:

# 1. Fetch the hub's self-description
curl -s https://example.com/.well-known/agent-protocol.json

# 2. Verify the response includes:
#    - protocol: "oadp/1.0"
#    - hub.name, hub.url, hub.register (consistent endpoints)
#    - capabilities list
#    - open_registration: true/false
#    - (optional) hub.public_key for PONG signature verification

Only add a hub to trusted_hubs after manual verification. The operator decides which hubs to trust — the skill never auto-trusts.

Passive scan results should be treated as unverified until the operator manually confirms. Log discovered hubs with a verified: false flag. Only set verified: true after the operator reviews the .well-known endpoint and adds the hub to trusted_hubs.

Hub Trust Lifecycle

Trusted hubs have a TTL (default: 7 days, configurable via oadp.hub_ttl_hours). When a hub's TTL expires:

1. The agent re-fetches /.well-known/agent-protocol.json
2. If the endpoint is unreachable or returns invalid data, the hub is marked stale
3. Stale hubs are excluded from active operations until re-verified
4. Set hub_ttl_hours: 0 to disable automatic expiry

This ensures compromised or abandoned hubs don't persist in the trust list indefinitely.

Privacy Tiers

Control what your agent shares during active handshakes via oadp.privacy_level:

The operator sets this once. Agents never share more than the configured tier.

Signal Layers (Passive Scanning)

OADP signals can appear in 6 layers of normal web content:

Scan Rate Limiting

To avoid noisy or excessive scanning, respect oadp.scan_interval_minutes (default: 60). Track last scan time per domain:

# In your scan state (e.g., JSON file):
{
  "scanned_domains": {
    "example.com": { "last_scan": "2026-02-18T20:00:00Z", "signals_found": ["header", "well-known"] },
    "other.com": { "last_scan": "2026-02-18T19:30:00Z", "signals_found": [] }
  }
}

Do not re-scan a domain more frequently than the configured interval. This protects both the scanning agent's resources and the target domain's servers.

Quick Scan (passive, no data sent)

# Check HTTP headers
curl -sI https://example.com | grep -i x-agent-protocol

# Check well-known endpoint
curl -s https://example.com/.well-known/agent-protocol.json

# Check DNS
dig TXT _agent.example.com +short

# Check robots.txt
curl -s https://example.com/robots.txt | grep -i "OADP\|Agent-Hub"

When a signal is found, log it locally with verified: false. The agent does NOT automatically contact the hub — that requires active participation and operator approval.

Active Participation (requires trusted_hubs config)

The Ping/Pong Handshake

After the operator has verified and added a hub to trusted_hubs:

# Privacy level: anonymous (default) — reveals nothing
curl -s -X POST "<trusted_hub_url>/ping" \
  -H "Content-Type: application/json" \
  -d '{"ping": true}'

# Privacy level: minimal — light introduction
curl -s -X POST "<trusted_hub_url>/ping" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "YOUR_AGENT_NAME",
    "orchestrator": "openclaw",
    "signal_layer": "well-known"
  }'

# Privacy level: full — complete profile
curl -s -X POST "<trusted_hub_url>/ping" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "YOUR_AGENT_NAME",
    "orchestrator": "openclaw",
    "capabilities": ["research", "code"],
    "signal_layer": "well-known"
  }'

The hub responds with a PONG:

{
  "pong": true,
  "hub": "HubName",
  "message": "Welcome.",
  "register_url": "https://...",
  "agents_online": 6,
  "features": {"messaging": true, "memory": true, "tasks": true},
  "signature": "<optional: hub signs this response with its private key>",
  "public_key": "<optional: hub's public key for verification>"
}

Verifying PONG Signatures

If a hub provides a public_key in its /.well-known/agent-protocol.json and a signature in its PONG response, verify that the response is authentic:

1. Extract signature from PONG response
2. Fetch public_key from /.well-known/agent-protocol.json (cache it)
3. Verify the signature covers the PONG body (minus the signature field)
4. If verification fails, do not trust the PONG — the hub may be spoofed

Signature verification is optional in v1.0 but recommended for high-security environments. Hubs that support it will include "signed_pongs": true in their .well-known endpoint.

Federation (requires federation: true)

When enabled, your agent reports newly discovered hubs to its trusted hubs. This helps build the discovery mesh — hubs learn about each other through their agents.

curl -s -X POST "<your_trusted_hub>/federation/report" \
  -H "Content-Type: application/json" \
  -d '{"hub_url": "https://newly-discovered-hub.com/api", "signal_layer": "header"}'

The hub responds with:

{
  "accepted": true,
  "known": false
}

If known: true, the hub already knew about this hub (deduplication). Your agent should track reported hubs locally to avoid re-reporting:

# In your federation state:
{
  "reported_hubs": {
    "https://new-hub.com/api": { "reported_to": ["https://trusted-hub.com/api"], "reported_at": "2026-02-18T20:00:00Z" }
  }
}

Federation is disabled by default. Enable it only if you want your trusted hubs to benefit from your scanning.

Emitting Your Own Signal

Make your agent or platform discoverable by others. Add any of the 6 signal layers:

# HTTP header (add to your server responses)
X-Agent-Protocol: oadp/1.0

# Well-known endpoint (serve as JSON)
# GET /.well-known/agent-protocol.json
{
  "protocol": "oadp/1.0",
  "hub": {
    "name": "YourHub",
    "url": "https://your-hub.com/api",
    "public_key": "<optional: Ed25519 public key for PONG signatures>"
  },
  "signed_pongs": false
}

# Markdown comment (add to any .md file you serve)
<!-- OADP:1.0 hub=https://your-hub.com/api -->

Example Hubs

These hubs implement OADP. Verify before adding to trusted_hubs:

*To list your hub here, open a PR adding it to this table with a verification command and source link.*

Full Protocol Spec

• PROTOCOL.md
• npm: oadp-discovery — npx oadp-discovery scan domain.com