docs: address SKALE integration feedback

[lloydmak99]

The SKALE team integrated OpenClaw 2026.7.12 with NEAR AI Cloud and filed five findings. All five were validated against live endpoints and source on 2026-08-18. Four are documentation gaps and are addressed here; the fifth (prompt_tokens_details) is explained rather than changed, because it cannot be fixed at the gateway.

Deterministic signature retrieval

The biggest one. GET https://{slug}.completions.near.ai/v1/signature/{chat_id} returns 404 non-deterministically, which broke SKALE's TEE-verification prototype.

The cause is by design: the signature is cached in a per-process in-memory moka cache inside the model TEE that served the completion, and model-proxy is an L4 SNI passthrough balancer with least-connections and no session affinity — it cannot route on a chat_id it never decrypts. dsv4-flash.completions.near.ai had 5 healthy backends on 2026-08-18, so the old "simply retry until you hit the right one" note was a 1-in-5 coin flip.

Replaces that note with three deterministic paths, all verified live:

1. Gateway (recommended) — GET https://cloud-api.near.ai/v1/signature/{chat_id}. cloud-api pins the chat id to the serving backend and persists the signature to the chat_signatures table at completion time. One call, no retries.
2. Pinned replica — https://{slug}-i{N}.completions.near.ai routes to backend N % healthy_count. Send the completion and the lookup to the same hostname.
3. Bounded sweep — read the public GET https://completions.near.ai/backends/count?domain=… and iterate 0..healthy-1.

Documents the caveat that the -i{N} index is positional and rebinds when the healthy backend count changes. /backends/list is auth-gated and deliberately not documented.

max_output_length and is_ready

Both were reported as misleading; both reports were correct.

max_output_length is advisory catalog metadata published for OpenRouter-schema compatibility. Nothing enforces it — the gateway forwards max_tokens unchanged. A catalog-wide audit found no serving configuration imposes a fixed per-response output cap on any model; every configured limit is a total-sequence bound, a concurrency limit, or a prefill chunk size.

is_ready is OpenRouter's catalog publication flag, not an availability signal. Every proxied third-party model reports false while being fully serviceable, and the field is omitted entirely on others.

prompt_tokens_details

On a cache miss, TEE-hosted models return null rather than OpenAI's {"cached_tokens": 0}. The inference engine emits null and the gateway returns the provider's exact response bytes so the model-TEE signature verifies byte-for-byte; normalizing at the gateway would break chat verification. Documented as a known deviation with a client-side snippet.

OpenClaw guide and compatibility matrix

OpenClaw cannot consume supported_features, so it applies conservative defaults to an unrecognized provider and disables usage-in-streaming, strict mode, and the developer role. All three are supported. Adds the integration guide (following the integrations/README.md section contract) and a feature matrix mapping each OpenAI request feature to NEAR AI Cloud support.

Verification

npm run build passes. onBrokenLinks is set to throw, so every internal link resolves; no anchor warnings.

🤖 Generated with Claude Code