# OmniClaw, a payment rail for agents that keeps the signing key behind a policy engine

> OmniClaw 0.0.8 is a Python buyer SDK plus a Financial Policy Engine over Circle wallets and x402. Here is the product boundary it draws, the modes it ships, and what the defaults actually point at.

**omnuron/omniclaw** — The first agentic payment network: policy-controlled, gasless, and real money-ready.  OmniClaw CLI + Financial Policy Engine let autonomous agents pay and earn safely at machine speed.

- Repository: https://github.com/omnuron/omniclaw
- Website: https://www.omniclaw.ai/
- Stars: 576 · Forks: 43
- Language: Python
- License: MIT
- Published: 2026-09-10 · Updated: 2026-09-10 · Language: en
- Canonical page: https://hysenlabs.com/projects/omnuron-omniclaw

## Core owns the buyer side and refuses the recipient side

One table in the README does the architectural work. OmniClaw core lives in `src/omniclaw` and owns five things: the buyer SDK, the policy engine, wallet and payment routing, x402 buyer execution, and Gateway buyer readiness. Immediately under that table comes the constraint that shapes everything else: core should not include recipient-side paid endpoint hosting or settlement service code. So the repository is deliberately half of a payment system. It knows how to decide whether a payment is allowed and how to make one, and it is not responsible for the endpoint being paid or for settling afterwards. That boundary is what lets the same package sit inside someone else's product without becoming their settlement provider.

## `OMNICLAW_BUYER_MODE` selects the rail, and there are three values

The rail profile is a single variable with three documented settings, and each one removes a dependency as well as a feature. `hybrid` is Circle direct transfer plus x402 paid APIs and is the default. `circle` is Circle direct transfer only. `x402` is x402 paid APIs only. The credential requirements differ with them, which is the part worth planning around: the hybrid default wants `CIRCLE_API_KEY` and `ENTITY_SECRET` alongside the private key, the agent token, the owner token, the network, and the RPC URL, while x402-only mode leaves the Circle key and entity secret empty unless you want the optional Gateway API helpers. The quickstart walks two of the three. The environment template is where the full list is, including the mode you get when you want transfers and nothing else.

## Two policy rails, and the x402 path chooses for you

A policy file names the rails it is allowed to use, and there are two of them. `circle_transfer` covers direct transfers from a Circle Developer Wallet. `x402` covers payments to paid APIs. For the second one the routing decision is not yours to make: OmniClaw chooses between a Gateway nanopayment and the standard x402 payment path internally, based on whether the seller accepts it, what the buyer configuration says, and what the Gateway balance is. That is a deliberate reduction in agent discretion, and it is worth understanding before you debug a payment that took a route you did not expect. The CLI makes the same kind of split explicit, with `pay`, `inspect-x402`, and `can-pay` as the three buyer commands, so an agent can ask what a payment would cost before it commits to one.

## Policy file and wallet state are two files on purpose

The quickstart draws a line that is easy to miss and expensive to get wrong. The policy file is stable configuration, and generated wallet state is written separately to `examples/agent/buyer/runtime/wallet-state.json`. In the environment template the same split appears as `OMNICLAW_AGENT_POLICY_PATH` and `OMNICLAW_AGENT_STATE_PATH`. That separation is what lets the same policy be committed, reviewed, and shared while the derived state stays disposable, and it is the reason the quickstart creates the runtime directory before copying anything in. Two more variables sit alongside them: an agent token for the worker that should not hold raw key authority, and an owner token for whoever does. The stated purpose of the agent token is the case where an agent, worker, or partner integration should not have the key.

## The buyer CLI talks to a local server on port 9091

After the environment file exists, the CLI needs to be pointed at a running buyer server and given a token. That is three lines:

```bash
set -a; source .env; set +a
export OMNICLAW_SERVER_URL="http://127.0.0.1:9091"
export OMNICLAW_TOKEN="$OMNICLAW_AGENT_TOKEN"
```

The `set -a` and `set +a` pair is what exports everything the `.env` file defines rather than only the one variable you name, which matters because the server process reads several of them. The token exported here is the agent token rather than the owner token, so a developer poking at the CLI is exercising the same restricted authority an autonomous worker would get. The loopback address and port are the defaults the example assumes; nothing in the repository suggests binding that server to a public interface is a supported arrangement.

## `inspect-x402` runs before `pay`, and the key is yours to supply

The documented payment sequence is inspect, then pay, against the same recipient:

```bash
omniclaw-cli inspect-x402 --recipient "http://127.0.0.1:4023/compute?size=20"
omniclaw-cli pay --recipient "http://127.0.0.1:4023/compute?size=20" --amount 0.10 --idempotency-key job-123
```

