Ambient OPENAI_* env vars silently override config.json provider settings (401 with OpenAI-compatible endpoints)

[StarChen-Cycler]

Environment

• @liustack/modlens 3.16.4, installed as the DeepSeek Harness (dsh) plugin on Windows (dsh plugin --profile web add @liustack/modlens@3.16.4)
• Engine: an OpenAI-compatible endpoint (Moonshot/Kimi, https://api.moonshot.cn/v1) configured in ~/.modlens/config.json

Problem

resolveProviderSettings applies the ENV_BINDINGS after the file values and overrides them unconditionally:

for (const [field, envName] of Object.entries(bindings)) {
  const value = env[envName]?.trim();
  if (value) {
    settings[field] = value;
  }
}

So any ambient OPENAI_API_KEY / OPENAI_BASE_URL in the process environment silently replaces the engine explicitly configured in config.json. This is easy to hit on Windows (user-level env vars set for other OpenAI-compatible tools) and under the dsh plugin in particular, because the plugin spawns the CLI with the full host process environment.

Result: a key meant for one endpoint is sent to the configured endpoint, and every read fails with:

openai: OpenAI-compatible API error 401: {"error":{"message":"Invalid Authentication","type":"invalid_authentication_error"}}

There is no opt-out, and the error gives no hint that the key came from the environment rather than the config file. (Same failure class as the ANTHROPIC_BASE_URL trap already documented in configure.md.)

Repro (verified)

1. Configure providers.openai in ~/.modlens/config.json with a working key for an OpenAI-compatible endpoint (e.g. Kimi).
2. Set an unrelated OPENAI_API_KEY in the process environment.
3. Run a read → 401 (wrong key sent to the configured endpoint). Unset the env var → the same config succeeds. Reproduced deterministically in both directions.

Proposed fix (verified locally)

Let an explicitly configured file value win; env only fills gaps:

for (const [field, envName] of Object.entries(bindings)) {
  const value = env[envName]?.trim();
  if (value && !settings[field]?.trim()) {
    settings[field] = value;
  }
}

Alternative/additional: an opt-out such as providers.openai.ignoreEnv: true for users who want the file to be the single source of truth.

As a second line of defense on the dsh side I also patched the plugin's spawn to not forward ambient credential env vars (OPENAI_*, GEMINI_API_KEY, ANTHROPIC_*) to the CLI, so config.json stays authoritative for dsh users regardless.

Test results (after the dist/main.js patch)

• CLI reads: 4/4 success against the configured endpoint (previously failed with 401 whenever the ambient var was present).
• dsh plugin tool path (modlens_read_image): success.
• doctor continues to report the config file as the effective source.

[liustack]

Fixed in 3.17.0, and thank you: this arrived with the mechanism, a deterministic repro in both directions, and a patch. That is what made it possible to argue about the shape of the fix rather than about whether the bug was real.

The change is not the one you proposed, and the reason is worth writing down, because your proposal does not close your own report.

A provider now takes its settings from one place, whole. Name a provider in the config file and the file is its source. Say nothing about it and the environment is. Nothing merges across the boundary.

Your suggestion was that the environment should only fill gaps the file leaves. Run your own repro against that rule: the file holds the Kimi baseUrl, the file holds no apiKey, the ambient OPENAI_API_KEY fills the gap. That is the same mismatched pair, and the same 401. Reversing the precedence keeps the shape too. The defect was never which side wins a field. A baseUrl and an apiKey are one credential, and drawing halves from two sources builds a pairing that exists in neither place, with nothing in the error naming the environment as the source.

So the boundary moved up a level, from the field to the provider.

What this costs you. If your file configures a provider and you were completing it from the environment, the rest belongs in the file now:

modlens config set <provider>.apiKey                          # prompts, hidden, never touches argv or shell history
modlens config set <provider>.baseUrl "$THE_VARIABLE"         # $env:THE_VARIABLE in PowerShell

Until you do, a run that names such a provider refuses and prints that exact command, rather than quietly falling back to the vendor's own endpoint. modlens doctor and modlens config show label every provider with the source actually in effect, so the answer to "where is this key coming from" is one command away.

What this does not cost. A container or CI job that only exports variables works exactly as before. Both halves still come from the same place, so they still match. That case was never broken, and an earlier draft of this fix that removed the variables outright would have broken it, which is why that draft did not ship.

One detail worth knowing if you ever edit the file by hand: naming a provider is about the key existing, not what is under it. An entry emptied down to {} still takes that provider off its variables. Clearing the last field is how an entry ends up empty in ordinary use, and a file you edited quietly handing the provider back to the environment is the surprise this whole issue is about.

This also defuses the ANTHROPIC_BASE_URL trap that was documented as a known hazard, where a shell that routed Claude Code through a text-only gateway sent vision requests there too.

MODLENS_MODEL, MODLENS_HARNESS and the HTTPS_PROXY family are untouched. None is a credential, and none can be split from a matching half.

On the patch: we do not take pull requests on this repo, so nothing was merged from it, but it was read closely and it shortened the diagnosis considerably. Thanks again.