CLAWPITAL Technical Documentation

Reference implementation and specification for the OpenClaw autonomous agent framework. This document describes architecture, APIs, deployment topology, and operational constraints.

1. System Architecture

The agent runtime is a stateful process that maintains an internal world model, executes a decision loop over configurable intervals, and interfaces with external execution and data providers via a well-defined adapter layer. The core loop is single-threaded; I/O is non-blocking and event-driven.

• Orchestrator: Coordinates the think–decide–act cycle, manages lifecycle (start/pause/stop), and enforces rate limits and cooldowns.
• Narrative Engine: Ingests and scores market narratives from configured sources (on-chain, social, fundamental); outputs a ranked set of themes with confidence and decay.
• Execution Layer: Translates high-level actions into signed transactions; supports multiple chains and DEX/CEX adapters with a unified order interface.
• State Store: Persists positions, PnL, and audit trail; supports replay and reconciliation for compliance.

2. Configuration & Risk Parameters

All deployable parameters are expressed in a single manifest (YAML/JSON). Critical knobs include:

Parameter	Type	Description
max_position_size_usd	float	Upper bound per position in USD; enforced pre-trade.
max_daily_drawdown_pct	float	Circuit breaker: halt new trades if daily equity drawdown exceeds this.
narrative_min_heat	int	Minimum narrative score (0–100) to consider for allocation.
think_interval_sec	int	Seconds between full think cycles.
execution_slippage_bps	int	Max slippage in basis points for market orders.

Override and validation rules are documented in the schema; invalid values cause the orchestrator to refuse startup and log a structured error.

3. API Contract (Internal)

The narrative engine exposes a single async method:

NarrativeResult[] getNarratives(UniverseFilter filter, int topK)

Returns a sorted list of narrative descriptors (id, theme, heat, sources, last_updated). The execution layer implements:

OrderReceipt submitOrder(OrderRequest req) throws InsufficientLiquidityException, SlippageExceededException

Idempotency is enforced via client-supplied idempotency_key; duplicate keys return the existing receipt without re-execution.

4. Deployment Topology

Recommended production topology: one orchestrator process per agent instance; state store (DB or key-value) and execution adapters can be shared or isolated per tenant. Network egress to blockchains and third-party APIs is rate-limited and retried with exponential backoff. No shared mutable in-memory state between instances.

5. Security & Key Management

Signing keys must never be exported from the execution environment. Use HSM or enclave-backed signers where available. API keys and RPC endpoints are injected via environment or secret manager; they must not appear in manifests or logs. All sensitive fields are redacted in audit logs.

6. Observability

Structured logs (JSON) with correlation IDs for each think cycle and order. Metrics: think_duration_sec, orders_submitted_total, orders_filled_total, pnl_realized_usd. Alerts should be configured on max_daily_drawdown_pct breach and on consecutive execution failures.

7. Versioning & Compatibility

Manifest schema is versioned; the runtime rejects manifests with an unsupported schema_version. Adapter interfaces are backward-compatible within major versions; new optional fields may be added without breaking existing implementations.

8. References

OpenClaw specification: github.com/brianweb3/clawpital. For deployment steps and manifest examples, see the repository README and the Deploy panel in this application.