IdentyClaw Tools Gateway Component

OpenClaw plugin — IdentyClaw API login, HOLA, identity, and DID tools

IdentyClaw — portable cryptographic identity for AI agents. Mint a Passport on NEAR, prove yourself with HOLA, and use the IdentyClaw API when you need it.

IdentyClaw component service: OpenClaw plugin that exposes the IdentyClaw HTTP API as agent tools — discovery, Passport identity, API session login, HOLA create/verify, subagent delegation, DID resolution, and MCP-style documentation resources. API login and HOLA flows follow the live API contract (via vendored @rodit/hola-client for HOLA signing). Protocol docs: MCP discovery · OpenAPI · doc:reference:openclaw-integration-guide.

[!IMPORTANT] Production deploy: For nginx TLS, A2A peer messaging, signed webhooks, and GitHub Actions CI, use identyclaw-agents instead of wiring plugins manually on the gateway host.

Quick start

Four steps to go from zero to a Passport-enrolled gateway (à la carte install — see the production callout above for the full stack template):

openclaw plugins install clawhub:@identyclaw/openclaw-identyclaw-plugin
openclaw gateway restart
identyclaw-generate-near-account

Purchase a Passport at purchase.identyclaw.com for the printed implicit_account_id, then restart the gateway so bootstrap syncs IDENTYCLAW_* into plugin config. On first startup with no credentials yet, the plugin can also auto-generate a NEAR account (ClawHub-safe — OpenClaw skips npm lifecycle scripts).

Details: Installation · NEAR account generation · Configuration · Tools

Role in the IdentyClaw stack

Install this plugin when Passport-authenticated agents need IdentyClaw API login, HOLA peer trust, identity discovery, or DID resolution — not for A2A peer messaging (use identyclaw-a2a for that). NEAR Passport credentials use the gennearaccount JSON layout under secrets/near-credentials/ — same as identyclaw-agents bootstrap.

Your agent gets identyclaw_* tools for IdentyClaw HTTP without hand-rolling login signatures or HOLA lines:

• identyclaw_ensure_session / identyclaw_list_sessions for multi-API JWT sessions (home + federated)
• identyclaw_request for generic authenticated HTTP (method + path + optional apiEndpoint) — peer product routes live in that peer’s skill, not as plugin-specific tools
• identyclaw_list_agents / identyclaw_list_resources / identyclaw_get_resource for public discovery and MCP docs
• identyclaw_get_my_identity / identyclaw_get_agent_identity / identyclaw_resolve_did for Passport identity
• identyclaw_get_nonce / identyclaw_create_hola / identyclaw_verify_hola for HOLA peer authentication
• identyclaw_check_subagent_signer for delegation authorization checks
• identyclaw_generate_near_account (optional) for operator NEAR account creation on the gateway host

