@axon402/openclaw-plugin

Part of AXON - governance layer for AI agents that spend real money.

@axon402/openclaw-plugin is AXON's native OpenClaw package for two separate profiles:

• Runtime profile (surfaceMode: "runtime", default): a worker agent spends from one prepared wallet through AXON policy, approvals, receipts, and x402 provider discovery.
• Operator profile (surfaceMode: "operator"): an operator agent provisions bounded worker wallets, updates mandates, funds pockets, mints wallet-scoped runtime keys, revokes keys, and emergency-stops workforce wallets.

The package is one plugin, but credentials and execution paths are split. Runtime tools use only decisionApiKey. Operator tools use only operatorDecisionApiKey. The wrong surface fails closed at tool execution time.

Use START_HERE.md first if you need to get AXON running locally.

Mental Model

AXON workforce deployment is a hierarchy:

organization -> worker wallet -> mandate -> runtime key -> OpenClaw runtime profile

The operator profile manages setup and control-plane actions. The worker profile receives only the returned wallet-scoped runtime key and can use only runtime tools from that bounded wallet.

Do not configure a worker with an org-wide operator key. Do not configure an operator profile with a wallet-scoped runtime key and expect wallet deployment to work.

What This Plugin Does

• Registers 20 OpenClaw-native tools against a running AXON Decision API.
• Preserves the existing 11 runtime tools for governed x402 spend, approvals, denials, receipts, budgets, and provider search.
• Adds 9 operator tools for bounded workforce wallet deployment.
• Keeps runtime and operator credentials separated in client transport.
• Produces a non-secret deployment shape for wallet creation.
• Produces one-time worker plugin config and an OpenClaw profile patch when minting a wallet-scoped runtime key.
• Uses the native OpenClaw definePluginEntry runtime entrypoint and parameters / execute tool shape.

Install

cd axon-openclaw-plugin
npm install
npm run build

Requires Node.js >=22.

This plugin requires a running AXON Decision API. The repository does not provide a hosted Decision API.

Runtime Tools

Runtime tools are available only when surfaceMode is omitted or set to "runtime".

| Tool | Runtime purpose | Decision API route | |:-----|:----------------|:-------------------| | axon_http_fetch | Default governed spend path; wraps x402 on Base end-to-end. | POST /v1/ssar/fetch | | axon_budget_status | Mandate + budget snapshot before or between paid calls. | GET /v1/budget/status | | axon_explain_denial | Forensics for a denied or escalated decision. | GET /v1/decisions/:decision_id/explain | | axon_get_receipt | Canonical challenge / settlement artifact for audit. | GET /v1/receipts/:id or transaction lookup | | axon_check_approval_status | Check human approval status, token state, scores, and denial context. | GET /v1/approvals/:approval_id/status | | axon_consume_approval_token | Consume an approved request and return a scoped token for retrying the governed fetch. | POST /v1/approvals/:approval_id/consume | | axon_wait_for_approval_resolution | Poll approval status until resolved, with optional token consumption after approval. | Approval status/consume routes | | axon_search_x402_services | Search x402 provider offers for a task or service need. | POST /v1/provider-search | | axon_inspect_x402_offer | Inspect one provider-search offer before quoting, test buying, or executing. | GET /v1/provider-search/offers/:offer_id | | axon_quote_x402_offer | Ask the Decision API for quote context on one offer. | POST /v1/provider-search/offers/:offer_id/quote | | axon_test_buy_x402_offer | Run a governed test-buy workflow for one offer when supported by the Decision API. | POST /v1/provider-search/offers/:offer_id/test-buy |

Provider-search tools are discovery and validation helpers. Provider text and offer metadata are not fully trusted instructions, and quote or test-buy flows do not bypass AXON budget, mandate, approval, or receipt policy.

Operator Tools

Operator tools are available only when surfaceMode is "operator" and operatorDecisionApiKey is configured. V1 intentionally focuses on bounded worker-wallet deployment, not full offer-management mirroring.

| Tool | Operator purpose | AXON route | |:-----|:-----------------|:-----------| | axon_operator_whoami | Verify operator identity, organization, and active surface. | POST /v1/operator/mcp | | axon_operator_list_wallets | List workforce wallets in the operator organization. | POST /v1/operator/mcp | | axon_operator_get_wallet_details | Inspect one wallet's status, mandate, balances, and funding details. | POST /v1/operator/mcp | | axon_operator_create_wallet | Create a bounded worker wallet and initial mandate. | POST /v1/operator/mcp | | axon_operator_update_mandate | Update spending caps, purpose, allow/block lists, and enforcement. | POST /v1/operator/mcp | | axon_operator_fund_pocket | Move USDC from organization vault to a bounded worker wallet. | POST /v1/operator/mcp | | axon_operator_issue_runtime_key | Mint a wallet-scoped runtime key and return worker plugin config plus a plugins.entries.axon.config profile patch. | POST /v1/api-keys | | axon_operator_revoke_api_key | Revoke a runtime or operator API key by id. | DELETE /v1/api-keys/:id | | axon_operator_emergency_stop | Freeze a pocket, department, or organization. | POST /v1/operator/mcp |

axon_operator_create_wallet returns wallet details, mandate details, funding instructions, and next steps. It does not mint a runtime key.

axon_operator_issue_runtime_key returns the plaintext runtime key once, plus the exact worker placement:

