Skip to content

feat(providers): add ClawRouter managed proxy#93832

Merged
vincentkoc merged 16 commits into
mainfrom
feat/clawrouter-provider
Jun 17, 2026
Merged

feat(providers): add ClawRouter managed proxy#93832
vincentkoc merged 16 commits into
mainfrom
feat/clawrouter-provider

Conversation

@vincentkoc

@vincentkoc vincentkoc commented Jun 17, 2026

Copy link
Copy Markdown
Member

Summary

  • add a bundled clawrouter provider backed by ClawRouter's credential-scoped live catalog
  • preserve native OpenAI, Anthropic, and Gemini request semantics while routing them through one managed proxy credential
  • resolve managed secret refs at discovery and request dispatch without process-global credential state
  • keep public catalog model ids stable and apply upstream model routing only at the request boundary

Intentionally out of scope: silently replacing existing openai/*, anthropic/*, or other provider namespaces. Users explicitly select clawrouter/<provider>/<model>.

Linked context

Related: openclaw/clawrouter#31

Requested by a maintainer/owner as the OpenClaw integration for ClawRouter.

Real behavior proof (required for external PRs)

  • Behavior or issue addressed: OpenClaw can discover and dispatch models through ClawRouter while ClawRouter remains the upstream credential authority.
  • Real environment tested: production https://clawrouter.openclaw.ai on ClawRouter commit ab73a19ca4a8564007fd54ad196e746e62ccdd8e.
  • Exact steps or command run after this patch: deployed the matching ClawRouter catalog/auth contract, then ran its mandatory authenticated deployed smoke and live OpenAI provider smoke.
  • Evidence after fix: https://github.com/openclaw/clawrouter/actions/runs/27657825237
  • Observed result after fix: authenticated catalog contract, deployed smoke, and live provider smoke passed. OpenClaw focused provider/runtime coverage passed locally.
  • What was not tested: a full interactive OpenClaw session against the production proxy.
  • Proof limitations or environment constraints: production smoke proves the live dependency and upstream path; OpenClaw request composition is covered by focused provider and runtime regression tests.

Tests and validation

  • node_modules/.bin/vitest run extensions/clawrouter/index.test.ts extensions/clawrouter/provider-catalog.test.ts src/agents/provider-stream.test.ts src/agents/btw.test.ts (101 passed)
  • focused oxfmt, oxlint, and git diff --check
  • .agents/skills/autoreview/scripts/autoreview --mode branch --base origin/main with deployed contract context (clean)
  • remote pnpm check:changed through Crabbox (running; draft stays open until green)

Regression coverage includes credential-scoped catalog discovery, native route selection, managed secret refs, stable model ids, request-boundary rewriting, native replay policy, direct stream wrappers, /btw, and runtime auth composition.

Risk checklist

Did user-visible behavior change? Yes

Did config, environment, or migration behavior change? Yes - adds CLAWROUTER_API_KEY and a bundled provider.

Did security, auth, secrets, network, or tool execution behavior change? Yes - adds credential-scoped catalog discovery and request dispatch through ClawRouter.

Highest risk: composing runtime-managed credentials with native provider transports. Mitigation: request-boundary model rewriting, no process-global credential cache, provider wrappers on direct paths, ClawRouter edge credential stripping, and focused regression coverage.

Current review state

Next action: wait for the authoritative Crabbox changed-gate, mark ready, then use the repo-native prepare and merge flow.

Addressed autoreview findings across native route selection, managed auth isolation, stable catalog ids, Gemini streaming requirements, direct stream paths, and runtime auth composition. The final review is clean.

@vincentkoc vincentkoc self-assigned this Jun 17, 2026
@vincentkoc vincentkoc added the extensions: clawrouter Extension: clawrouter label Jun 17, 2026
@openclaw-barnacle openclaw-barnacle Bot added docs Improvements or additions to documentation scripts Repository scripts agents Agent runtime and tooling size: XL maintainer Maintainer-authored PR labels Jun 17, 2026
@vincentkoc vincentkoc mentioned this pull request Jun 17, 2026
Closed
@clawsweeper

clawsweeper Bot commented Jun 17, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

Codex review: needs changes before merge. Reviewed June 16, 2026, 9:31 PM ET / 01:31 UTC.

Summary
This PR adds a bundled ClawRouter provider, docs, auth choice, live catalog parsing, provider wrappers, and focused tests for routing managed proxy credentials through native provider transports.

PR surface: Source +564, Tests +588, Docs +85, Config +28, Other +7. Total +1272 across 22 files.

Reproducibility: yes. by source inspection: ClawRouter native rows require prepareClawRouterRequestModel, but the normal embedded-agent and compaction callers do not set applyProviderWrapper at the current PR head.

Review metrics: 1 noteworthy metric.

  • New provider auth surface: 1 env var, 1 auth choice, 1 provider namespace added. Provider credentials and setup surfaces affect operator configuration and should be reviewed before this bundled provider ships.

Stored data model
Persistent data-model change detected: persistent cache schema: docs/providers/clawrouter.md. Confirm migration or upgrade compatibility proof before merge.

Merge readiness
Overall: 🧂 unranked krab
Proof: 🦐 gold shrimp
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:

  • Apply wrapper composition to normal embedded-agent and compaction paths.
  • [P2] Add a regression test for a normal ClawRouter Anthropic or Gemini agent run rewriting to the upstream model id.
  • Finish the authoritative changed-gate at the exact head.

Risk before merge

  • [P1] Normal agent and compaction paths can still bypass the ClawRouter wrapper, so native Anthropic/Gemini rows may dispatch the public ClawRouter model id instead of the upstream id.
  • [P1] This adds a new provider namespace and proxy credential surface; the draft should not land until wrapper coverage and the authoritative changed-gate are clean.

Maintainer options:

  1. Fix wrapper coverage before merge (recommended)
    Apply the provider wrapper to normal embedded-agent, compaction, and other boundary-transport fallback paths that can dispatch ClawRouter native models.
  2. Narrow the first landing
    Maintainers could initially support only OpenAI-compatible ClawRouter rows and defer native Anthropic/Gemini routing until wrapper coverage is proven.
  3. Keep the draft paused
    Keep the draft open without landing until the changed-gate and ClawRouter live contract proof are reviewable at the exact head.
Copy recommended automerge instruction 
@clawsweeper automerge

Special instructions:
Apply the provider wrapper to all registerProviderStreamForModel runtime paths that can dispatch ClawRouter native models, especially embedded-agent attempts and compaction, and add focused regression coverage for a normal ClawRouter Anthropic or Gemini run rewriting to the upstream model id.

Next step before merge

  • [P2] The remaining blocker is a concrete wrapper-coverage defect that automation can attempt on the PR branch, while final landing still needs maintainer proof gates.

Security
Cleared: No concrete supply-chain issue was found; the credential-sensitive routing problem is tracked as an auth-provider merge risk.

Review findings

  • [P1] Apply the ClawRouter wrapper on normal runtime paths — src/agents/provider-stream.ts:49-51
Review details

Best possible solution:

Compose the ClawRouter wrapper on every runtime path that can use boundary transports, then land only after focused runtime coverage and changed-gate proof are green.

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

Yes, by source inspection: ClawRouter native rows require prepareClawRouterRequestModel, but the normal embedded-agent and compaction callers do not set applyProviderWrapper at the current PR head.

Is this the best way to solve the issue?

No. The provider implementation is plausible, but the best fix is to make wrapper composition cover normal runtime paths, not only /btw and the focused helper path.

Full review comments:

  • [P1] Apply the ClawRouter wrapper on normal runtime paths — src/agents/provider-stream.ts:49-51
    The new wrapper only runs when callers pass applyProviderWrapper, but the main embedded-agent and compaction callers still omit that flag. ClawRouter native Anthropic/Gemini rows rely on prepareClawRouterRequestModel to rewrite the public ClawRouter model id to the upstream id, so normal sessions can bypass the rewrite while /btw works.
    Confidence: 0.89

Overall correctness: patch is incorrect
Overall confidence: 0.86

AGENTS.md: found and applied where relevant.

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

Label changes

Label justifications:

  • P2: This is a normal-priority provider feature with a blocking runtime-routing defect but no evidence of impact to existing shipped users.
  • merge-risk: 🚨 auth-provider: The diff adds credential-scoped provider routing through ClawRouter, and the wrapper coverage gap can break native model dispatch.
  • rating: 🧂 unranked krab: Overall readiness is 🧂 unranked krab; proof is 🦐 gold shrimp 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 PR is maintainer-authored, so the external-contributor proof gate does not apply; linked ClawRouter live smoke evidence is useful validation context but not a substitute for exact-head changed-gate proof.
Evidence reviewed

PR surface:

Source +564, Tests +588, Docs +85, Config +28, Other +7. Total +1272 across 22 files.

View PR surface stats
Area Files Added Removed Net
Source 7 574 10 +564
Tests 4 588 0 +588
Docs 6 87 2 +85
Config 3 28 0 +28
Generated 0 0 0 0
Other 2 7 0 +7
Total 22 1284 12 +1272

Acceptance criteria:

  • [P1] node scripts/run-vitest.mjs extensions/clawrouter/index.test.ts extensions/clawrouter/provider-catalog.test.ts src/agents/provider-stream.test.ts src/agents/btw.test.ts src/agents/embedded-agent-runner/stream-resolution.test.ts.
  • [P1] node scripts/run-vitest.mjs src/agents/embedded-agent-runner/compact.hooks.test.ts src/agents/embedded-agent-runner/run.overflow-compaction.test.ts.
  • [P1] node scripts/crabbox-wrapper.mjs run -- env OPENCLAW_CHECK_CHANGED_REMOTE_CHILD=1 OPENCLAW_CHANGED_LANES_RAW_SYNC=1 corepack pnpm check:changed.

What I checked:

Likely related people:

  • vincentkoc: The PR branch authors the ClawRouter provider, and current-main blame also points to this person on the shared provider-stream seam. (role: proposed feature owner and recent area contributor; confidence: high; commits: 8b14aaea7f49, 4e440a03e608, e17297f7dc82; files: extensions/clawrouter/index.ts, extensions/clawrouter/provider-catalog.ts, extensions/clawrouter/stream.ts)
  • ragesaq: Recent history identifies this person on the runtime settings and boundary-aware stream seam that this provider wrapper path builds on. (role: recent adjacent area contributor; confidence: medium; commits: f94a2506d218; files: src/agents/provider-stream.ts, src/agents/provider-transport-stream.ts, src/agents/embedded-agent-runner/stream-resolution.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: 🧂 unranked krab Not merge-ready due to missing proof or serious correctness/safety concerns. status: ⏳ waiting on author ClawSweeper has contributor-facing work open and is waiting for author action. P2 Normal backlog priority with limited blast radius. merge-risk: 🚨 auth-provider 🚨 May break OAuth, tokens, provider routing, model choice, or credentials. labels Jun 17, 2026
@vincentkoc
vincentkoc force-pushed the feat/clawrouter-provider branch from 4e440a0 to 1a312aa Compare June 17, 2026 03:06
@vincentkoc
vincentkoc marked this pull request as ready for review June 17, 2026 03:17
@vincentkoc
vincentkoc requested a review from a team as a code owner June 17, 2026 03:17
@github-actions github-actions Bot added the dependencies-changed PR changes dependency-related files label Jun 17, 2026
@github-actions

github-actions Bot commented Jun 17, 2026

Copy link
Copy Markdown
Contributor

Dependency Guard

This PR changes dependency-related files. Maintainers should confirm these changes are intentional.

Changed files:

  • extensions/clawrouter/package.json
  • pnpm-lock.yaml

Maintainer follow-up:

  • Review whether the dependency changes are intentional.
  • Inspect resolved package deltas when lockfile, shrinkwrap, or workspace dependency policy changes are present.
  • Treat package-lock.json and npm-shrinkwrap.json diffs as security-review surfaces.
  • Run pnpm deps:changes:report -- --base-ref origin/main --markdown /tmp/dependency-changes.md --json /tmp/dependency-changes.json locally for detailed release-style evidence.

@github-actions

github-actions Bot commented Jun 17, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

Dependency graph changes noted

This PR includes dependency graph changes. The dependency guard is informational because the PR author is a repository admin or a member of @openclaw/openclaw-secops.

  • Current SHA: 11a3f74de3f5d1e48ad13a6007ec5f9e74ffac5b
  • Trusted actor: @vincentkoc
  • Trusted role: pull request author; openclaw-secops

Security review is still recommended before merge when the dependency graph change is intentional.

@vincentkoc
vincentkoc force-pushed the feat/clawrouter-provider branch from 8e8da16 to 11a3f74 Compare June 17, 2026 03:38
@vincentkoc
vincentkoc merged commit 8c61390 into main Jun 17, 2026
166 checks passed
@vincentkoc
vincentkoc deleted the feat/clawrouter-provider branch June 17, 2026 03:47
This was referenced Jul 1, 2026
Closed
Closed
Merged
@clawsweeper clawsweeper Bot mentioned this pull request Jul 13, 2026
Merged
2 tasks
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

@vincentkoc vincentkoc

Labels

agents Agent runtime and tooling dependencies-changed PR changes dependency-related files docs Improvements or additions to documentation extensions: clawrouter Extension: clawrouter maintainer Maintainer-authored PR merge-risk: 🚨 auth-provider 🚨 May break OAuth, tokens, provider routing, model choice, or credentials. P2 Normal backlog priority with limited blast radius. rating: 🧂 unranked krab Not merge-ready due to missing proof or serious correctness/safety concerns. scripts Repository scripts 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.

1 participant

@vincentkoc