Two details carry the weight. The inspect step exists so the price and the accepted payment method can be read before any value moves, which is the only sane ordering when an agent holds a budget. And the idempotency key is supplied by the caller rather than generated, so a retry after a timeout can be recognised as the same payment instead of becoming a second one. Ledger, idempotency, simulation, and payment-intent controls are listed as core capabilities, and this flag is where the idempotency one surfaces in a command you can read.

## The Compose service is named for the agent but builds the core image

The Compose file has two services. Redis runs on 7-alpine with `--appendonly yes --appendfsync everysec`, a named volume, and a healthcheck that gates the other service. The application service is called `omniclaw-agent`, builds from the repository root, and runs `uvicorn omniclaw.agent.server:app` with `--reload`, while mounting `./src` over `/app/src`. Three things are worth checking against your own setup. A bind mount of the source tree means the container runs your working copy rather than the installed package. `--reload` is a development flag. And the build context is the default `Dockerfile`, so the separate `Dockerfile.agent` at the top level is not what this service uses. That Dockerfile also creates no unprivileged user, so the container runs as root by default.

## Version 0.0.8 comes from a git tag, and every shipped default is a testnet

The version number is not written anywhere in the source. The build backend is Hatchling with `uv-dynamic-versioning`, reading the tag from git, formatted as PEP 440, with bumping enabled, which is why the three most recent tags are v0.0.6 on 2026-04-14, v0.0.7 on 2026-04-22, and v0.0.8 on 2026-05-29, and why the last push to the default branch main is also 2026-05-29. The classifier says Development Status 3, Alpha, and the package requires Python 3.10 or newer with 3.10 through 3.12 listed. The network defaults are the other thing to look at: the environment template lists ETH-SEPOLIA, BASE-SEPOLIA, and ARC-TESTNET as supported, and ships `OMNICLAW_NETWORK=BASE-SEPOLIA` with an RPC URL on sepolia.base.org. Every default is a test network.

## Conclusion

OmniClaw is aimed at integrators who cannot hand an autonomous process a signing key, which makes the policy engine, the separate agent and owner tokens, and the read-only `inspect-x402` step the parts that matter. It is a poor fit if you need the receiving side, because the project places paid endpoint hosting and settlement code outside core on purpose, and it is an alpha package at version 0.0.8 with the last push on 2026-05-29. Before pointing it at a chain, change `OMNICLAW_NETWORK` off the shipped testnet defaults and decide which of the three buyer modes you actually need.

## FAQ

### What does OmniClaw actually let an agent do?

Pay, through two policy rails: circle_transfer for direct Circle Developer Wallet transfers, and x402 for payments to paid APIs. The core also ships a policy engine covering budgets, approvals, trust checks, and execution control, plus ledger, idempotency, simulation, and payment-intent controls. Recipient-side hosting and settlement are explicitly outside core.

### What is the difference between the OmniClaw buyer modes?

OMNICLAW_BUYER_MODE selects one of three rail profiles. hybrid is Circle direct transfer plus x402 paid APIs and is the default, circle is Circle direct transfer only, and x402 is x402 paid APIs only. Each mode has different credential requirements, which are listed in the environment template.

### Can OmniClaw run against a real network out of the box?

Not with the shipped defaults. The environment template lists ETH-SEPOLIA, BASE-SEPOLIA, and ARC-TESTNET as the supported examples and defaults to BASE-SEPOLIA with an RPC URL on sepolia.base.org. The package is also classified as Alpha and its newest tag is v0.0.8.

### How does OmniClaw stop an agent from paying twice?

The buyer CLI takes an idempotency key on the pay command, and idempotency is one of the core controls alongside the ledger, simulation, and payment intent. You supply the key yourself, so a retry after a timeout can be recognised as the same payment rather than becoming a second one.

### Do I need to install OmniClaw with any extras?

The package installs with a plain pip install omniclaw. The declared dependencies include the Circle developer wallet client, the x402 SDK with evm, fastapi, and httpx extras, web3, eth-account, typer, fastapi, uvicorn, and redis. The testing and packaging tools live in a separate dev extra.

## Sources

- [License: MIT](https://github.com/omnuron/omniclaw/blob/main/LICENSE)
- [omnuron/omniclaw on GitHub](https://github.com/omnuron/omniclaw)
- [Project website](https://www.omniclaw.ai/)
- [README](https://github.com/omnuron/omniclaw/blob/main/README.md)
- [Releases](https://github.com/omnuron/omniclaw/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/omnuron-omniclaw