8.7 KiB
Provider Integration Flows
CCS routes profiles through direct target configuration or CLIProxy. This document describes the durable flow and trust boundaries. Mutable provider capabilities are linked to their source registries.
Sources of truth
| Detail | Authoritative source |
|---|---|
| Canonical provider IDs, aliases, auth-flow type, callback ports, refresh ownership | src/cliproxy/provider-capabilities.ts |
| Original vs Plus backend restrictions | src/cliproxy/types/provider-types.ts |
| Provider/backend enforcement | src/cliproxy/services/variant-service.ts |
| Remote proxy precedence and fallback | src/cliproxy/proxy/proxy-config-resolver.ts |
| Provider capability regression tests | src/cliproxy/__tests__/provider-capabilities.test.ts |
Do not copy provider inventories, callback ports, or quota-supported lists into this document. They change independently of the architecture.
Route selection
Resolved profile
|
+-- account profile
| └── target-native authenticated context
|
+-- settings/API profile
| └── direct or compatible upstream URL and credential environment
|
└-- CLIProxy provider
|
+-- reachable configured remote proxy
|
└-- local proxy, when selected or fallback is allowed
|
└── original or Plus backend
The provider route is resolved before the target adapter prepares credentials. This keeps provider selection independent from whether Claude Code, Droid, or Codex receives the route.
Local CLIProxy
CCS manages the local binary, generated configuration, auth files, lifecycle, and provider-specific launch environment.
The local backend contract is:
originalis the default upstream CLIProxy backend;plusis an explicit opt-in community-maintained distribution;- providers declared Plus-only fail clearly on the original backend; and
- CCS does not silently downgrade a configured Plus backend.
The management-panel repository is generated to match the selected backend unless the user supplies the supported override.
Local target traffic uses a provider-compatible endpoint and an internal credential. CLIProxy owns upstream OAuth token use and request translation according to the selected provider.
Remote CLIProxy
Remote mode delegates proxy lifecycle and stored authentication to another CLIProxy installation.
CLI flags and environment
|
v
CCS proxy configuration
|
v
Reachability check
+-----+-----+
| |
reachable unreachable
| |
remote remote-only? ---- yes ---> fail
|
no
|
fallback enabled? -- no ----> fail
|
yes
|
local proxy
Configuration precedence and accepted environment names are implemented in
proxy-config-resolver.ts.
The stable behavioral contract is:
- CLI flags override other sources where supported;
- environment can select a remote host;
- configuration supplies persistent remote settings;
- HTTPS and HTTP defaults remain protocol-aware;
--remote-onlydisables local fallback; and- an unreachable remote proxy falls back only when fallback is enabled.
A remote proxy is a separate trust boundary. Its operator can receive provider traffic and owns its stored OAuth state. Use TLS and authentication appropriate to that boundary.
Authentication
CCS asks the selected CLIProxy backend to start the provider's supported auth flow. The provider registry identifies whether that is an authorization-code flow, device-code flow, browser polling flow, or currently unsupported account linking.
Select canonical provider
|
Validate backend and auth-start support
|
Start backend-owned auth flow
|
User completes provider interaction
|
Backend writes provider auth file
|
CCS reconciles account identity and readiness
|
Launch through provider route
Provider tokens live under the configured CLIProxy auth directory. Documentation and examples must use neutral account labels; raw email addresses, token filenames, access tokens, and refresh tokens are not architecture data.
Some providers can produce more than one account with the same display email. CCS keeps runtime identity tied to the exact registered auth file rather than collapsing accounts by display text. The dashboard can show a safe variant label without exposing the internal identifier.
API-key profiles
API-key profiles store string-valued environment under the CCS profile settings file.
Create or edit API profile
|
Write CCS-owned <profile>.settings.json
|
Resolve direct/native vs compatible proxy-style auth
|
Target adapter prepares credentials
|
Spawn target
Native Anthropic profiles use ANTHROPIC_API_KEY without forcing a proxy base
URL. Compatible providers typically use ANTHROPIC_BASE_URL and
ANTHROPIC_AUTH_TOKEN. The profile writer owns that distinction; callers
should not infer it from documentation examples.
Normal launches do not write ~/.claude/settings.json. Users who want shared
Claude settings must select the explicit ccs persist workflow.
Legacy GLMT compatibility
glmt is a compatibility input, not a current provider architecture. Existing
legacy settings are normalized to the direct GLM path before normal
settings-profile dispatch. Internal GLMT transformer modules can remain in use
by other compatibility surfaces without making GLMT a supported standalone
runtime.
New configuration should use current API profile commands and provider names.
Quota and account-pool flow
Quota support is provider-specific and intentionally sourced from
provider-capabilities.ts.
The stable pool contract is:
- Reconcile registered accounts with live auth files.
- Exclude manually paused accounts from rotation.
- Fetch quota only for providers with an implemented quota fetcher.
- Distinguish an exhausted account from a provider-wide or transient failure.
- When a healthy fallback exists, CCS can create a temporary quota pause for an exhausted account.
- Persist the cooldown so later launches observe the same state.
- Auto-resume only pauses created by CCS quota management; never override a user's manual pause.
Routing strategy remains an explicit user choice. CCS must not infer round-robin or fill-first from account count, plan tier, or quota state.
Image analysis
For profiles that need managed vision support, CCS prepares the image-analysis route before launch:
Resolve profile and provider
|
Resolve supported provider backend
|
Provision managed MCP/runtime configuration
|
Target invokes ImageAnalysis
|
CCS sends provider-scoped request
|
Return text result
The managed route must not expose its internal credential in logs or user settings. If managed preparation, authentication, or proxy readiness is unavailable, CCS falls back to compatible native behavior where possible instead of failing the entire target launch.
Provider-specific vision mappings are implementation data and should be read from the image-analysis routing services and tests.
Session and observability boundary
Execution paths can record non-secret metadata such as profile identity, profile type, canonical provider, target type, timestamps, duration, and numeric process exit status. Logs must not contain provider tokens, API keys, raw auth payloads, or personal account identifiers.
Textual CCS log codes and numeric child-process exit statuses are different contracts. See Logging Contract.
Invariants
- Canonical provider identity is registry-driven.
- Provider aliases normalize before execution.
- Backend restrictions are validated before starting local auth or routing.
- Remote-only mode never starts a local fallback.
- Persistent environment values are strings.
- Account display text is not a unique runtime identity.
- Manual pauses are never auto-resumed by quota management.
- Provider credentials never appear in architecture examples.