Skip to content

feat: route canonical provider models through ClawRouter#94012

Closed
vincentkoc wants to merge 2 commits into
mainfrom
feat/clawrouter-transport-routing
Closed

feat: route canonical provider models through ClawRouter#94012
vincentkoc wants to merge 2 commits into
mainfrom
feat/clawrouter-transport-routing

Conversation

@vincentkoc

@vincentkoc vincentkoc commented Jun 17, 2026

Copy link
Copy Markdown
Member

Summary

  • adds generic plugin hooks for credential-scoped model transport routing
  • adds a ClawRouter plugin that routes canonical provider models through the gateway without inventing clawrouter/... model IDs
  • caches the gateway catalog per credential profile and preserves provider-specific request formats while rewriting only the outbound route and gateway authentication

Why

ClawRouter should be an optional control-plane and proxy layer for normal provider configuration, not another model provider. A maintainer keeps using canonical models such as openai/gpt-... or anthropic/claude-...; selecting a ClawRouter credential profile controls whether that call is routed through the gateway.

Impact

  • provider credentials are stripped before gateway dispatch and replaced with the ClawRouter bearer credential
  • direct, embedded, simple-completion, compaction, failover, and /btw paths resolve the same late transport route
  • ClawRouter supports multiple credential profiles with independent catalog access
  • response model identity remains canonical while the upstream gateway model alias is retained separately

Validation

  • 482 focused tests passed in Blacksmith Testbox
  • autoreview clean
  • formatting, lint, plugin SDK generation and export checks, import-boundary checks, and import-cycle checks passed
  • full Testbox TypeScript build remains blocked by an unrelated missing cross-spawn declaration in src/agents/utils/child-process.ts

Deployment status

Code only. No production ClawRouter configuration or deployment is included.

Remaining risk

This branch is currently behind main and needs a rebase plus final merge validation before landing.

@openclaw-barnacle openclaw-barnacle Bot added docs Improvements or additions to documentation agents Agent runtime and tooling extensions: google size: XL maintainer Maintainer-authored PR labels Jun 17, 2026
@clawsweeper

clawsweeper Bot commented Jun 17, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

Codex review: found issues before merge. Reviewed June 26, 2026, 3:07 PM ET / 19:07 UTC.

Summary
The PR adds credential-scoped provider transport routing hooks, a bundled ClawRouter plugin, dispatch-route model metadata, and runtime/auth updates so canonical provider models can be routed through a ClawRouter gateway profile.

PR surface: Source +993, Tests +1020, Config +31, Generated 0, Other +6. Total +2050 across 46 files.

Reproducibility: not applicable. as a user bug reproduction because this is a feature PR. Source inspection does show a high-confidence fail-open path for selected ClawRouter profiles, but I did not run a live ClawRouter setup.

Review metrics: 1 noteworthy metric.

  • Config and SDK surfaces: 2 provider hooks added, 2 plugin config keys added, 1 env/CLI credential added. These surfaces affect plugin authors, setup/onboarding, and provider auth routing, so maintainers need upgrade and ownership proof before merge.

Root-cause cluster
Relationship: canonical
Canonical: #94012
Summary: This PR is the current open successor for ClawRouter canonical-provider routing; the earlier synthetic-provider implementation was merged and then reverted.

Members:

Proposal only: this assessment does not dispatch repair, suppress jobs, mutate sibling items, close, or merge anything.

Merge readiness
Overall: 🧂 unranked krab
Proof: 🌊 off-meta tidepool
Patch quality: 🧂 unranked krab
Result: blocked by patch quality or review findings.

Overall follows the weaker of proof and patch quality, so missing proof can cap an otherwise strong patch.

Rank-up moves:

  • [P1] Make explicit ClawRouter profile failures fail closed with focused coverage across runtime entry points.
  • Document the new SDK hooks and ClawRouter credential/config semantics before treating them as public API.
  • [P2] Add the ClawRouter labeler mapping, rebase the dirty draft branch, and rerun final validation.

