> ## Documentation Index
> Fetch the complete documentation index at: https://docs.axon402.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# OpenClaw Plugin

> AXON OpenClaw profiles for operator-led worker wallet deployment and runtime governed spend.

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

* **Operator profile**: provisions bounded worker wallets and hands out
  wallet-scoped runtime profiles.
* **Runtime profile**: lets a worker spend only from its prepared wallet
  through AXON policy, approval, receipt, and x402 provider-search flows.

> [!NOTE]
>
> One plugin package exposes both surfaces, but one OpenClaw profile should
> run only one surface at a time. Operator tools use
> `operatorDecisionApiKey`. Runtime tools use `decisionApiKey`. The
> plugin fails closed if a tool is called from the wrong `surfaceMode`.

## Mental model

AXON workforce deployment is a hierarchy:

```text theme={null}
organization -> worker wallet -> mandate -> runtime key -> OpenClaw runtime profile
```

The operator profile controls the organization and deploys bounded worker
wallets. The worker receives only a wallet-scoped runtime key and a
runtime OpenClaw profile.

## Runtime tools

Use these from `surfaceMode: "runtime"` profiles.

| Tool | Runtime purpose | Decision API route |
| :- | :- | :- |
| `axon_http_fetch` | Governed HTTP request; default 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` | Single approval status check after an escalation. | `GET /v1/approvals/:approval_id/status` |
| `axon_consume_approval_token` | Consume a human-approved approval token for the retry. | `POST /v1/approvals/:approval_id/consume` |
| `axon_wait_for_approval_resolution` | Bounded polling until approval, denial, expiry, or timeout. | Approval status/consume routes |
| `axon_search_x402_services` | Discover x402 services through AXON provider search. | `POST /v1/provider-search` |
| `axon_inspect_x402_offer` | Inspect a specific provider-search offer. | `GET /v1/provider-search/offers/:offer_id` |
| `axon_quote_x402_offer` | Request a quote for a candidate offer. | `POST /v1/provider-search/offers/:offer_id/quote` |
| `axon_test_buy_x402_offer` | Run a governed test-buy probe for a candidate offer. | `POST /v1/provider-search/offers/:offer_id/test-buy` |

## Operator tools

Use these from `surfaceMode: "operator"` profiles.

| 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 OpenClaw worker 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` |

> [!WARNING]
>
> `axon_operator_issue_runtime_key` returns the plaintext runtime key once.
> Store it immediately and configure only the intended worker by placing
> `openclaw_plugin_config` at `plugins.entries.axon.config`, or by
> merging `openclaw_profile_patch`. The operator key is never included
> in that output.

## Installation

```bash theme={null}
cd axon-openclaw-plugin
npm install
npm run build
```

> [!NOTE]
>
> This plugin talks to the AXON Decision API over ordinary HTTP. For
> production, point it at the hosted API base URL `https://api.axon402.com`.
> For local development, point it at your own daemon such as
> `http://127.0.0.1:3030`.

## Runtime configuration

```json theme={null}
{
  "surfaceMode": "runtime",
  "decisionApiUrl": "https://api.axon402.com",
  "decisionApiKey": "your-wallet-scoped-runtime-key",
  "defaultWalletId": "worker-wallet-id",
  "timeoutMs": 30000,
  "retries": 1,
  "enableProviderSearch": true
}
```

`surfaceMode` defaults to `"runtime"`.

| Field | Type | Default | Description |
| :- | :- | :- | :- |
| `surfaceMode` | string | `runtime` | `runtime` for worker profiles or `operator` for workforce deployment profiles |
| `decisionApiUrl` | string | - | Base URL of the AXON Decision API. Do not append `/v1/mcp`. |
| `decisionApiKey` | string | - | Wallet-scoped runtime key used only by runtime tools |
| `defaultWalletId` | string | - | Fallback wallet ID used when runtime tool calls omit `wallet_id` |
| `timeoutMs` | number | `30000` | Request timeout in milliseconds |
| `retries` | number | `1` | Number of retry attempts |
| `enableProviderSearch` | boolean | `true` | Metadata hint for x402 provider-search support. It does not hide tools or grant spend authority. |

## Operator configuration

```json theme={null}
{
  "surfaceMode": "operator",
  "decisionApiUrl": "https://api.axon402.com",
  "operatorDecisionApiKey": "your-org-wide-operator-key",
  "timeoutMs": 30000,
  "retries": 1,
  "enableProviderSearch": true
}
```

| Field | Type | Description |
| :- | :- | :- |
| `surfaceMode` | string | Must be `operator` |
| `decisionApiUrl` | string | Base URL of the AXON Decision API |
| `operatorDecisionApiKey` | string | Org-wide operator key used only by operator tools |

Do not put `operatorDecisionApiKey` in worker runtime profiles.

## Workforce deployment flow

```text theme={null}
1. axon_operator_whoami
2. axon_operator_list_wallets
3. axon_operator_create_wallet
4. axon_operator_update_mandate
5. axon_operator_fund_pocket
6. axon_operator_issue_runtime_key
7. Configure worker from openclaw_plugin_config at plugins.entries.axon.config
8. Worker uses runtime tools
```

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

## Runtime spend flow

`axon_http_fetch` is the default runtime spend path. Every call is
policy-gated, risk-scored, and bound to an `intent` and `task_id`.
Workers should not reach past this tool to a raw HTTP client when calling
paid endpoints.

Required fields:

| Field | Type | Description |
| :- | :- | :- |
| `url` | string | Target URL |
| `task_id` | string | Task identifier for forensics |
| `intent` | string | Business reason aligned with the mandate purpose and allowed categories |

Recommended fields:

| Field | Description |
| :- | :- |
| `idempotency_key` | Deterministic key required to safely retry POSTs or replay after approval |
| `expected_output_type` | Helps risk scoring and forensics |
| `cost_expectation_min_usdc`, `cost_expectation_max_usdc` | Cost bounds |
| `justification`, `agent_id`, `employee_id`, `evidence_hashes` | Audit trail |

## Approval flow

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

```text theme={null}
1. axon_http_fetch -> APPROVAL_REQUIRED + approval_request_id
2. Human approves in the AXON dashboard or control plane
3. axon_check_approval_status or axon_wait_for_approval_resolution
4. axon_consume_approval_token
5. Retry axon_http_fetch with the same idempotency_key and approval_token
```

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

## Provider-search flow

Provider search lets a worker discover candidate paid x402 services
without leaving the runtime surface.

```text theme={null}
1. axon_search_x402_services
2. axon_inspect_x402_offer
3. axon_quote_x402_offer or axon_test_buy_x402_offer
4. axon_http_fetch for actual governed execution
5. axon_get_receipt for audit proof
```

Provider-search output is discovery input, not spend approval. Budget,
mandate, approval, and network enforcement still happen through the
Decision API.

## Related reading

* [Organizations and wallets](https://docs.axon402.com/docs/concepts/organizations-and-wallets.md)
* [Mandates](https://docs.axon402.com/docs/concepts/mandates.md)
* [Spend lifecycle](https://docs.axon402.com/docs/concepts/spend-lifecycle.md)
* [Two-Surface Migration](https://docs.axon402.com/docs/integrations/two-surface-migration.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.