How We Route Cloud APIs, Hermes, OpenClaw, and Your Mac

I wrote about BYOK and local tool calling. This post covers the routing underneath them: where a turn goes, how it reaches a runtime on your Mac, and what “local” does and does not mean.

---

Three Lanes, Not “Cloud vs Local”

1. Cloud BYOK providers. OpenAI, Anthropic, Google, Mistral, Azure OpenAI, Vertex, Bedrock, and Codex. Your account or credential; AICoven calls that provider.

2. Hermes and OpenClaw runtimes you host. A full agent stack on your Mac, VM, or tailnet. Hermes exposes native HTTP runs. OpenClaw exposes a native Gateway plus an OpenAI-compatible HTTP surface.

3. The AICoven Local Agent on macOS. The Mac app keeps an authenticated WebSocket to AICoven so work can reach private endpoints, files, and shell tools that Cloud Run cannot see.

Lanes 2 and 3 can both involve your Mac, but they are not the same thing. A role can run in Claude while using the Mac for a shell command, or it can hand the whole agent run to Hermes/OpenClaw.

An OpenAI-compatible server (Ollama, LM Studio, llama.cpp or vLLM on your hardware; Groq or DeepSeek hosted) is not lane 2. It answers chat completions and nothing more: AICoven runs the agent loop for it as it does in lane 1, and there are no agent runs or approvals. One on your Mac or local network is reached through lane 3's connection.

Privacy note: every lane still uses AICoven's backend for threading, memory, tools, continuity, and encrypted message persistence. “Local” says where the runtime or tool executes. It does not mean the turn never touches our cloud. We decrypt content in memory to orchestrate the turn; we do not keep a plaintext chat archive for staff to browse. The narrower trust claim is in middleman-attack.

---

We Route to the Runtime, Not Its Internal Model

Hermes Agent and OpenClaw are not just model servers. They own their tools, skills, MCP connections, internal memory, and model configuration.

They can use local models. They can also use cloud models configured inside the runtime. AICoven chooses the authorized runtime account and address; it does not choose or bill the model that runtime calls internally unless the runtime reports it.

So “local provider” means you host the agent process. It is not a guarantee that every token was generated offline.

---

OpenClaw Has Two Addresses

An OpenClaw account can store both:

Address	Typical local value	Purpose
Gateway address (gateway_url)	ws://127.0.0.1:18789	Native runs, durable state, Stop, approvals, steering
Compatibility address (base_url)	http://127.0.0.1:18789	Model discovery and OpenAI-compatible fallback

They are separate protocols on one port. OpenClaw serves WebSocket Gateway traffic and its HTTP API together on gateway.port (18789 unless you changed it), and the HTTP endpoints are off until you enable them in OpenClaw's config.

The native path below shipped in AICoven 3.0.0. When a Gateway address is configured, AICoven uses the native OpenClaw path first. It completes the Gateway handshake, subscribes to the thread session, sends chat.send, streams bounded assistant events, and keeps the run's native identity for Stop and reconciliation.

If that native preflight fails definitively before AICoven takes ownership, the same account may fall back to its compatibility HTTP address. Once the native run may have been sent, AICoven does not switch providers or post the prompt again. It keeps ownership and reconciles the same run.

An account with only a compatibility address can chat, but it does not gain native approvals, authoritative Stop, active steering, or durable Gateway recovery.

---

How Native OpenClaw Reaches the Gateway

The current route is:

AICoven API/worker instance
  -> the user's Mac local-agent WebSocket (in memory, or an encrypted relay across instances)
  -> OpenClaw Gateway client in AICoven for Mac
  -> loopback ws:// or remote wss:// Gateway

The Mac advertises openclaw.gateway.v4, keeps a Keychain-backed device identity, signs the Gateway challenge, and sends the Gateway token inside the handshake rather than in the URL.

The Gateway may be local to that Mac or remote behind wss://. Either way, the Mac opens the Gateway connection. The AICoven API does not currently connect directly to OpenClaw Gateway.

There is another important boundary: native Gateway traffic always terminates at the connected Mac. Same-instance traffic stays in memory. Across backend instances, relay request and response rows store only AES-GCM ciphertext envelopes and non-sensitive routing fields; prompts, tokens, credentials, and projected frames are not persisted there as plaintext. The gateway_url endpoint itself is stored separately as provider-account configuration, so query parameters and URL credentials are rejected and authentication tokens stay in encrypted credential storage and the Gateway handshake.