Risk before merge

  • [P1] An explicitly selected clawrouter:* profile can lose its prepared route on catalog/auth/entitlement failure and continue toward direct canonical provider auth instead of failing closed.
  • [P1] The PR adds public Plugin SDK hooks plus plugin config/env/CLI credential surfaces without maintainer-visible docs for semantics, failure behavior, and upgrade/operator expectations.
  • [P1] The branch is draft and dirty against main; a rebase plus final validation is needed before the security-sensitive routing change can be considered for landing.
  • [P1] The PR body has focused Testbox/test claims but no redacted live OpenClaw-to-ClawRouter proof of gateway dispatch and denied-route failure behavior.

Maintainer options:

  1. Fail closed for selected ClawRouter profiles (recommended)
    Make catalog, auth, and entitlement failure terminal whenever authProfileId or preferredProfile is clawrouter-scoped, then cover embedded, simple-completion, compaction, and /btw paths.
  2. Document the SDK and operator contract
    Before merge, document prepareModelTransportRoute and routeModelTransport semantics, auth-profile selection, failure behavior, and ClawRouter credential/config expectations.
  3. Pause until fallback policy is explicit
    If maintainers intentionally want best-effort direct-provider fallback, keep the PR draft until that security and operator policy is explicitly accepted and documented.

Next step before merge

  • Manual review is appropriate because this protected maintainer draft changes provider routing, public SDK, config/credential surfaces, and security semantics.

Security
Needs attention: The diff is security-sensitive because it changes credential ownership and gateway dispatch, and the selected-profile failure path can currently fall back toward direct provider auth.

Review findings

  • [P1] Fail closed for locked ClawRouter profiles — extensions/clawrouter/transport-router.ts:303-308
  • [P2] Document the new provider routing hooks — src/plugins/types.ts:1362-1376
  • [P3] Add the ClawRouter labeler mapping — extensions/clawrouter/openclaw.plugin.json:2-7
Review details

Best possible solution:

Land a rebased ClawRouter design only after selected gateway profiles fail closed, SDK/config docs and label ownership are aligned, and redacted live proof shows canonical dispatch through ClawRouter plus denied routes failing closed.

Do we have a high-confidence way to reproduce the issue?

Not applicable as a user bug reproduction because this is a feature PR. Source inspection does show a high-confidence fail-open path for selected ClawRouter profiles, but I did not run a live ClawRouter setup.

Is this the best way to solve the issue?

No: the canonical-provider direction is plausible, but the current branch is not the best merge state until explicit ClawRouter profile failures are terminal and the public SDK/config contract is documented.

Full review comments:

  • [P1] Fail closed for locked ClawRouter profiles — extensions/clawrouter/transport-router.ts:303-308
    When a user explicitly selects a clawrouter-scoped profile, catalog/auth/entitlement failure is swallowed and routeModelTransport can return undefined. The runner can then continue as the canonical provider, so a gateway-controlled run may bypass ClawRouter instead of failing with a clear routing error.
    Confidence: 0.88
  • [P2] Document the new provider routing hooks — src/plugins/types.ts:1362-1376
    These hooks are exported as provider-plugin contract surface, but the provider-plugin docs still stop at the existing dynamic/normalize hooks and do not explain routing, async preparation, auth-profile semantics, or failure behavior. Plugin authors need that contract before this public SDK surface lands.
    Confidence: 0.8
  • [P3] Add the ClawRouter labeler mapping — extensions/clawrouter/openclaw.plugin.json:2-7
    This adds a new bundled plugin under extensions/clawrouter, but the branch does not add a ClawRouter entry to .github/labeler.yml. Future ClawRouter changes will miss the dedicated ownership label until the mapping is added.
    Confidence: 0.82

Overall correctness: patch is incorrect
Overall confidence: 0.78

AGENTS.md: found and applied where relevant.

Codex review notes: model internal, reasoning high; reviewed against e5123e44b0f5.

Label changes

