diff --git a/CHANGELOG.md b/CHANGELOG.md index 90f019acc..2e4a3c5c1 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -13,6 +13,7 @@ Docs: https://docs.openclaw.ai - Daemon/macOS launchd: forward proxy env vars into supervised service environments, keep LaunchAgent `KeepAlive=true` semantics, and harden restart sequencing to `print -> bootout -> wait old pid exit -> bootstrap -> kickstart`. (#27276) thanks @frankekn. - Android/Node invoke: remove native gateway WebSocket `Origin` header to avoid false origin rejections, unify invoke command registry/policy/error parsing paths, and keep command availability checks centralized to reduce dispatcher/advertisement drift. (#27257) Thanks @obviyus. - CI/Windows: shard the Windows `checks-windows` test lane into two matrix jobs and honor explicit shard index overrides in `scripts/test-parallel.mjs` to reduce CI critical-path wall time. (#27234) Thanks @joshavant. +- Agents/Models config: preserve agent-level provider `apiKey` and `baseUrl` during merge-mode `models.json` updates when agent values are present. (#27293) thanks @Sid-Qin. ## 2026.2.25 diff --git a/docs/concepts/models.md b/docs/concepts/models.md index ee8f06ecb..b4317273d 100644 --- a/docs/concepts/models.md +++ b/docs/concepts/models.md @@ -207,3 +207,9 @@ mode, pass `--yes` to accept defaults. Custom providers in `models.providers` are written into `models.json` under the agent directory (default `~/.openclaw/agents//models.json`). This file is merged by default unless `models.mode` is set to `replace`. + +Merge mode precedence for matching provider IDs: + +- Non-empty `apiKey`/`baseUrl` already present in the agent `models.json` win. +- Empty or missing agent `apiKey`/`baseUrl` fall back to config `models.providers`. +- Other provider fields are refreshed from config and normalized catalog data. diff --git a/docs/gateway/configuration-reference.md b/docs/gateway/configuration-reference.md index 8d147b23f..c548fc973 100644 --- a/docs/gateway/configuration-reference.md +++ b/docs/gateway/configuration-reference.md @@ -1741,6 +1741,10 @@ OpenClaw uses the pi-coding-agent model catalog. Add custom providers via `model - Use `authHeader: true` + `headers` for custom auth needs. - Override agent config root with `OPENCLAW_AGENT_DIR` (or `PI_CODING_AGENT_DIR`). +- Merge precedence for matching provider IDs: + - Non-empty agent `models.json` `apiKey`/`baseUrl` win. + - Empty or missing agent `apiKey`/`baseUrl` fall back to `models.providers` in config. + - Use `models.mode: "replace"` when you want config to fully rewrite `models.json`. ### Provider examples diff --git a/src/agents/models-config.fills-missing-provider-apikey-from-env-var.test.ts b/src/agents/models-config.fills-missing-provider-apikey-from-env-var.test.ts index c26142158..4abfa4f1a 100644 --- a/src/agents/models-config.fills-missing-provider-apikey-from-env-var.test.ts +++ b/src/agents/models-config.fills-missing-provider-apikey-from-env-var.test.ts @@ -134,6 +134,116 @@ describe("models-config", () => { }); }); + it("preserves non-empty agent apiKey/baseUrl for matching providers in merge mode", async () => { + await withTempHome(async () => { + const agentDir = resolveOpenClawAgentDir(); + await fs.mkdir(agentDir, { recursive: true }); + await fs.writeFile( + path.join(agentDir, "models.json"), + JSON.stringify( + { + providers: { + custom: { + baseUrl: "https://agent.example/v1", + apiKey: "AGENT_KEY", + api: "openai-responses", + models: [{ id: "agent-model", name: "Agent model", input: ["text"] }], + }, + }, + }, + null, + 2, + ), + "utf8", + ); + + await ensureOpenClawModelsJson({ + models: { + mode: "merge", + providers: { + custom: { + baseUrl: "https://config.example/v1", + apiKey: "CONFIG_KEY", + api: "openai-responses", + models: [ + { + id: "config-model", + name: "Config model", + input: ["text"], + reasoning: false, + cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 }, + contextWindow: 8192, + maxTokens: 2048, + }, + ], + }, + }, + }, + }); + + const parsed = await readGeneratedModelsJson<{ + providers: Record; + }>(); + expect(parsed.providers.custom?.apiKey).toBe("AGENT_KEY"); + expect(parsed.providers.custom?.baseUrl).toBe("https://agent.example/v1"); + }); + }); + + it("uses config apiKey/baseUrl when existing agent values are empty", async () => { + await withTempHome(async () => { + const agentDir = resolveOpenClawAgentDir(); + await fs.mkdir(agentDir, { recursive: true }); + await fs.writeFile( + path.join(agentDir, "models.json"), + JSON.stringify( + { + providers: { + custom: { + baseUrl: "", + apiKey: "", + api: "openai-responses", + models: [{ id: "agent-model", name: "Agent model", input: ["text"] }], + }, + }, + }, + null, + 2, + ), + "utf8", + ); + + await ensureOpenClawModelsJson({ + models: { + mode: "merge", + providers: { + custom: { + baseUrl: "https://config.example/v1", + apiKey: "CONFIG_KEY", + api: "openai-responses", + models: [ + { + id: "config-model", + name: "Config model", + input: ["text"], + reasoning: false, + cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 }, + contextWindow: 8192, + maxTokens: 2048, + }, + ], + }, + }, + }, + }); + + const parsed = await readGeneratedModelsJson<{ + providers: Record; + }>(); + expect(parsed.providers.custom?.apiKey).toBe("CONFIG_KEY"); + expect(parsed.providers.custom?.baseUrl).toBe("https://config.example/v1"); + }); + }); + it("refreshes stale explicit moonshot model capabilities from implicit catalog", async () => { await withTempHome(async () => { const prevKey = process.env.MOONSHOT_API_KEY; diff --git a/src/agents/models-config.ts b/src/agents/models-config.ts index 4b38b8243..3b02737eb 100644 --- a/src/agents/models-config.ts +++ b/src/agents/models-config.ts @@ -142,7 +142,30 @@ export async function ensureOpenClawModelsJson( string, NonNullable[string] >; - mergedProviders = { ...existingProviders, ...providers }; + mergedProviders = {}; + for (const [key, entry] of Object.entries(existingProviders)) { + mergedProviders[key] = entry; + } + for (const [key, newEntry] of Object.entries(providers)) { + const existing = existingProviders[key] as + | (NonNullable[string] & { + apiKey?: string; + baseUrl?: string; + }) + | undefined; + if (existing) { + const preserved: Record = {}; + if (typeof existing.apiKey === "string" && existing.apiKey) { + preserved.apiKey = existing.apiKey; + } + if (typeof existing.baseUrl === "string" && existing.baseUrl) { + preserved.baseUrl = existing.baseUrl; + } + mergedProviders[key] = { ...newEntry, ...preserved }; + } else { + mergedProviders[key] = newEntry; + } + } } } diff --git a/src/config/schema.help.ts b/src/config/schema.help.ts index f32433e13..c16e25df8 100644 --- a/src/config/schema.help.ts +++ b/src/config/schema.help.ts @@ -608,7 +608,7 @@ export const FIELD_HELP: Record = { models: "Model catalog root for provider definitions, merge/replace behavior, and optional Bedrock discovery integration. Keep provider definitions explicit and validated before relying on production failover paths.", "models.mode": - 'Controls provider catalog behavior: "merge" keeps built-ins and overlays your custom providers, while "replace" uses only your configured providers. Keep "merge" unless you intentionally want a strict custom list.', + 'Controls provider catalog behavior: "merge" keeps built-ins and overlays your custom providers, while "replace" uses only your configured providers. In "merge", matching provider IDs preserve non-empty agent models.json apiKey/baseUrl values and fall back to config when agent values are empty or missing.', "models.providers": "Provider map keyed by provider ID containing connection/auth settings and concrete model definitions. Use stable provider keys so references from agents and tooling remain portable across environments.", "models.providers.*.baseUrl":