The plugin auto-logins when protected tools run: GET /api/login/timestamp → sign login payload → POST /api/login → cache jwt_token per API URL until near expiry; applies New-Token response headers when present. Pass optional apiEndpoint to target a federated peer (e.g. https://api-b.example.com) while keeping the home session. Agents should call tools — not invent curl login.

A2A P2P (send/receive with other agents) is a separate plugin: openclaw-a2a-idc-plugin (identyclaw-a2a). That component owns per-peer JWTs; this plugin owns IdentyClaw HTTP API + HOLA.

📦 Installation

From ClawHub:

openclaw plugins install clawhub:@identyclaw/openclaw-identyclaw-plugin

From npm:

openclaw plugins install @identyclaw/openclaw-identyclaw-plugin

Local checkout (after npm run prepare:publish):

openclaw plugins install /path/to/openclaw-identyclaw-plugin

Restart the gateway:

openclaw gateway restart

Enable optional tools in OpenClaw config (see Configuration and Tools):

{
  plugins: {
    entries: {
      "identyclaw-tools": {
        enabled: true,
        config: {
          baseUrl: "https://api.identyclaw.com",
          apiEndpoints: ["https://api-b.example.com"],
          accountid: "<64-char-hex-near-implicit-account>",
          nearPrivateKey: "ed25519:..."
        }
      }
    }
  },
  tools: {
    allow: [
      "identyclaw_ensure_session",
      "identyclaw_list_sessions",
      "identyclaw_get_my_identity",
      "identyclaw_get_nonce",
      "identyclaw_create_hola",
      "identyclaw_verify_hola",
      "identyclaw_get_agent_identity",
      "identyclaw_check_subagent_signer",
      "identyclaw_resolve_did"
    ]
  }
}

Related IdentyClaw artifacts

identyclaw-tools and identyclaw-a2a can share IDENTYCLAW_ACCOUNT_ID, IDENTYCLAW_NEAR_PRIVATE_KEY, and IDENTYCLAW_BASE_URL. Optional IDENTYCLAW_API_ENDPOINTS (comma-separated) lists federated HTTP APIs for this plugin. HOLA stays application-layer via identyclaw_* tools; A2A peer calls use separate per-peer Passport JWTs through the A2A component (login_server / P2P — not the central API session cache here).

🔐 Two lanes — do not mix them

IdentyClaw uses two separate authentication mechanisms. This plugin implements both, but they are not interchangeable. Vocabulary: doc:reference:login-authentication vs doc:reference:hola-authentication.

Two clocks (from doc:reference:hola-howto):

A JWT is not a HOLA line. HOLA tools need an API session only so the plugin can call protected endpoints (/api/holanonce16ts, /api/identity/verify, …). The peer handshake itself is the HOLA line you send or verify.

Timestamp endpoints are different:

nearPrivateKey on the Gateway host

The same NEAR key signs two different messages (different encodings):

1. API login — UTF-8 accountid + timestamp_iso → base64url signature on POST /api/login.
2. HOLA create — uppercase canonical HOLA prefix → base32 line signature (via @rodit/hola-client). Never sent to HTTP endpoints except inside the finished HOLA string you deliver to peers or verify endpoints.

identyclaw_verify_hola does not need nearPrivateKey — only an API session and the peer's HOLA line.

Keep credentials in env or secrets files — not in openclaw.json.

🔑 NEAR account generation (v1.5.0+)

Create a NEAR implicit account with the Node CLI or optional agent tool in this plugin. Credentials are written as gennearaccount-compatible JSON under secrets/near-credentials/<implicit_account_id>.json (directory mode 0700, file mode 0600). Private keys never appear in tool output or chat — only implicit_account_id and public_key are returned.

On hosts without Node, build and run gennearaccount instead — the C CLI writes the same JSON credential layout to secrets/near-credentials/.

Operator CLI (recommended)

From a plugin checkout or after install:

npm run generate-near-account -- /path/to/secrets/near-credentials
# installed package:
identyclaw-generate-near-account /path/to/secrets/near-credentials
# default when installed: ~/.openclaw/secrets/near-credentials
# default in checkout: ./secrets/near-credentials
# env: IDENTYCLAW_NEAR_CREDENTIALS_DIR

Example (identyclaw-agents layout):

npm run generate-near-account -- ~/identyclaw-agents-app/agents/agent-a/secrets/near-credentials

Then purchase a Passport at https://purchase.identyclaw.com for the printed account id, restart the gateway (or ./identyclaw.sh restart agent-a) so bootstrap syncs IDENTYCLAW_* into .env and plugin config.

On first gateway startup after install, the plugin also bootstraps a NEAR account when accountid / nearPrivateKey are unset and no credential JSON exists yet (disable with generateNearAccountOnInstall: false). OpenClaw plugin installs skip npm lifecycle scripts, so this startup bootstrap is the ClawHub-safe install path.

Optional agent tool

Allowlist identyclaw_generate_near_account for advanced setups. Output path must end with secrets/near-credentials or appear in nearCredentialsOutputDirs:

{
  plugins: {
    entries: {
      "identyclaw-tools": {
        config: {
          generateNearAccountDefaultDir: "/home/node/.openclaw/secrets/near-credentials",
          nearCredentialsOutputDirs: []
        }
      }
    }
  },
  tools: {
    allow: ["identyclaw_generate_near_account"]
  }
}

Returns: implicit_account_id, public_key, filePath — not private_key.

💡 Use Cases

• Obtain and refresh IdentyClaw API sessions from OpenClaw without custom login code
• Prove Passport identity to peers with outbound HOLA lines and verify inbound peer HOLA
• Look up agent identity, DID documents, and subagent signer authorization from chat
• Bootstrap NEAR implicit accounts and credential files on gateway hosts (identyclaw-agents layout)
• Fetch MCP documentation resources (doc:*) for operator workflows alongside the ClawHub skill
• Pair with identyclaw-a2a on the same host — shared NEAR creds, separate auth lanes (HOLA vs A2A JWT)

✨ Features

• Public discovery tools — list agents and MCP resources without an API session
• Multi-API auto-login — protected tools trigger POST /api/login with Ed25519 signing; JWT cache per API URL (home + federated) with New-Token refresh
• Session tools — identyclaw_ensure_session / identyclaw_list_sessions so agents never hand-roll login
• Federated claim check — validates rodit_subjectuniqueidentifier_url / iss when logging into a non-home API (aligned with @rodit/rodit-auth-be ≥9.13)
• HOLA create and verify — nonce fetch, local base32 signing (identyclaw_create_hola), server-side peer verification (identyclaw_verify_hola)
• Identity and DID — identyclaw_get_my_identity, per-token lookup, did:rodit resolution
• Subagent delegation — identyclaw_check_subagent_signer against POST /api/isauthorizedsigner
• NEAR account generation — CLI and optional tool; startup bootstrap on first install when creds are missing
• Vendored HOLA client — @rodit/hola-client ships in the published package (ClawHub-safe file: dependency)
• Optional tool rollout — sensitive tools off by default; allowlist in OpenClaw config for safer deployment

⚙️ Configuration

Deprecated config alias: roditid → use accountid.

Most HTTP tools accept optional apiEndpoint. Federation shares Rodit login only — a federated peer may expose arbitrary product routes and need not implement home IdentyClaw paths (/api/me/identity, HOLA, DID, …). For federated product work: identyclaw_ensure_session → discover → identyclaw_request. Keep Passport/HOLA/DID tools on the home baseUrl unless you know the peer is a full IdentyClaw replica.

For smoke tests you may pass a pre-obtained API bearer token instead of login bootstrap:

• IDENTYCLAW_JWT — full jwt_token from POST /api/login (not a HOLA line). Runtime plugin tools do not read this env; they always auto-login from Passport credentials.

🧰 Tools

Sessions (multi-API)

Public (no API session)

API session only

Requires auto-login (Passport credentials). No HOLA line involved. Optional apiEndpoint per call.

HOLA protocol

Requires API session. Create also requires nearPrivateKey on the Gateway.

Account generation (no API session)

Optional tools are off by default in the manifest; allowlist them in OpenClaw config for safer rollout.

Trust note: Treat a peer as authenticated only after identyclaw_verify_hola returns a successful verification outcome — not from checksum or signature checks alone. See doc:reference:hola-authentication (section When is a HOLA validated?) or verify.identyclaw.com.

🔄 Typical flows

1. API login only (identity / discovery)

accountid + nearPrivateKey  →  auto POST /api/login (per apiEndpoint)  →  cached jwt_token
identyclaw_ensure_session
identyclaw_get_my_identity          # home baseUrl (omit apiEndpoint)

1b. Federated product peer

identyclaw_ensure_session({ apiEndpoint })   # Rodit login only
identyclaw_list_resources / get_resource     # discover peer surface
identyclaw_request({ method, path, apiEndpoint })  # arbitrary peer routes
# Do NOT call identyclaw_get_my_identity against the federated host

Federated example: keep home session on baseUrl for Passport/HOLA; open a second session for the peer and call that peer’s paths via identyclaw_request.

2. Outbound HOLA (intro to a peer)

jwt_token  →  GET /api/holanonce16ts  →  noncetsHex, timestamp
nearPrivateKey  →  sign canonical HOLA prefix  →  HOLA line
HOLA line  →  deliver to peer (out of band)

Self-test: POST /api/testhola with your line (smoke script covers this when credentials are set).

3. Inbound HOLA (verify a peer)

Peer sends HOLA line  →  identyclaw_verify_hola  →  POST /api/identity/verify
(your API session JWT authorizes the verify call; the HOLA line is the payload)

🛠️ Development

Node ≥ 22.19 (see .nvmrc). From repository root:

npm install
npm run prepare:publish   # build + sync openclaw.plugin.json + validate
npm run smoke:test:mock   # CI-style, no network
npm run smoke:test        # public API; optional API session + HOLA round-trip

Smoke — API session (pick one):

# Pre-issued bearer token from POST /api/login
IDENTYCLAW_JWT="<jwt_token>" npm run smoke:test

# Or login bootstrap (same signing as plugin auto-login)
IDENTYCLAW_ACCOUNT_ID="<hex>" IDENTYCLAW_NEAR_PRIVATE_KEY="ed25519:..." npm run smoke:test

When both API session and IDENTYCLAW_NEAR_PRIVATE_KEY are set, smoke runs create HOLA → POST /api/testhola.

Individual steps:

npm run build
npm run plugin:build
npm run plugin:validate

Publish to ClawHub

Plugin — see PUBLISH.md:

npm run publish:clawhub:dry-run
npm run publish:clawhub

Skill — see skill/PUBLISH.md (references synced from MCP at publish time or set IDENTYCLAW_REFERENCES):

npm run skill:sync
npm run skill:publish:dry-run
npm run skill:publish

Further reading (API docs)

Fetch any resource with identyclaw_get_resource, curl https://api.identyclaw.com/api/mcp/resource/{uri}, or browse MCP discovery.

📄 License

MIT-0 (MIT No Attribution). ClawHub-published releases follow registry terms on clawhub.ai.

🔗 IdentyClaw & upstream links

discernible.io · sdk monorepo · A2A plugin · webhooks plugin · API docs (MCP) · verify HOLA

• This repo: discernible-io/openclaw-identyclaw-plugin
• Production template: discernible-io/identyclaw-agents — nginx TLS, A2A, webhooks, CI
• API contract: api.identyclaw.com/.well-known/mcp — JWT, HOLA, enrollment, OpenClaw integration guides
• A2A component: discernible-io/openclaw-a2a-idc-plugin — Passport JWT peer messaging (a2a_* tools)
• Webhooks component: discernible-io/openclaw-identyclaw-webhooks-plugin — RODiT-signed ingress on /hooks/wake and /hooks/agent
• NEAR account CLI (C): discernible-io/gennearaccount — same JSON output as identyclaw-generate-near-account
• ClawHub skill: clawhub.ai/identyclaw/identyclaw
• ClawHub plugin: clawhub.ai/plugins/@identyclaw/openclaw-identyclaw-plugin

Suggested GitHub About metadata