IdentyClaw OpenClaw Plugin

OpenClaw code plugin that exposes IdentyClaw HTTP API endpoints as agent tools: discovery, Passport identity, API session login, HOLA create/verify, subagent delegation, DID resolution, and MCP-style documentation resources.

Complementary artifacts (from OpenClaw integration guide):

Two lanes — do not mix them

IdentyClaw uses two separate authentication mechanisms. This plugin implements both, but they are not interchangeable.

Two clocks (from hola-howto.md):

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:

What this plugin does

• Public tools — no API session: list agents, list/fetch MCP resources.
• API session tools — auto-login (or env-provided bearer token), then call protected routes: identity, agent lookup, DID resolve, subagent signer check.
• HOLA tools — require API session plus HOLA protocol steps: fetch nonce, sign a line locally (identyclaw_create_hola), or submit a peer line to POST /api/identity/verify (identyclaw_verify_hola).

The plugin auto-logins when protected tools run: GET /api/login/timestamp → sign login payload → POST /api/login → cache jwt_token until near expiry; applies New-Token response headers when present.

nearPrivateKey on the Gateway host is used for two different signatures (same NEAR key, different messages and 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.

NEAR account generation (v1.5.0+)

Create a NEAR implicit account without installing the gennearaccount C binary. 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.

Operator CLI (recommended)

From a plugin checkout:

npm run generate-near-account -- /path/to/secrets/near-credentials
# or default: ./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.

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.

Install

From ClawHub (after npm run prepare:publish for local paths):

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

Local checkout:

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

Enable optional tools in OpenClaw config:

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

Configuration

Deprecated config alias: roditid → use accountid.

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).

Tools

Public (no API session)

API session only

Requires auto-login or IDENTYCLAW_JWT. No HOLA line involved.

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 hola-agent-authentication.md § When is a HOLA validated?.

Typical flows

1. API login only (identity / discovery)

accountid + nearPrivateKey  →  POST /api/login  →  jwt_token
jwt_token  →  GET /api/me/identity, GET /api/agents, …

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 (requires ../idclawserver-idc/references or IDENTYCLAW_REFERENCES):

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

Further reading (IdentyClaw server)

License

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