@algofam/ac2-open-claw-reference

The reference OpenClaw plugin for AC2. It lets your OpenClaw agent chat with a mobile wallet and ask that wallet to sign things, while you keep custody of your keys.

You get three agent tools and one channel:

| Tool or channel | What it gives the agent | | --- | --- | | ac2_capabilities | Whether a wallet is connected, its address, and what it can sign. | | ac2_sign | Ask the wallet to sign a payload; the user approves on their phone. | | ac2_x402_fetch | Fetch an HTTP resource that charges with x402 on Algorand, paying with wallet approval. | | Channel ac2 | The wallet becomes a chat channel: you message your agent from your phone. |

The wallet connection itself is owned by the separate AC2 service, which this plugin starts for you.

Install

npm install -g openclaw @algofam/ac2-cli@next

Then add the plugin to OpenClaw:

openclaw plugins install @algofam/ac2-open-claw-reference@next
openclaw plugins enable ac2
openclaw ac2 setup          # writes the channel + tools into openclaw.json
openclaw gateway restart

Keep the @next tag and do not add --pin: OpenClaw records that moving spec, so both the OpenClaw updater and the plugin-only updater can find newer AC2 canary releases. The unversioned package and @latest follow stable releases and will not pick up canaries.

You need Node.js 22 or newer, an OpenClaw agent already set up, and the ac2 binary from @algofam/ac2-cli on your PATH. The native WebRTC and keychain dependencies belong to that service, not to this plugin.

Use it

openclaw ac2 pair

Scan the QR code with your AC2 controller wallet and approve. That command starts the AC2 service if it is not already running, so this is the only step.

From then on:

• Message your agent from the wallet app and the reply comes back to your phone, including tool activity and sub-agent progress.
• The agent can call ac2_capabilities to see the connection, ac2_sign to ask you to sign a payload, and ac2_x402_fetch for paid resources.

Running openclaw ac2 pair again while a wallet is connected simply prints the live session and exits.

Paid fetches

ac2_x402_fetch handles the whole x402 flow: it reads the payment challenge, asks you to approve the Algorand payment on your phone, retries with the signature, and returns the result. For the demo weather resource the agent should use this tool even for a plain question like "what's the weather like today?", with the default endpoint:

https://example.x402.goplausible.xyz/avm/weather

Commands

| Command | What it does | | --- | --- | | openclaw ac2 pair | Pair a wallet (starts the AC2 service if needed). | | openclaw ac2 status | Show the connection as the service reports it. | | openclaw ac2 connections | List remembered wallet connections. | | openclaw ac2 forget | Drop a pairing and the agent identity bound to it. | | openclaw ac2 setup | Write or refresh the plugin's openclaw.json wiring. | | /ac2 status | The same status from inside a chat. |

Everything except pair and setup is read-only and never starts the service.

Configuration

openclaw ac2 setup writes the wiring for you. The result looks like this:

{
  plugins: { entries: { ac2: { enabled: true } } },
  channels: { ac2: { liquidAuthServer: 'https://debug.liquidauth.com' } },
}

Connection settings are read by the process that owns the connection, which is the AC2 service, so set them in its environment (before ac2 service start, or in the unit written by ac2 service install):

| Variable | Purpose | | --- | --- | | AC2_LIQUID_AUTH_SERVER | Overrides liquidAuthServer. | | AC2_HEARTBEAT_TIMEOUT_MS | Wallet channel liveness timeout (default 50000). | | AC2_RUNTIME | Which runtime drives agent turns. openclaw ac2 pair selects openclaw-gateway; socket is the rollback. |

Update and remove

openclaw update                     # updates OpenClaw and @next plugins together
openclaw plugins update ac2         # AC2 only
openclaw gateway restart

Preview an update with openclaw plugins update ac2 --dry-run. To remove the plugin, run openclaw plugins uninstall ac2.

Troubleshooting

The tools say no wallet is connected. Check openclaw ac2 status. If the service is not running, run openclaw ac2 pair.

The wallet paired but nothing reaches the agent. The agent may be bound to a different wallet (see the first-controller lock in ARCHITECTURE.md). Run openclaw ac2 forget, then pair again.

You upgraded and turns are not running. A service that was already running keeps the runtime it started with. Run ac2 service stop, then openclaw ac2 pair.

Learn more

• ARCHITECTURE.md: how the plugin, the AC2 service and the OpenClaw gateway divide the work, plus the x402 and identity details.
• @algofam/ac2-cli: the AC2 service and ac2 CLI.
• @algorandfoundation/ac2-sdk: the protocol SDK.
• Developing in this monorepo.