mirror of
https://github.com/openclaw/openclaw.git
synced 2026-05-29 16:15:14 +00:00
bb46b79d3c
* refactor: extract agent core package Introduce packages/agent-core as the OpenClaw-owned home for reusable agent loop, harness, session, prompt, and runtime dependency contracts. * refactor: extract shared llm runtime Move provider model registries, stream wrappers, OAuth helpers, and LLM utilities into src/llm with plugin-sdk barrels instead of depending on the old embedded runtime layout. * refactor: remove pi runtime internals Rename remaining Pi-shaped agent surfaces to OpenClaw agent runtime names, delete obsolete Pi docs and package graph checks, and add the third-party notice for incorporated code. * refactor: tighten agent session runtime Make agent-core/runtime dependencies explicit, consolidate compaction and session transcript helpers, and move model/session helpers behind OpenClaw-owned contracts. * refactor: remove static model and pi auth paths Drop static model catalogs and Pi auth bridges, move model/provider facts to manifest-owned runtime contracts, and harden internal embedded-agent utilities. * refactor: remove legacy provider compat paths * docs: remove agent parity notes * fix: skip provider wildcard metadata parsing * refactor: share session extension sdk loading * refactor: inline acpx proxy error formatter * refactor: fold edit recovery into edit tool * fix: accept extension batch separator * test: align startup provider plugin expectations * fix: restore provider-scoped release discovery * test: align static asset packaging expectations * fix: run static provider catalogs during scoped discovery * fix: add provider entry catalogs for scoped live discovery * fix: load lightweight provider catalog entries * fix: refresh provider-scoped plugin metadata * fix: keep provider catalog entries on release live path * fix: keep static manifest models in release live checks * fix: harden release model discovery * fix: reduce OpenAI live cache probe reasoning * fix: disable OpenAI cache probe reasoning * ci: extend OpenAI gateway live timeout * fix: extend live gateway model budget * fix: stabilize release validation regressions * fix: honor provider aliases in model rows * fix: stabilize release validation lanes * fix: stabilize release memory qa * ci: stabilize release validation lanes * ci: prefer ipv4 for live docker node calls * fix: restore shared tool-call stream wrapper * ci: remove legacy pi test shard alias * fix: clean up embedded agent test drift * fix: stabilize runtime alias status * fix: clean up embedded agent ci drift * fix: restore release ci invariants * fix: clean up post-rebase runtime drift * fix: restore release ci checks * fix: restore release ci after rebase * fix: remove stale pi runtime path * test: align compaction runtime expectations * test: update plugin prerelease expectations * fix: handle claude live tool approvals * fix: stabilize release validation gates * fix: finish agent runtime import * test: finish post-rebase agent runtime mocks * fix: keep codex compaction native * fix: stabilize codex app-server hook tests * test: isolate codex diagnostic active run * test: remove codex diagnostic completion race # Conflicts: # extensions/codex/src/app-server/run-attempt.test.ts * ci: fix full release manifest performance run id * refactor: narrow llm plugin sdk boundary * chore: drop generated google boundary stamps * fix: repair rebase fallout * fix: clean up rebased runtime references * fix: decode codex jwt payloads as base64url * fix: preserve shipped pi runtime alias * fix: add scoped sdk virtual modules * fix: decode llm codex oauth jwt as base64url * fix: avoid stale vertex adc negative cache * fix: harden tool arg decoding and codeql path * fix: keep vertex adc negative checks live * refactor: consolidate codex jwt and edit helpers * fix: await codex oauth node runtime imports * fix: preserve sdk tool and notice contracts * fix: preserve shipped compat config boundaries * fix: align codex oauth callback host * fix: terminate agent-core loop streams on failure * fix: keep codex oauth callback alive during fallback * ci: include session tools in critical codeql scans * fix: keep Cloudflare Anthropic provider auth header * docs: redirect legacy pi runtime pages * fix: honor bundled web provider compat discovery * fix: protect session output spill files * fix: keep legacy agent dir env blocked * fix: contain auto-discovered skill symlinks * fix: harden agent core sdk proxy surfaces * fix: restore approval reaction sdk compat * fix: keep live docker runs bounded * fix: keep codex oauth redirect host aligned * fix: resolve post-rebase agent runtime drift * fix: redact anthropic oauth parse failures * fix: preserve responses strict tool shaping * fix: repair agent runtime rebase cleanup * docs: redirect retired parity pages * fix: bound auto-discovered resources to roots * fix: repair post-rebase agent test drift * fix: preserve bundled provider allowlist migration * fix: preserve manifest-owned provider aliases * fix: declare photon image dependency * fix: keep provider headers out of proxy body * fix: preserve shipped env aliases * fix: refresh control ui i18n generated state * fix: quote read fallback paths * fix: preview edits through configured backend * test: satisfy core test typecheck * fix: preserve ZAI usage auth fallback * test: repair codex diagnostic test * fix: repair agent runtime rebase drift * test: finish embedded runner import rename * fix: repair agent runtime rebase integrations * test: align compaction oauth fallback expectations * fix: allow sdk-auth session models * fix: update doctor tool schema import * fix: preserve bedrock plugin region * fix: stream harmony-like prose immediately * ci: include session runtime in codeql shards * fix: repair latest rebase integrations * fix: honor explicit codex websocket transport * fix: keep openai-compatible credentials provider-scoped * fix: refresh sdk api baseline after rebase * fix: route cli runtime aliases through openclaw harness * test: rename stale harness mock expectation * test: rename embedded agent overflow calls * test: clean embedded auth test wording * test: use openclaw stream types in deepinfra cache test * fix: refresh sdk api baseline on latest main * fix: honor bundled discovery compat allowlists * fix: refresh sdk api baseline after latest rebase * fix: remove stale rebase imports * test: rename stale model catalog mock * test: mock renamed doctor runtime modules * fix: map canonical kimi env auth * fix: use internal model registry in bench script * fix: migrate deepinfra provider catalog entry * fix: enforce builtin tool suppression * fix: route compaction auth and proxy payloads safely * refactor: prune unused llm registry leftovers * test: update codex hooks session import * test: fix model picker ci coverage * test: align model picker auth mock types
125 lines
4.9 KiB
Markdown
125 lines
4.9 KiB
Markdown
---
|
|
summary: "Canonical credential eligibility and resolution semantics for auth profiles"
|
|
title: "Auth credential semantics"
|
|
read_when:
|
|
- Working on auth profile resolution or credential routing
|
|
- Debugging model auth failures or profile order
|
|
---
|
|
|
|
This document defines the canonical credential eligibility and resolution semantics used across:
|
|
|
|
- `resolveAuthProfileOrder`
|
|
- `resolveApiKeyForProfile`
|
|
- `models status --probe`
|
|
- `doctor-auth`
|
|
|
|
The goal is to keep selection-time and runtime behavior aligned.
|
|
|
|
## Stable probe reason codes
|
|
|
|
- `ok`
|
|
- `excluded_by_auth_order`
|
|
- `missing_credential`
|
|
- `invalid_expires`
|
|
- `expired`
|
|
- `unresolved_ref`
|
|
- `no_model`
|
|
|
|
## Token credentials
|
|
|
|
Token credentials (`type: "token"`) support inline `token` and/or `tokenRef`.
|
|
|
|
### Eligibility rules
|
|
|
|
1. A token profile is ineligible when both `token` and `tokenRef` are absent.
|
|
2. `expires` is optional.
|
|
3. If `expires` is present, it must be a finite number greater than `0`.
|
|
4. If `expires` is invalid (`NaN`, `0`, negative, non-finite, or wrong type), the profile is ineligible with `invalid_expires`.
|
|
5. If `expires` is in the past, the profile is ineligible with `expired`.
|
|
6. `tokenRef` does not bypass `expires` validation.
|
|
|
|
### Resolution rules
|
|
|
|
1. Resolver semantics match eligibility semantics for `expires`.
|
|
2. For eligible profiles, token material may be resolved from inline value or `tokenRef`.
|
|
3. Unresolvable refs produce `unresolved_ref` in `models status --probe` output.
|
|
|
|
## Agent copy portability
|
|
|
|
Agent auth inheritance is read-through. When an agent has no local profile, it
|
|
can resolve profiles from the default/main agent store at runtime without
|
|
copying secret material into its own `auth-profiles.json`.
|
|
|
|
Explicit copy flows, such as `openclaw agents add`, use this portability policy:
|
|
|
|
- `api_key` profiles are portable unless `copyToAgents: false`.
|
|
- `token` profiles are portable unless `copyToAgents: false`.
|
|
- `oauth` profiles are not portable by default because refresh tokens can be
|
|
single-use or rotation-sensitive.
|
|
- Provider-owned OAuth flows may opt in with `copyToAgents: true` only when
|
|
copying refresh material across agents is known safe.
|
|
|
|
Non-portable profiles remain available through read-through inheritance unless
|
|
the target agent signs in separately and creates its own local profile.
|
|
|
|
## Config-only auth routes
|
|
|
|
`auth.profiles` entries with `mode: "aws-sdk"` are routing metadata, not stored
|
|
credentials. They are valid when the target provider uses
|
|
`models.providers.<id>.auth: "aws-sdk"` or plugin-owned Amazon Bedrock setup
|
|
AWS SDK route. These profile ids may appear in `auth.order` and session
|
|
overrides even when no matching entry exists in `auth-profiles.json`.
|
|
|
|
Do not write `type: "aws-sdk"` into `auth-profiles.json`. If a legacy install
|
|
has such a marker, `openclaw doctor --fix` moves it to `auth.profiles` and
|
|
removes the marker from the credential store.
|
|
|
|
## Explicit auth order filtering
|
|
|
|
- When `auth.order.<provider>` or the auth-store order override is set for a
|
|
provider, `models status --probe` only probes profile ids that remain in the
|
|
resolved auth order for that provider.
|
|
- A stored profile for that provider that is omitted from the explicit order is
|
|
not silently tried later. Probe output reports it with
|
|
`reasonCode: excluded_by_auth_order` and the detail
|
|
`Excluded by auth.order for this provider.`
|
|
|
|
## Probe target resolution
|
|
|
|
- Probe targets can come from auth profiles, environment credentials, or
|
|
`models.json`.
|
|
- If a provider has credentials but OpenClaw cannot resolve a probeable model
|
|
candidate for it, `models status --probe` reports `status: no_model` with
|
|
`reasonCode: no_model`.
|
|
|
|
## External CLI credential discovery
|
|
|
|
- Runtime-only credentials owned by external CLIs are discovered only when the
|
|
provider, runtime, or auth profile is in scope for the current operation, or
|
|
when a stored local profile for that external source already exists.
|
|
- Auth-store callers should choose an explicit external-CLI discovery mode:
|
|
`none` for persisted/plugin auth only, `existing` for refreshing already
|
|
stored external CLI profiles, or `scoped` for a concrete provider/profile set.
|
|
- Read-only/status paths pass `allowKeychainPrompt: false`; they use file-backed
|
|
external CLI credentials only and do not read or reuse macOS Keychain results.
|
|
|
|
## OAuth SecretRef Policy Guard
|
|
|
|
- SecretRef input is for static credentials only.
|
|
- If a profile credential is `type: "oauth"`, SecretRef objects are not supported for that profile credential material.
|
|
- If `auth.profiles.<id>.mode` is `"oauth"`, SecretRef-backed `keyRef`/`tokenRef` input for that profile is rejected.
|
|
- Violations are hard failures in startup/reload auth resolution paths.
|
|
|
|
## Legacy-Compatible Messaging
|
|
|
|
For script compatibility, probe errors keep this first line unchanged:
|
|
|
|
`Auth profile credentials are missing or expired.`
|
|
|
|
Human-friendly detail and stable reason codes may be added on subsequent lines.
|
|
|
|
## Related
|
|
|
|
- [Secrets management](/gateway/secrets)
|
|
- [Auth storage](/concepts/oauth)
|