Label justifications:

  • P2: This is a substantial unshipped provider-routing feature with concrete pre-merge blockers but no active production outage.
  • merge-risk: 🚨 compatibility: The PR adds public Plugin SDK hooks plus plugin config/env/CLI credential surfaces that require documented semantics and upgrade expectations.
  • merge-risk: 🚨 auth-provider: The diff changes which provider owns runtime credentials and auth-profile failover for canonical model dispatch.
  • merge-risk: 🚨 security-boundary: The diff strips provider credentials and replaces them with gateway credentials, while the current failure path can bypass ClawRouter when a gateway profile was selected.
  • rating: 🧂 unranked krab: Overall readiness is 🧂 unranked krab; proof is 🌊 off-meta tidepool and patch quality is 🧂 unranked krab.
  • status: ⏳ waiting on author: ClawSweeper has contributor-facing work open and is waiting for author action. Not applicable: The external-contributor proof gate does not apply to this maintainer-labeled member PR, but redacted live OpenClaw/ClawRouter proof remains important before landing the security-sensitive routing behavior.
Evidence reviewed

PR surface:

Source +993, Tests +1020, Config +31, Generated 0, Other +6. Total +2050 across 46 files.

View PR surface stats
Area Files Added Removed Net
Source 27 1122 129 +993
Tests 15 1021 1 +1020
Docs 0 0 0 0
Config 2 31 0 +31
Generated 1 2 2 0
Other 1 6 0 +6
Total 46 2182 132 +2050

Security concerns:

  • [high] Selected gateway profiles can fail open — extensions/clawrouter/transport-router.ts:303
    ClawRouter route preparation swallows errors and missing grants return undefined; when dispatch metadata disappears, later auth-profile validation can clear the selected clawrouter profile and continue toward canonical provider auth.
    Confidence: 0.82

What I checked:

  • Repository policy applied: Root and scoped AGENTS.md guidance were read; provider routing, plugin SDK hooks, auth/profile state, config/default additions, and fallback behavior are compatibility-sensitive review surfaces. (AGENTS.md:20, e5123e44b0f5)
  • Live PR state: GitHub reports this PR as draft, dirty, and still on head 2d22ef4 with maintainer and merge-risk labels already present. (2d22ef440732)
  • Current main does not already implement the feature: Current main has no ClawRouter plugin, routeModelTransport hooks, prepareModelTransportRoute hooks, or ModelDispatchRoute type, so the PR is not implemented on main. (e5123e44b0f5)
  • Selected route failures can fall through: The ClawRouter router swallows prepareRoute errors and routeModelTransport returns undefined when no prepared route exists, leaving the canonical provider path intact even for a selected gateway profile. (extensions/clawrouter/transport-router.ts:303, 2d22ef440732)
  • Locked profile validation can clear the gateway profile: The runner compares the locked profile provider against the resolved dispatch auth provider; if routing disappeared and authProvider falls back to the canonical provider, the clawrouter profile can be cleared before direct auth continues. (src/agents/embedded-agent-runner/run.ts:1167, 2d22ef440732)
  • Added tests do not prove explicit profile termination: The added fail-closed test expects routeModelTransport to be undefined for a denied catalog row, but it does not prove a user-selected clawrouter profile terminates instead of falling back to canonical provider auth. (extensions/clawrouter/transport-router.test.ts:115, 2d22ef440732)

