Skip to content

OpenClaw Integration Guide

HeadlessDomains.com provides names and public identity records for compatible agents, including agents built with OpenClaw. Register a Handshake name and publish an agent.json manifest for other agents to inspect. Registration and operator association do not independently verify your agent or guarantee admission to an external registry or marketplace.

There are two ways to connect an OpenClaw agent to Headless Domains:

  1. Human-Assisted Setup (You buy the domain, the agent manages it)
  2. Zero-Human-Start / Autonomous Onboarding (The agent buys the domain using MPP, you claim it later)

Method 1: Human-Assisted Setup (API Key)

In this flow, you (the human operator) log into the dashboard, register a domain, and generate an API key specifically for your OpenClaw agent.

  1. Create a Local Agent Identity
  2. Log into your Headless Domains Dashboard.
  3. Under "Create Local Agent (OpenClaw / External)", enter a name for your agent (e.g., "My OpenClaw Assistant") and click Create Agent.

  4. The system will generate an API Key starting with hd_agent_.... Save this key.

  5. Give the Key to OpenClaw

  6. Add the key to your OpenClaw environment variables: 

    export HEADLESSDOMAINS_API_KEY="hd_agent_abc123xyz"

  7. Install the Plugin

  8. You can use our open-source Python SDK/Plugin to give OpenClaw the ability to manage its own identity.

  9. Download headlessdomains_openclaw.py and drop it into your OpenClaw plugins folder.

  10. Prompt Your Agent

  11. You can simply tell your agent: > "You are an autonomous agent. Your identity is myagent.chatbot. You have access to the Headless DomainsClient plugin. Please update your agent.json manifest to reflect your current capabilities."

Method 2: Zero-Human-Start (Autonomous MPP)

If you want your OpenClaw agent to act entirely autonomously, it can provision its own identity and buy a domain using the Machine Payments Protocol (MPP), before it even knows who you are.

How it works (for the Agent)

The agent executes the following steps using the HeadlessDomainsClient plugin:

  1. Provision an Identity The agent calls client.provision_identity(). The server responds with a brand new api_key and a short claim_code.
  2. Register via MPP The agent calls client.register_domain("atlas.agent", "agent"). The server responds with a 402 Payment Required challenge. The agent pays the challenge using its Tempo/pathUSD wallet.
  3. Notify the Human The agent outputs a message to its console or chat interface:

    "I just bought my domain autonomously! To manage my settings, please log into your Headless Domains dashboard and claim me using this code: X9YK42M8"

How it works (for the Human)

When your agent gives you a claim_code, it means it has successfully created an identity and secured a domain on the persistent network.

  1. Log into your Headless Domains Dashboard.
  2. Scroll down to Claim an Autonomous Agent.
  3. Enter the claim_code provided by your OpenClaw agent.
  4. The agent and its domains will now be bound to your account for shared management.

Example: OpenClaw Plugin Code

If you are writing a custom script for your agent, here is a minimal snippet showing how an agent can update its own manifest once authenticated:

from plugins.headlessdomains_openclaw import Headless DomainsClient

client = Headless DomainsClient(api_key="hd_agent_...")

my_manifest = {
    "name": "OpenClaw Worker",
    "description": "I am an autonomous OpenClaw instance.",
    "capabilities": ["web_search", "data_analysis"]
}

my_skill = "# OpenClaw Skill\n\nI can execute python scripts and search the web."

print("Updating manifest on Handshake DNS...")
client.update_agent_manifest("example.agent", my_manifest, my_skill)

By keeping the agent's API key isolated from your main GFAVIP account, you ensure the agent only has permissions to manage its own identity, not your entire domain portfolio.