A model's original vendor does not tell a desktop agent which HTTP interface to call. A gateway can serve models from several vendors through one contract, while a direct connection may need a different protocol for a particular model.
Putting the protocol choice on every model makes a large catalog tedious to configure. Guessing from a model name can also send the right model to the wrong interface.
AIClaw 3.7.32 introduces service-aware routing: resolve the connection contract first, apply scoped model rules where they are known, and keep manual exceptions in advanced settings. This is in the published release, rather than an unreleased proposal. All implementation links below are pinned to that tag.
Start with the service contract
The resolver identifies a service profile from the configured provider type. For an OpenAI-compatible entry, it also recognizes specific official endpoint hosts. An unfamiliar compatible gateway remains a generic compatible service; a model name containing a familiar vendor name does not reclassify it.
The resulting automatic behavior is deliberately bounded:
| Connection | Automatic route in this release |
|---|---|
| OpenRouter | Chat Completions, including models originating from other vendors |
| Direct OpenAI or Azure | Responses for exact model IDs in the versioned registry; Chat Completions otherwise |
| Native Claude service | Messages |
| Native Gemini service | Generate Content |
| Unknown compatible gateway | Chat Completions |
This table describes AIClaw's routing policy, not an exhaustive list of interfaces each upstream service offers. In particular, the OpenRouter policy does not mean the gateway only supports one API.
The routing implementation keeps the direct-service rules as exact IDs with a verification date and source links. Those rules are applied only to the corresponding service profiles.
A deployment alias that is absent from that registry stays unknown. There is no universal discovery mechanism here that can infer the capabilities of every custom deployment name.
Make exceptions explicit, without configuring every model
The route precedence is:
model protocol override > manual service protocol > automatic service strategy and built-in model rule Most models therefore inherit the service strategy. A user only needs an exception when the actual endpoint contract differs from that strategy.
The model service settings view places service and model protocol overrides in its advanced controls. Clearing a model override restores inheritance. The backend includes the effective protocol and its source in the model route view, so an inherited choice can be distinguished from a manual one.
The call path resolves the route before constructing a protocol client. It does not wait for a 400 response and then guess another protocol from the error text. An incorrect custom configuration can still fail; explicit routing makes that failure easier to explain without silently changing the requested behavior.
Keep capability metadata separate from the model list
A catalog supplies names, but a name is not proof that tools, images, or reasoning parameters are supported.
When fetching an OpenRouter catalog, AIClaw also reads explicit supported-parameter and input-modality fields. A missing field remains unknown; it does not automatically become “unsupported.” The metadata fetch preserves the user's manually maintained model list.
The cached metadata carries its service profile and base URL. Changing the endpoint prevents the resolver from using metadata scoped to the old endpoint.
There is also a concurrency boundary. Catalog fetching captures one provider record for the request, decoding, and cache provenance. Configuration writes advance a revision. The metadata cache write checks that captured revision before accepting the result.
If the address, key, or protocol changes while the fetch is running—or the service is deleted—the old result is rejected instead of being returned for merging into the current configuration. The user is asked to refresh the catalog again. The conditional store update implements that check without putting the key into its comparison predicate.
Apply edits at the next request boundary
Refreshing a connection and mutating a running request are different operations.
The agent's sampling client resolves the current provider configuration for each sample and constructs a new client snapshot. An HTTP request already in progress retains the snapshot it started with. The next sample can use the new protocol and credentials, including within the same agent turn.
This avoids requiring a conversation restart just to pick up a service edit. It also keeps one request's protocol and credentials together rather than changing part of its connection midstream.
The release has separate adapters for Chat Completions, Responses, Claude Messages, and Gemini Generate Content. Shared agent history does not make their authentication, message encoding, or stream termination rules identical. The design document describes those boundaries and the migration behavior for older service entries.
What was verified
For this article, I reran five focused Go tests against the source at the public release commit. All five passed:
- Service-contract routing, exact-rule provenance, override precedence, and unknown-model behavior.
- Scoped OpenRouter metadata, missing versus explicit capability fields, and preservation of manual models.
- Rejection of a catalog response after concurrent endpoint, key, protocol, or deletion changes, exercised as four subtests.
- A service edit taking effect at the next sample in one turn, followed by session restoration.
- Late usage from an earlier sample not being assigned to a replacement model.
The fixtures are in routing_test.go, catalog_snapshot_test.go, and model_client_test.go.
These checks use local HTTP fixtures and temporary application databases. They establish the resolver, snapshot, and stale-result behavior; they do not establish successful paid calls against every vendor or gateway. I did not rerun the full desktop suite for this article. The release notes separately report the broader release validation.
The practical gain is one service configuration that models can usually inherit, with visible exceptions when needed. The remaining limits are explicit: exact-ID rules need maintenance, custom aliases may require an override, and the selected model and endpoint still have to support the requested operation.
