Omniclaw Cli Skill

Use this skill whenever an agent needs to pay for an x402 URL, transfer USDC to an address, inspect OmniClaw balances or ledger entries, or explicitly expose...

Security Scan

The skill is internally consistent: it documents and requires the omniclaw-cli binary and the expected OmniClaw service token/URL, and its instructions stay within the CLI execution surface while warning about dangerous operations like serve/--exec.

Purpose & Capability

Name, description, required binaries (omniclaw-cli), and required env vars (OMNICLAW_SERVER_URL, OMNICLAW_TOKEN) align with a CLI-focused payment/inspection/serve skill. Included helper scripts and generated CLI reference are consistent with documenting a local CLI.

Instruction Scope

SKILL.md limits the agent to CLI execution paths (pay, inspect-x402, balance, serve when owner-approved) and explicitly forbids policy editing, wallet provisioning, and searching for secrets. The only notable risk is legitimate: omniclaw-cli serve combined with --exec runs host commands and binds to 0.0.0.0 — the skill documents this and requires explicit owner approval before using serve/--exec. Operators should enforce that owner approval step and prefer isolated runtimes for serve.

Install Mechanism

Instruction-only skill with no install spec; requires the omniclaw-cli binary to be present. This is low-risk from an install perspective. The included generator scripts call the CLI to capture --help output (expected for doc generation).

Credentials

Requested env vars (OMNICLAW_SERVER_URL, OMNICLAW_TOKEN) and optional OMNICLAW_OWNER_TOKEN are appropriate for a payment CLI. Warning: the docs generator subprocesses inherit the parent process environment (os.environ), so if you run generation with secret env vars present, they will be available to child processes — not necessarily leaked by the help commands, but worth caution when running the generator in an environment with live tokens.

Persistence & Privilege

Skill does not request always:true, does not modify other skills, and does not require config paths. Autonomous invocation is allowed (platform default) but the skill’s documented safety checks (owner approval for serve) mitigate risky autonomous actions if operator policies are followed.

Assessment

This skill appears to do what it says: operate the omniclaw-cli for payments, balance inspection, and (with explicit owner approval) exposing paid endpoints. Before installing, ensure: (1) the omniclaw-cli binary is obtained from a trusted source and up-to-date; (2) only provide OMNICLAW_TOKEN and OMNICLAW_SERVER_URL that you trust (do not supply OMNICLAW_OWNER_TOKEN unless you intentionally allow owner approval actions); (3) block or tightly control use of omniclaw-cli serve/--exec unless an owner explicitly approves the exact command and you run it in an isolated container or private network; (4) avoid running the included docs generator scripts in an environment where live tokens are present unless you trust the CLI help output — the generator forwards your environment to child processes; and (5) add monitoring/limits for payments so accidental or unauthorized spends are detectable. If you need higher assurance, request the omniclaw-cli source or a reproducible package verification from the publisher before granting tokens.

Trigger

Use omniclaw-cli only when the task is directly about one of these actions:

• pay for a paid URL that returns 402 Payment Required
• transfer USDC to an address
• inspect wallet, Gateway, or Circle balances
• inspect transaction history
• expose a paid endpoint for other agents or automation with serve, only when the owner explicitly asks for it

Do not use this skill for:

• editing policy files
• creating wallets
• provisioning secrets
• changing allowlists, limits, or owner approvals outside the exposed CLI commands
• administering the Financial Policy Engine process itself

Core Model

OmniClaw is not just a wallet wrapper. It is the economic execution and control layer that combines:

• zero-trust execution through the CLI
• owner-defined financial policy through the Financial Policy Engine
• settlement rails such as direct transfers, x402, CCTP, and Circle Gateway nanopayments

This skill is specifically about the CLI execution surface.

The same CLI has two agent-side economic roles:

• buyer role: omniclaw-cli pay
• seller role for agent-run paid endpoints: omniclaw-cli serve

Vendor and enterprise seller APIs should use the Python SDK with client.sell(...), not this CLI skill.

The agent does not control the private key. The Financial Policy Engine enforces policy and signs allowed actions.

Dependency and Credential Contract

The runtime must have:

• omniclaw-cli installed from the official OmniClaw package
• OMNICLAW_SERVER_URL pointing to the trusted Financial Policy Engine
• OMNICLAW_TOKEN scoped to the agent wallet/policy

Optional:

• OMNICLAW_OWNER_TOKEN, only when the owner intentionally grants approval authority for this run

Never print tokens, write tokens into generated files, or pass tokens to third-party services.

Inputs The Agent Should Expect

The runtime should normally provide either:

1. environment-driven execution

• OMNICLAW_SERVER_URL
• OMNICLAW_TOKEN
• optionally OMNICLAW_OWNER_TOKEN if this run is allowed to approve confirmations

2. persisted CLI config

• omniclaw-cli configure was already run before the turn
• the CLI reads saved config values for server URL, token, wallet alias, and optional owner token

If neither is true, stop and ask the owner for:

• Financial Policy Engine URL
• agent token
• wallet alias

Do not invent or search for them yourself.

Safe Default Workflow

For any new spend

1. Run omniclaw-cli status if connectivity or health is uncertain.
2. Run omniclaw-cli balance-detail if Gateway balance matters.
3. Run omniclaw-cli can-pay --recipient ... before paying a new recipient.
4. Use --idempotency-key for job-based payments.
5. For direct-address payments where budget/guards matter, use simulate first.

For x402 URLs

1. Run omniclaw-cli inspect-x402 --recipient <url> before the first live payment to confirm the seller requirements and buyer funding path.
2. Use omniclaw-cli pay --recipient <url> --idempotency-key <unique-id>.
3. Add --method, --body, and --header when the paid endpoint expects a non-GET request.
4. Add --output if the paid response should be saved.

For direct address transfers

1. Use omniclaw-cli pay --recipient <0xaddress> --amount <usdc>.
2. Always include --purpose.

For agent-run seller tasks

1. Inspect current state with balance-detail.
2. Confirm the owner explicitly asked this agent to expose a paid endpoint.
3. Start the paid endpoint with omniclaw-cli serve only for the approved endpoint, price, command, and port.
4. Remember that serve binds to 0.0.0.0 even if the banner prints localhost.

Serve Safety Rules

omniclaw-cli serve is powerful because it starts a network-accessible service and requires --exec.

Rules:

• do not run serve unless the owner explicitly requested a seller endpoint in the current task
• do not invent the --exec command
• do not use --exec for shell pipelines, downloads, package installs, destructive commands, or credential access
• prefer an isolated container or private development network for serve
• disclose the port and endpoint before treating the service as ready

Approval Handling

If pay returns approval-required output, for example:

• requires_confirmation: true
• confirmation_id: ...

Then:

• do not retry blindly
• do not invent a workaround
• if the run explicitly has owner authority, use omniclaw-cli confirmations approve --id <confirmation-id>
• otherwise stop and notify the owner

Stop Conditions

Stop and notify the owner if any of these happen:

• token or Financial Policy Engine URL is missing
• can-pay says the recipient is blocked
• pay returns a policy or guard rejection
• available or Gateway balance is insufficient
• the exact command or flag is unclear
• serve is requested without an explicit owner instruction
• serve --exec is requested but the command is not supplied or approved by the owner

Command Reference

For exact command schemas, flags, and live help output, read:

• references/cli-reference.md

Do not guess flags from memory when a reference is available.