Likely related people:

  • vincentkoc: Prior merged ClawRouter add/revert PRs, recent model/runner refactors, and this successor design all point to this person as the strongest routing candidate beyond simply opening this PR. (role: likely feature owner and recent area contributor; confidence: high; commits: caad9451943f, 0159fa3cfe78, 206552c6977b; files: extensions/clawrouter/*, src/agents/embedded-agent-runner/model.ts, src/agents/embedded-agent-runner/run.ts)
  • jalehman: Recent current-main history touched the embedded runner seam that this PR changes for model/auth routing. (role: recent adjacent contributor; confidence: medium; commits: 0dfa22c6e0fc; files: src/agents/embedded-agent-runner/run.ts)
  • obviyus: Recent provider/model routing work touched central model resolution and plugin type surfaces adjacent to the new transport-route hooks. (role: recent adjacent contributor; confidence: medium; commits: 501f63443f54, dae2bcf31bc9; files: src/agents/embedded-agent-runner/model.ts, src/plugins/types.ts)
What the crustacean ranks mean
  • 🦀 challenger crab: rare, exceptional readiness with strong proof, clean implementation, and convincing validation.
  • 🦞 diamond lobster: very strong readiness with only minor maintainer review expected.
  • 🐚 platinum hermit: good normal PR, likely mergeable with ordinary maintainer review.
  • 🦐 gold shrimp: useful signal, but proof or patch confidence is still limited.
  • 🦪 silver shellfish: thin signal; proof, validation, or implementation needs work.
  • 🧂 unranked krab: not merge-ready because proof is missing/unusable or there are serious correctness or safety concerns.
  • 🌊 off-meta tidepool: rating does not apply to this item.

Shiny media proof means a screenshot, video, or linked artifact directly shows the changed behavior. Runtime, network, CSP, and security claims still need visible diagnostics.

How this review workflow works
  • ClawSweeper keeps one durable marker-backed review comment per issue or PR.
  • Re-runs edit this comment so the latest verdict, findings, and automation markers stay together instead of adding duplicate bot comments.
  • A fresh review can be triggered by eligible @clawsweeper re-review comments, exact-item GitHub events, scheduled/background review runs, or manual workflow dispatch.
  • PR/issue authors and users with repository write access can comment @clawsweeper re-review or @clawsweeper re-run on an open PR or issue to request a fresh review only.
  • Maintainers can also comment @clawsweeper review to request a fresh review only.
  • Fresh-review commands do not start repair, autofix, rebase, CI repair, or automerge.
  • Maintainer-only repair and merge flows require explicit commands such as @clawsweeper autofix, @clawsweeper automerge, @clawsweeper fix ci, or @clawsweeper address review.
  • Maintainers can comment @clawsweeper explain to ask for more context, or @clawsweeper stop to stop active automation.

@clawsweeper clawsweeper Bot added rating: 🦪 silver shellfish Thin PR readiness signal; proof, validation, or implementation needs work. status: ⏳ waiting on author ClawSweeper has contributor-facing work open and is waiting for author action. rating: 🧂 unranked krab Not merge-ready due to missing proof or serious correctness/safety concerns. P2 Normal backlog priority with limited blast radius. merge-risk: 🚨 compatibility 🚨 May break existing users, config, migrations, defaults, or upgrade paths. merge-risk: 🚨 auth-provider 🚨 May break OAuth, tokens, provider routing, model choice, or credentials. merge-risk: 🚨 security-boundary 🚨 May affect sandboxing, authorization, credentials, or sensitive data. status: 📣 needs proof The PR needs real behavior proof before ClawSweeper can clear the contributor ask. and removed rating: 🦪 silver shellfish Thin PR readiness signal; proof, validation, or implementation needs work. status: ⏳ waiting on author ClawSweeper has contributor-facing work open and is waiting for author action. labels Jun 17, 2026
@clawsweeper clawsweeper Bot added status: ⏳ waiting on author ClawSweeper has contributor-facing work open and is waiting for author action. and removed status: 📣 needs proof The PR needs real behavior proof before ClawSweeper can clear the contributor ask. labels Jun 26, 2026
This was referenced Jul 3, 2026
Closed
Merged
@steipete ChatGPT Codex Connector

steipete commented Jul 4, 2026

Copy link
Copy Markdown
Contributor

Superseded by #99658 and the auth-profile follow-up #99759, both now on main. The landed implementation covers credential-scoped catalog discovery, supported transport routing, quota reporting, and runtime auth-profile model resolution. Closing this older draft to keep one canonical implementation path. Thank you for the original exploration and design work.

@steipete steipete closed this Jul 4, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

agents Agent runtime and tooling docs Improvements or additions to documentation extensions: google maintainer Maintainer-authored PR merge-risk: 🚨 auth-provider 🚨 May break OAuth, tokens, provider routing, model choice, or credentials. merge-risk: 🚨 compatibility 🚨 May break existing users, config, migrations, defaults, or upgrade paths. merge-risk: 🚨 security-boundary 🚨 May affect sandboxing, authorization, credentials, or sensitive data. P2 Normal backlog priority with limited blast radius. rating: 🧂 unranked krab Not merge-ready due to missing proof or serious correctness/safety concerns. size: XL status: ⏳ waiting on author ClawSweeper has contributor-facing work open and is waiting for author action.

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@vincentkoc @steipete