This is a real limitation, not a UI detail.

---

Native Run Controls

The OpenClaw Gateway contract is pinned to OpenClaw v2026.9.9, protocol 4.

Stop. AICoven records cancellation intent first, then sends chat.abort(sessionKey, runId). The ACK is not proof that the run stopped. The UI remains in a cancelling state until Gateway state or history proves cancellation, completion, or failure.

Approvals. OpenClaw publishes session.approval, which is scoped to a session and does not carry a run ID. AICoven binds it only to the exact thread session and its one current native run. We keep the approval ID, kind, offered choices, and a local evidence version; command text and raw tool payloads are dropped. Resolving sends only the exact approval.resolve(id, kind, decision) shape. OpenClaw offers once, always, or deny on this protocol pin; we do not invent Hermes's session approval choice. An exec approval carries no detail AICoven can show safely, so it is offered as Deny only.

Steering. The active-run endpoint (an API route; the app has no control for it yet) sends another chat.send with queueMode="steer". There is no separate chat.steer protocol method.

Recovery. Disconnects, missing outer frame sequence numbers, and Gateway restarts do not mean the run failed. A durable monitor asks agent.wait, then bounded chat.history, until it can prove the run is still active or settle a terminal result.

There is no gateway.sequence_gap event on the wire. The Mac detects a gap in the outer frame sequence and retires that connection.

---

Hermes Uses a Different Native Protocol

Hermes remains native through its HTTP /v1/runs family, including event observation, approvals, recovery, and Stop. OpenClaw does not reuse those URLs, run IDs, or monitor state.

The product semantics align — owned run, bounded events, durable reconciliation, approvals, cancellation — while the provider adapters and wire contracts remain separate.

AICoven does not merge them into one slug. The provider gateway picks the account bound to the role and builds the right client. It does not fall back to another account or model: if that account fails, the turn stops and says which model could not run and how to fix it.

---

Cloud Models Can Still Use Your Mac

This is separate from assigning a role to Hermes or OpenClaw.

A Claude role can request shell.execute, file reads, or other Mac-local tools. The command flows through AICoven's orchestration and the authenticated Mac WebSocket, runs on the Mac, and returns output to the turn. Anthropic is not remotely controlling your laptop; AICoven is coordinating a cloud model with a local execution agent.

Shell commands and output transit our backend when they are needed in model context. Local execution is not the same as cloud-free orchestration.

---

Discovery and Setup

On macOS, Detect probes the OpenClaw compatibility API at port 18789, or at the configured gateway.port after you grant access to the OpenClaw config folder. A detected OpenClaw card pre-fills both addresses with that port.

The save-time probe tells the two cases apart:

• with a Gateway address, it requires the connected Mac's openclaw.gateway.v4 capability and checks, in the Gateway handshake, that the Gateway offers the methods and approval authority native runs need;
• without one, it tests compatibility HTTP.

A healthy /v1/models response does not prove native Gateway controls are available.

---

What This Is Not

• Not “local means offline.” The runtime may use cloud models internally.
• Not “the OpenClaw Gateway is an HTTP API.” The native Gateway is a WebSocket protocol; compatibility HTTP is a separate protocol on the same port.
• Not direct remote Gateway transport from AICoven's API. Remote wss:// is opened by the Mac client.
• Not direct API-to-Gateway delivery. The Mac remains the Gateway transport boundary.
• Not provider fallback after ownership. Once a native run may exist, AICoven reconciles it instead of duplicating the prompt elsewhere.
• Not a claim that a stream close or abort ACK is terminal evidence.
• Not the on-device MLX path from local-vs-api-tools.

---

TL;DR

• Cloud providers use BYOK routes.
• Hermes uses native HTTP runs.
• OpenClaw's native Gateway path (used when gateway_url is configured; base_url stays for compatibility) shipped in AICoven 3.0.0.
• Native OpenClaw travels through a connected Mac, using a ciphertext relay when the worker and socket are on different instances; there is no direct API Gateway client.
• Stop is chat.abort, approvals use exact approval.resolve identity, steering is chat.send with queueMode="steer", and recovery uses agent.wait plus chat.history.
• “Local” describes where the agent or tool runs, not a promise that AICoven's cloud is absent.

Questions: @aicoven. Beta: aicoven.com/beta.