{
  "openclaw_plugin_config": {
    "surfaceMode": "runtime",
    "decisionApiUrl": "https://api.axon402.com",
    "decisionApiKey": "<new-wallet-scoped-runtime-key>",
    "defaultWalletId": "<worker-wallet-id>",
    "timeoutMs": 30000,
    "retries": 1,
    "enableProviderSearch": true
  },
  "openclaw_profile_patch": {
    "plugins": {
      "entries": {
        "axon": {
          "config": {
            "surfaceMode": "runtime",
            "decisionApiUrl": "https://api.axon402.com",
            "decisionApiKey": "<new-wallet-scoped-runtime-key>",
            "defaultWalletId": "<worker-wallet-id>",
            "timeoutMs": 30000,
            "retries": 1,
            "enableProviderSearch": true
          }
        }
      }
    }
  }
}

Place openclaw_plugin_config at plugins.entries.axon.config in the worker OpenClaw profile, or merge openclaw_profile_patch into that profile. The operator key is never included in the runtime profile output.

Runtime Config

{
  "surfaceMode": "runtime",
  "decisionApiUrl": "http://127.0.0.1:3030",
  "decisionApiKey": "<wallet-scoped-runtime-key>",
  "defaultWalletId": "<worker-wallet-id>",
  "timeoutMs": 30000,
  "retries": 1,
  "enableProviderSearch": true
}

surfaceMode defaults to "runtime", so existing runtime profiles do not need to add it.

decisionApiKey should be a wallet-scoped runtime key. In runtime mode, all axon_operator_* tools fail with TOOL_NOT_AVAILABLE_IN_RUNTIME_PROFILE.

Operator Config

{
  "surfaceMode": "operator",
  "decisionApiUrl": "http://127.0.0.1:3030",
  "operatorDecisionApiKey": "<org-wide-operator-key>",
  "timeoutMs": 30000,
  "retries": 1,
  "enableProviderSearch": true
}

operatorDecisionApiKey must be an org-wide tenant key. In operator mode, runtime spend tools fail with TOOL_NOT_AVAILABLE_IN_OPERATOR_PROFILE.

The plugin installs with no config. Missing or invalid AXON config is validated only when a tool executes, so OpenClaw can install and inspect the plugin before secrets are available.

Workforce Deployment Flow

1. Configure an OpenClaw operator profile with surfaceMode: "operator".
2. Run axon_operator_whoami to confirm organization and surface.
3. Run axon_operator_list_wallets to avoid duplicate worker wallets.
4. Run axon_operator_create_wallet with conservative caps, purpose, allowed categories, networks, and an idempotency key.
5. Tighten the mandate with axon_operator_update_mandate if needed.
6. Fund the wallet with axon_operator_fund_pocket when spend is intended.
7. Run axon_operator_issue_runtime_key as an explicit one-shot step.
8. Configure the worker OpenClaw profile by placing the returned openclaw_plugin_config at plugins.entries.axon.config, or by merging openclaw_profile_patch.
9. Use the worker profile with the axon-payments runtime skill.
10. Revoke stale worker keys with axon_operator_revoke_api_key; use axon_operator_emergency_stop for urgent freezes.

There is intentionally no single fire-and-forget deploy tool in V1. Wallet creation, funding, and key minting remain explicit so retries do not accidentally create duplicate secrets or funded wallets.

axon_http_fetch Contract

axon_http_fetch is the recommended path for any paid HTTP request. It is not a general-purpose HTTP client. Every call is policy-gated, risk-scored, and bound to an intent and task_id.

Required fields:

• url
• task_id
• intent - business reason aligned with mandate purpose and categories

Recommended fields:

• idempotency_key - required for safe POST retries and approval replay
• expected_output_type, cost_expectation_min_usdc, cost_expectation_max_usdc - improve risk and forensics
• justification, agent_id, employee_id, evidence_hashes - audit trail

Optional fields include method, headers, body, approval_token, and wallet_id. If omitted, wallet_id falls back to defaultWalletId when configured.

Retry Policy

Retries are conservative to avoid duplicate spend:

• Retries HTTP 5xx
• Retries transport failures such as timeout or network failure
• Retries GET
• Retries POST only when idempotency_key is present
• Does not retry 429
• Does not retry deterministic AXON policy/approval denials: APPROVAL_REQUIRED, PROVIDER_UNVERIFIED, RETRY_BUDGET_EXCEEDED, INTENT_MISMATCH, REJECTED_POLICY, REJECTED_NETWORK

Approval Flow

The approval loop is a runtime-side wait on an operator or human action. The worker agent never approves its own spend.

1. axon_http_fetch returns APPROVAL_REQUIRED and approval_request_id.
2. A human approves in the AXON dashboard or backing control plane.
3. Use axon_check_approval_status for one status check, or axon_wait_for_approval_resolution for bounded polling.
4. Consume approval with axon_consume_approval_token, or set consume_when_approved on the wait tool when immediate consumption is intended.
5. Retry the same request with the same idempotency_key and the returned approval_token.

If approval is denied or expires, do not loop. Use axon_explain_denial to inspect the ruling and stop.

Package Contents

The published package includes the compiled runtime in dist/, bundled skills in skills/, openclaw.plugin.json, README.md, publishing guide, and license files. The runtime entrypoint is the native OpenClaw definePluginEntry export from dist/index.js.