# steipete-oai/clawrouter architecture

> Architecture diagram of the GitHub repository steipete-oai/clawrouter, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/steipete-oai/clawrouter
- Repository: https://github.com/steipete-oai/clawrouter

## Overview

ClawRouter is a local LLM proxy and OpenClaw plugin for agent-driven inference. A client submits a request; the proxy can classify it and choose a capable, lower-cost model, then handle upstream inference and wallet-based x402 payment. The repository also includes context compression, session continuity, partner tools, web search, and spend and usage controls. The README documents these product capabilities, while sampled source directly confirms routing delegation, wallet setup, compression, partner definitions, and web-search requests; some proxy internals are represented only by their enclosing modules.

Main entry points: [`src/proxy.ts`](https://github.com/steipete-oai/clawrouter/blob/main/src/proxy.ts) (Local API proxy), [`src/router/index.ts`](https://github.com/steipete-oai/clawrouter/blob/main/src/router/index.ts) (Routing entry), [`src/auth.ts`](https://github.com/steipete-oai/clawrouter/blob/main/src/auth.ts) (Wallet authentication), [`src/provider.ts`](https://github.com/steipete-oai/clawrouter/blob/main/src/provider.ts) (Provider integration)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Client entry"]
  node_plugin["OpenClaw plugin<br/>[index.ts]"]
  node_proxy["Local API proxy<br/>[proxy.ts]"]
  node_cli["CLI and setup<br/>[cli.ts]"]
end

subgraph group_routing["Request routing"]
  node_router["Routing entry<br/>[index.ts]"]
  node_classifier["Request classifier<br/>[rules.ts]"]
  node_selector["Model selector<br/>[selector.ts]"]
  node_session[("Session pinning<br/>[session.ts]")]
  node_models["Model catalog<br/>[models.ts]"]
end

subgraph group_inference["Inference and payment"]
  node_provider["Provider integration<br/>[provider.ts]"]
  node_upstream["Upstream transport<br/>[upstream-proxy.ts]"]
  node_auth["Wallet authentication<br/>[auth.ts]"]
  node_payment["Payment preauthorization<br/>[payment-preauth.ts]"]
  node_wallet["Wallet storage<br/>[wallet.ts]"]
end

subgraph group_capabilities["Agent capabilities"]
  node_compression["Context compression<br/>[index.ts]"]
  node_partners["Partner tools<br/>[tools.ts]"]
  node_partnerregistry["Partner catalog<br/>[registry.ts]"]
  node_websearch["Web search tool"]
  node_stats[("Usage and spend<br/>[stats.ts]")]
  node_controls["Spend controls<br/>[spend-control.ts]"]
end

node_client(("Agent or client"))
node_chains{{"Base and Solana"}}
node_upstreammodels{{"Model providers"}}
node_partnerapis{{"Partner APIs"}}

node_client -->|"sends requests"| node_proxy
node_client -->|"uses plugin"| node_plugin
node_cli -->|"sets up wallet"| node_auth
node_proxy -->|"routes requests"| node_router
node_router -->|"classifies request"| node_classifier
node_router -->|"selects model"| node_selector
node_router -->|"pins session model"| node_session
node_selector -->|"checks models"| node_models
node_proxy -->|"dispatches inference"| node_provider
node_provider -->|"forwards requests"| node_upstream
node_upstream -->|"calls model APIs"| node_upstreammodels
node_provider -->|"authenticates"| node_auth
node_auth -->|"loads keys"| node_wallet
node_auth -->|"signs payments"| node_payment
node_payment -->|"settles x402"| node_chains
node_proxy -->|"compresses context"| node_compression
node_proxy -->|"dispatches tools"| node_partners
node_partners -->|"reads definitions"| node_partnerregistry
node_partners -->|"calls services"| node_partnerapis
node_websearch -->|"submits search"| node_proxy
node_proxy -->|"records usage"| node_stats
node_proxy -->|"checks spending"| node_controls

click node_plugin "https://github.com/steipete-oai/clawrouter/blob/main/src/index.ts"
click node_proxy "https://github.com/steipete-oai/clawrouter/blob/main/src/proxy.ts"
click node_cli "https://github.com/steipete-oai/clawrouter/blob/main/src/cli.ts"
click node_router "https://github.com/steipete-oai/clawrouter/blob/main/src/router/index.ts"
click node_classifier "https://github.com/steipete-oai/clawrouter/blob/main/src/router/rules.ts"
click node_selector "https://github.com/steipete-oai/clawrouter/blob/main/src/router/selector.ts"
click node_session "https://github.com/steipete-oai/clawrouter/blob/main/src/session.ts"
click node_models "https://github.com/steipete-oai/clawrouter/blob/main/src/models.ts"
click node_provider "https://github.com/steipete-oai/clawrouter/blob/main/src/provider.ts"
click node_upstream "https://github.com/steipete-oai/clawrouter/blob/main/src/upstream-proxy.ts"
click node_auth "https://github.com/steipete-oai/clawrouter/blob/main/src/auth.ts"
click node_payment "https://github.com/steipete-oai/clawrouter/blob/main/src/payment-preauth.ts"
click node_wallet "https://github.com/steipete-oai/clawrouter/blob/main/src/wallet.ts"
click node_compression "https://github.com/steipete-oai/clawrouter/blob/main/src/compression/index.ts"
click node_partners "https://github.com/steipete-oai/clawrouter/blob/main/src/partners/tools.ts"
click node_partnerregistry "https://github.com/steipete-oai/clawrouter/blob/main/src/partners/registry.ts"
click node_websearch "https://github.com/steipete-oai/clawrouter/blob/main/src/web-search-provider.ts"
click node_stats "https://github.com/steipete-oai/clawrouter/blob/main/src/stats.ts"
click node_controls "https://github.com/steipete-oai/clawrouter/blob/main/src/spend-control.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_plugin,node_proxy,node_cli,node_client toneBlue
class node_router,node_classifier,node_selector,node_session,node_models toneAmber
class node_provider,node_upstream,node_auth,node_payment,node_wallet,node_partnerapis toneMint
class node_compression,node_partners,node_partnerregistry,node_websearch,node_stats,node_controls toneRose
class node_chains,node_upstreammodels toneIndigo
```

## Components

### Client entry

- [OpenClaw plugin](https://github.com/steipete-oai/clawrouter/blob/main/src/index.ts): `src/index.ts`
- [Local API proxy](https://github.com/steipete-oai/clawrouter/blob/main/src/proxy.ts): `src/proxy.ts`
- [CLI and setup](https://github.com/steipete-oai/clawrouter/blob/main/src/cli.ts): `src/cli.ts`

### Request routing

- [Routing entry](https://github.com/steipete-oai/clawrouter/blob/main/src/router/index.ts): `src/router/index.ts`
- [Request classifier](https://github.com/steipete-oai/clawrouter/blob/main/src/router/rules.ts): `src/router/rules.ts`
- [Model selector](https://github.com/steipete-oai/clawrouter/blob/main/src/router/selector.ts): `src/router/selector.ts`
- [Session pinning](https://github.com/steipete-oai/clawrouter/blob/main/src/session.ts): `src/session.ts`
- [Model catalog](https://github.com/steipete-oai/clawrouter/blob/main/src/models.ts): `src/models.ts`

### Inference and payment

- [Provider integration](https://github.com/steipete-oai/clawrouter/blob/main/src/provider.ts): `src/provider.ts`
- [Upstream transport](https://github.com/steipete-oai/clawrouter/blob/main/src/upstream-proxy.ts): `src/upstream-proxy.ts`
- [Wallet authentication](https://github.com/steipete-oai/clawrouter/blob/main/src/auth.ts): `src/auth.ts`
- [Payment preauthorization](https://github.com/steipete-oai/clawrouter/blob/main/src/payment-preauth.ts): `src/payment-preauth.ts`
- [Wallet storage](https://github.com/steipete-oai/clawrouter/blob/main/src/wallet.ts): `src/wallet.ts`

### Agent capabilities

- [Context compression](https://github.com/steipete-oai/clawrouter/blob/main/src/compression/index.ts): `src/compression/index.ts`
- [Partner tools](https://github.com/steipete-oai/clawrouter/blob/main/src/partners/tools.ts): `src/partners/tools.ts`
- [Partner catalog](https://github.com/steipete-oai/clawrouter/blob/main/src/partners/registry.ts): `src/partners/registry.ts`
- [Web search tool](https://github.com/steipete-oai/clawrouter/blob/main/src/web-search-provider.ts): `src/web-search-provider.ts`
- [Usage and spend](https://github.com/steipete-oai/clawrouter/blob/main/src/stats.ts): `src/stats.ts`
- [Spend controls](https://github.com/steipete-oai/clawrouter/blob/main/src/spend-control.ts): `src/spend-control.ts`

### Other components

- **Agent or client**
- **Base and Solana**
- **Model providers**
- **Partner APIs**

## Connections

- Agent or client → Local API proxy: sends requests
- Agent or client → OpenClaw plugin: uses plugin
- CLI and setup → Wallet authentication: sets up wallet
- Local API proxy → Routing entry: routes requests
- Routing entry → Request classifier: classifies request
- Routing entry → Model selector: selects model
- Routing entry → Session pinning: pins session model
- Model selector → Model catalog: checks models
- Local API proxy → Provider integration: dispatches inference
- Provider integration → Upstream transport: forwards requests
- Upstream transport → Model providers: calls model APIs
- Provider integration → Wallet authentication: authenticates
- Wallet authentication → Wallet storage: loads keys
- Wallet authentication → Payment preauthorization: signs payments
- Payment preauthorization → Base and Solana: settles x402
- Local API proxy → Context compression: compresses context
- Local API proxy → Partner tools: dispatches tools
- Partner tools → Partner catalog: reads definitions
- Partner tools → Partner APIs: calls services
- Web search tool → Local API proxy: submits search
- Local API proxy → Usage and spend: records usage
- Local API proxy → Spend controls: checks spending