[Bug]: OpenCode agent fails with "fetch() URL is invalid" when using custom providers with {env:...} placeholders launched from Finder/desktop

[petrarca]

What happened?

When OpenCode is configured with a custom provider that uses {env:VAR_NAME} placeholders in opencode.jsonc (e.g. a custom Azure/Foundry endpoint), launching Open Design from Finder or the desktop app causes the OpenCode agent to fail with:

Could not start OpenCode: fetch() URL is invalid.

The error appears when running the connection test in Settings, and also during actual runs. Models are listed correctly (because opencode models doesn't need the provider URL), but any run with a custom-provider model fails.

Steps to reproduce

1. Configure OpenCode with a custom provider using env var placeholders in ~/.config/opencode/opencode.jsonc:

   "provider": {
     "my-provider": {
       "npm": "@ai-sdk/anthropic",
       "options": {
         "baseURL": "{env:MY_PROVIDER_BASE_URL}",
         "apiKey": "{env:MY_PROVIDER_API_KEY}"
       }
     }
   }

2. Export the required env vars in your shell profile (.zshrc, .zprofile, etc.).
3. Launch Open Design from Finder (or the desktop app icon) — not from the terminal.
4. Go to Settings → select OpenCode as the agent → pick a model from the custom provider → click Test.
5. See: Could not start OpenCode: fetch() URL is invalid.

Expected behavior

The connection test succeeds, or at minimum the error message explains that the required environment variables are not available and directs the user to configure them in Settings.

Root cause

Two compounding issues:

1. macOS Finder launch strips shell env vars.
When the app is launched from Finder, macOS does not source the user's shell profile (.zshrc, .zprofile, etc.). Env vars set there are absent from the daemon's process.env and therefore absent from the spawned OpenCode subprocess.

2. The OpenCode agentCliEnv allowlist only exposes OPENCODE_BIN.
In apps/daemon/src/app-config.ts:206:

['opencode', new Set(['OPENCODE_BIN'])],

Unlike claude (which exposes ANTHROPIC_BASE_URL, ANTHROPIC_API_KEY, etc.) or codex (which exposes OPENAI_BASE_URL, CODEX_API_KEY, etc.), the OpenCode allowlist has no mechanism for users to supply custom provider credentials through the Settings UI. So even if a user knows what's wrong, there is no in-product fix.

When both hit together: OpenCode resolves {env:MY_PROVIDER_BASE_URL} to an empty string, constructs an invalid fetch URL, and surfaces a cryptic error.

Suggested fix

Expand the opencode allowlist in apps/daemon/src/app-config.ts to include env vars that cover common custom provider patterns — at minimum something equivalent to what claude and codex already expose. A reasonable starting set:

['opencode', new Set([
  'OPENCODE_BIN',
  'OPENCODE_FOUNDRY_BASE_URL',   // or a generic OPENCODE_PROVIDER_BASE_URL
  'ANTHROPIC_FOUNDRY_API_KEY',   // or a generic OPENCODE_PROVIDER_API_KEY
  // ... other common custom provider env keys
])],

Alternatively, support a generic pass-through mechanism for arbitrary env vars so users with non-standard provider configs can supply whatever {env:...} keys their opencode.jsonc uses.

A secondary improvement would be a better error message: detect when the fetch URL resolves to empty/invalid and surface a hint like "A required environment variable is missing — check your OpenCode provider configuration or set it via Settings."

Workaround

Hardcode the literal values in ~/.config/opencode/opencode.jsonc instead of using {env:...} placeholders. Note this puts credentials in plaintext in the config file.

Open Design version

Platform

macOS (Apple Silicon)

[open-design-bot]

🎉 ✨ Welcome to Open Design, @petrarca!

✨ 🔥 Lit the spark.

🌱 Your first contribution adds energy to the project. Thanks for showing up and helping Open Design grow.

💛 Thanks for helping Open Design grow. Keep building in the open. 🚀

🔗 Share on X (English) · 分享到 X（中文）

[lefarcen]

Hey @petrarca, thanks for the very careful write-up — the Finder/desktop launch detail plus the {env:...} placeholder path points at a real gap here.

I checked the current daemon/UI path, and the code lines up with the behavior you're describing: apps/daemon/src/app-config.ts still allowlists only OPENCODE_BIN for the opencode agent, while the Settings UI currently exposes CLI env override fields for Claude/Codex custom base URLs and auth keys, but not for OpenCode custom-provider vars. So when Open Design is launched without the shell env you normally export in your profile, there is no in-product path to re-inject those OpenCode provider values, and an env-backed baseURL can plausibly collapse into the invalid URL failure you hit.

So from triage, this looks like a valid bug rather than just a local setup mistake. The likely fix area is the one you identified: extend the OpenCode env bridge (or add a generic pass-through for provider placeholder keys), and pair it with a more actionable connection-test error when a required env-backed URL resolves empty. If you'd like to open a PR for it, happy to review in that direction.