feat(opencode-local): env-driven gateway routing (custom providers, small/cheap model, remote allow-all) (#7837)

## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work > - The `opencode-local` adapter runs the OpenCode harness; its model/provider routing assumes built-in providers (anthropic/openai/...) and their default models > - Deployments increasingly put an OpenAI/Anthropic-compatible LLM gateway between the harness and the model for cost, governance, or data-residency reasons: LiteLLM, OpenRouter, Portkey, Kong, a corporate proxy, self-hosted models (vLLM/Ollama), or region-pinned/sovereign endpoints. But OpenCode only resolves `--model provider/model` when the model is registered in a provider's `models` map, and `OPENCODE_ALLOW_ALL_MODELS` does NOT bypass its internal `getModel()` > - Several lanes also fall back to built-in default models the gateway may not serve: the auxiliary/title model (e.g. `claude-haiku-*`) and the budget/recovery "cheap" lane (`openai/gpt-5.1-codex-mini`); these abort runs with "no keys found that support model" > - This pull request makes the adapter's provider/model wiring declarative via env, so any such deployment can register gateway models + pin the auxiliary/budget lanes without code changes; nothing here is specific to one hosting setup > - The benefit is OpenCode works behind any compatible gateway with config only; with no env set, behavior is unchanged ## Linked Issues or Issue Description No existing issue; describing in-PR (feature / adapter enhancement). - **Gap:** there is no supported way to register custom/gateway providers + models for `opencode-local`, nor to pin the auxiliary (title-gen) and budget (recovery) model lanes, so routing OpenCode through a gateway fails at `getModel()` or on the default helper models. - Related: #5737 (exe.dev sandbox installs for gemini/opencode local), #5823 (unblock claude_local on remote sandbox providers). > Note on ROADMAP: this is adapter-level, opt-in config (defaults unchanged) that *enables* gateway routing for one harness; it is not the core "Cloud / Sandbox agents" platform work itself. Happy to redirect/discuss in #dev if preferred. ## What Changed - `PAPERCLIP_OPENCODE_PROVIDERS`: merge custom/extended providers (OpenCode `provider` shape) into the runtime `opencode.json`, so gateway models are registered and `--model provider/model` resolves. `{env:VAR}` placeholders are expanded server-side (so a key need not depend on the sandbox run env). - A malformed `PAPERCLIP_OPENCODE_PROVIDERS` is no longer silently ignored: invalid JSON, a non-object value, and individual provider entries with non-object values (which are skipped by name) each append a visible note to the run notes so the misconfiguration is diagnosable (addresses both review P1s). - `PAPERCLIP_OPENCODE_SMALL_MODEL` / `PAPERCLIP_OPENCODE_CHEAP_MODEL`: pin the auxiliary (title-generation) and budget (recovery-retry) lanes to gateway-served models; defaults unchanged. - Honour `OPENCODE_ALLOW_ALL_MODELS` on the **remote** execution path too (was local-only, a parity gap). - `PAPERCLIP_OPENCODE_PRINT_LOGS`: optional toggle adding `--print-logs` so OpenCode logs surface on stderr for diagnosing remote/sandbox runs. - `buildOpenCodeModelProfiles()` guards its `process.env` default with `typeof process` so the shared client/server module stays browser-safe (a bare `process.env` at module load threw ReferenceError in the browser under Vite dev middleware and broke UI rendering in the e2e lane). ## Verification - `pnpm --filter @paperclipai/adapter-opencode-local build` and `typecheck` (tsc clean) - `pnpm exec vitest run packages/adapters/opencode-local/src` shows 33 passing (incl. new tests for the provider merge, `{env:}` expansion, the malformed/non-object/skipped-entry provider notes, small/cheap-model resolution, and the remote allow-all bypass) - Manually verified end-to-end against a real OpenAI-/Anthropic-compatible gateway: with the providers + small/cheap model set, both the title-gen and main task route to the configured gateway model and the agent completes (a real completion is returned and billed). That deployment supplies the verification evidence; the mechanism is gateway-agnostic. ## Risks Low. Everything is env-driven and opt-in; with no env set the generated config output is unchanged, and the cheap model profile keeps its model (the only difference is its updated human-readable description). Defaults preserved: built-in providers, Codex-mini cheap lane with `variant: low`, no `--print-logs`. No migration/UI impact. ## Model Used Claude Opus 4.8 (`claude-opus-4-8`, 1M context), extended thinking + tool use, via Claude Code. ## Checklist - [x] I have included a thinking path that traces from project context to this change - [x] I have specified the model used (with version and capability details) - [x] I have checked ROADMAP.md (adapter-level opt-in config enabling gateway routing; not the core sandbox-platform work, noted above) - [x] I have searched GitHub for duplicate or related PRs and linked them above (#5737, #5823) - [x] I have either (a) linked existing issues OR (b) described the issue in-PR following the relevant issue template - [x] I have run tests locally and they pass - [x] I have added or updated tests where applicable - [ ] If this change affects the UI, I have included before/after screenshots (n/a, no UI) - [ ] I have updated relevant documentation to reflect my changes (env vars documented inline via comments; no central doc references the adapter env yet) - [x] I have considered and documented any risks above - [x] All Paperclip CI gates are green - [x] Greptile is 5/5 with no open P2s, recommendations, or follow-ups (the P1 about silently dropped malformed providers JSON is addressed in 6eeb803, the follow-up P1 about silently skipped non-object entries in 2f4045a; the latest review has no further findings, and a re-review is requested for the final note-copy/test-fixture polish at head) - [x] I will address all Greptile and reviewer comments before requesting merge 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-06-11 06:11:49 +02:00
parent 398d746093
commit 1ac1ba5442
8 changed files with 482 additions and 16 deletions
@@ -0,0 +1,28 @@
+import { describe, expect, it } from "vitest";
+import { buildOpenCodeModelProfiles, DEFAULT_OPENCODE_CHEAP_MODEL } from "./index.js";
+
+describe("buildOpenCodeModelProfiles cheap lane", () => {
+  it("defaults to the upstream Codex mini model with variant low", () => {
+    const [cheap] = buildOpenCodeModelProfiles({});
+    expect(cheap.key).toBe("cheap");
+    expect(cheap.adapterConfig).toEqual({ model: DEFAULT_OPENCODE_CHEAP_MODEL, variant: "low" });
+  });
+
+  it("uses PAPERCLIP_OPENCODE_CHEAP_MODEL when set (no variant, gateway models may not support it)", () => {
+    const [cheap] = buildOpenCodeModelProfiles({ PAPERCLIP_OPENCODE_CHEAP_MODEL: "anthropic/gw/m" });
+    expect(cheap.adapterConfig).toEqual({ model: "anthropic/gw/m" });
+  });
+
+  it("falls back to PAPERCLIP_OPENCODE_SMALL_MODEL so one setting covers both budget lanes", () => {
+    const [cheap] = buildOpenCodeModelProfiles({ PAPERCLIP_OPENCODE_SMALL_MODEL: "anthropic/gw/small" });
+    expect(cheap.adapterConfig).toEqual({ model: "anthropic/gw/small" });
+  });
+
+  it("prefers CHEAP_MODEL over SMALL_MODEL when both are set", () => {
+    const [cheap] = buildOpenCodeModelProfiles({
+      PAPERCLIP_OPENCODE_CHEAP_MODEL: "anthropic/gw/cheap",
+      PAPERCLIP_OPENCODE_SMALL_MODEL: "anthropic/gw/small",
+    });
+    expect(cheap.adapterConfig).toEqual({ model: "anthropic/gw/cheap" });
+  });
+});
@@ -61,18 +61,40 @@ export const models: Array<{ id: string; label: string }> = [
  { id: "openai/gpt-5.1-codex-mini", label: "openai/gpt-5.1-codex-mini" },
 ];

-export const modelProfiles: AdapterModelProfileDefinition[] = [
-  {
-    key: "cheap",
-    label: "Cheap",
-    description: "Use OpenCode's known Codex mini model as the budget lane.",
-    adapterConfig: {
-      model: "openai/gpt-5.1-codex-mini",
-      variant: "low",
+export const DEFAULT_OPENCODE_CHEAP_MODEL = "openai/gpt-5.1-codex-mini";
+
+// The "cheap" budget profile (used for recovery retries and other low-cost lanes).
+// Defaults to OpenCode's known Codex mini model, but is overridable so a deployment
+// routing through a gateway that does not serve that model (e.g. an EU LLM gateway)
+// can point the budget lane at a gateway-served model instead -- otherwise recovery
+// retries fail with "model not found". PAPERCLIP_OPENCODE_CHEAP_MODEL takes priority;
+// PAPERCLIP_OPENCODE_SMALL_MODEL (the auxiliary/title model) is reused as a sensible
+// fallback so a single setting covers both budget lanes. The default keeps the
+// upstream behaviour (with the Codex `variant: "low"`).
+//
+// This module is shared client/server code (the UI imports it for
+// DEFAULT_OPENCODE_LOCAL_MODEL etc.), so it must not touch the global `process`
+// unguarded: in the browser (Vite dev middleware serves it untransformed)
+// a bare `process.env` throws ReferenceError at module load and takes the whole
+// app down. Guard with `typeof process` and fall back to an empty env.
+export function buildOpenCodeModelProfiles(
+  env: NodeJS.ProcessEnv = typeof process === "undefined" ? {} : process.env,
+): AdapterModelProfileDefinition[] {
+  const override = (env.PAPERCLIP_OPENCODE_CHEAP_MODEL ?? env.PAPERCLIP_OPENCODE_SMALL_MODEL)?.trim();
+  return [
+    {
+      key: "cheap",
+      label: "Cheap",
+      description: "Budget lane model for recovery retries and other low-cost tasks.",
+      adapterConfig: override
+        ? { model: override }
+        : { model: DEFAULT_OPENCODE_CHEAP_MODEL, variant: "low" },
+      source: "adapter_default",
    },
-    source: "adapter_default",
-  },
-];
+  ];
+}
+
+export const modelProfiles: AdapterModelProfileDefinition[] = buildOpenCodeModelProfiles();

 export const agentConfigurationDoc = `# opencode_local agent configuration

@@ -0,0 +1,62 @@
+import { afterEach, describe, expect, it } from "vitest";
+
+import { ensureRemoteOpenCodeModelConfiguredAndAvailable } from "./execute.js";
+
+describe("ensureRemoteOpenCodeModelConfiguredAndAvailable", () => {
+  afterEach(() => {
+    delete process.env.OPENCODE_ALLOW_ALL_MODELS;
+  });
+
+  // The remote/sandbox execution path must honour OPENCODE_ALLOW_ALL_MODELS just
+  // like the local path: gateway-routed models (e.g. anthropic/<gateway>/<model>
+  // via Bifrost) never appear in `opencode models`, so the availability probe
+  // must be skipped. The early return happens before the executionTarget is ever
+  // touched, so a bogus target proves the probe was not run.
+  const bogusTarget = {} as never;
+
+  it("skips the remote availability probe when OPENCODE_ALLOW_ALL_MODELS is set in the run env", async () => {
+    await expect(
+      ensureRemoteOpenCodeModelConfiguredAndAvailable({
+        runId: "run-1",
+        executionTarget: bogusTarget,
+        command: "opencode",
+        model: "anthropic/tensorix/deepseek/deepseek-chat-v3.1",
+        cwd: "/tmp",
+        env: { OPENCODE_ALLOW_ALL_MODELS: "true" },
+        timeoutSec: 30,
+        graceSec: 5,
+      }),
+    ).resolves.toBeUndefined();
+  });
+
+  it("honours OPENCODE_ALLOW_ALL_MODELS from the process env", async () => {
+    process.env.OPENCODE_ALLOW_ALL_MODELS = "1";
+    await expect(
+      ensureRemoteOpenCodeModelConfiguredAndAvailable({
+        runId: "run-2",
+        executionTarget: bogusTarget,
+        command: "opencode",
+        model: "anthropic/tensorix/deepseek/deepseek-chat-v3.1",
+        cwd: "/tmp",
+        env: {},
+        timeoutSec: 30,
+        graceSec: 5,
+      }),
+    ).resolves.toBeUndefined();
+  });
+
+  it("still enforces provider/model format even when the bypass flag is set", async () => {
+    await expect(
+      ensureRemoteOpenCodeModelConfiguredAndAvailable({
+        runId: "run-3",
+        executionTarget: bogusTarget,
+        command: "opencode",
+        model: "",
+        cwd: "/tmp",
+        env: { OPENCODE_ALLOW_ALL_MODELS: "true" },
+        timeoutSec: 30,
+        graceSec: 5,
+      }),
+    ).rejects.toThrow();
+  });
+});
@@ -47,6 +47,7 @@ import {
 import { isOpenCodeUnknownSessionError, parseOpenCodeJsonl } from "./parse.js";
 import {
  ensureOpenCodeModelConfiguredAndAvailable,
+  isTruthyEnvFlag,
  parseOpenCodeModelsOutput,
  requireOpenCodeModelId,
 } from "./models.js";
@@ -79,7 +80,7 @@ function resolveOpenCodeBiller(env: Record<string, string>, provider: string | n
 const REMOTE_OPENCODE_MODELS_PROBE_DEFAULT_TIMEOUT_SEC = 20;
 const REMOTE_OPENCODE_MODELS_PROBE_SANDBOX_TIMEOUT_SEC = 120;

-async function ensureRemoteOpenCodeModelConfiguredAndAvailable(input: {
+export async function ensureRemoteOpenCodeModelConfiguredAndAvailable(input: {
  runId: string;
  executionTarget: NonNullable<AdapterExecutionContext["executionTarget"]>;
  command: string;
@@ -90,6 +91,17 @@ async function ensureRemoteOpenCodeModelConfiguredAndAvailable(input: {
  graceSec: number;
 }) {
  const model = requireOpenCodeModelId(input.model);
+
+  // When the caller opts into OPENCODE_ALLOW_ALL_MODELS, OpenCode accepts any
+  // provider/model at run time (e.g. gateway-routed models that never appear in
+  // `opencode models` output). Honour that on the REMOTE path too by skipping the
+  // remote availability probe; we still enforce the provider/model format above.
+  // Mirrors the local ensureOpenCodeModelConfiguredAndAvailable bypass. Prefer the
+  // explicit run env, then the process env.
+  if (isTruthyEnvFlag(input.env.OPENCODE_ALLOW_ALL_MODELS ?? process.env.OPENCODE_ALLOW_ALL_MODELS)) {
+    return;
+  }
+
  const defaultProbeTimeoutSec =
    input.executionTarget.kind === "remote" && input.executionTarget.transport === "sandbox"
      ? REMOTE_OPENCODE_MODELS_PROBE_SANDBOX_TIMEOUT_SEC
@@ -548,8 +560,17 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExec
      heartbeatPromptChars: renderedPrompt.length,
    };

+    // Optional diagnostic: surface OpenCode's own logs on stderr (captured into the
+    // run result) so failures that OpenCode otherwise wraps as an opaque
+    // "Unexpected server error" can be diagnosed in remote/sandbox runs where the
+    // log file is unreachable. Toggle via PAPERCLIP_OPENCODE_PRINT_LOGS (run env,
+    // then process env).
+    const printLogs = isTruthyEnvFlag(
+      env.PAPERCLIP_OPENCODE_PRINT_LOGS ?? process.env.PAPERCLIP_OPENCODE_PRINT_LOGS,
+    );
    const buildArgs = (resumeSessionId: string | null) => {
      const args = ["run", "--format", "json"];
+      if (printLogs) args.push("--print-logs");
      if (resumeSessionId) args.push("--session", resumeSessionId);
      if (model) args.push("--model", model);
      if (variant) args.push("--variant", variant);
@@ -9,6 +9,7 @@ import {
 describe("openCode models", () => {
  afterEach(() => {
    delete process.env.PAPERCLIP_OPENCODE_COMMAND;
+    delete process.env.OPENCODE_ALLOW_ALL_MODELS;
    resetOpenCodeModelsCacheForTests();
  });

@@ -44,4 +45,33 @@ describe("openCode models", () => {
      }),
    ).rejects.toThrow("Failed to start command");
  });
+
+  it("skips the availability check when OPENCODE_ALLOW_ALL_MODELS is set in the run env", async () => {
+    process.env.PAPERCLIP_OPENCODE_COMMAND = "__paperclip_missing_opencode_command__";
+    await expect(
+      ensureOpenCodeModelConfiguredAndAvailable({
+        model: "anthropic/tensorix/deepseek/deepseek-chat-v3.1",
+        env: { OPENCODE_ALLOW_ALL_MODELS: "true" },
+      }),
+    ).resolves.toEqual([
+      { id: "anthropic/tensorix/deepseek/deepseek-chat-v3.1", label: "anthropic/tensorix/deepseek/deepseek-chat-v3.1" },
+    ]);
+  });
+
+  it("honours OPENCODE_ALLOW_ALL_MODELS from the process env", async () => {
+    process.env.PAPERCLIP_OPENCODE_COMMAND = "__paperclip_missing_opencode_command__";
+    process.env.OPENCODE_ALLOW_ALL_MODELS = "1";
+    await expect(
+      ensureOpenCodeModelConfiguredAndAvailable({ model: "anthropic/gateway/some-model" }),
+    ).resolves.toEqual([{ id: "anthropic/gateway/some-model", label: "anthropic/gateway/some-model" }]);
+  });
+
+  it("still enforces provider/model format when OPENCODE_ALLOW_ALL_MODELS is set", async () => {
+    await expect(
+      ensureOpenCodeModelConfiguredAndAvailable({
+        model: "not-a-valid-id",
+        env: { OPENCODE_ALLOW_ALL_MODELS: "true" },
+      }),
+    ).rejects.toThrow("OpenCode requires `adapterConfig.model`");
+  });
 });
@@ -175,6 +175,12 @@ export async function discoverOpenCodeModelsCached(input: {
  return models;
 }

+export function isTruthyEnvFlag(value: string | undefined): boolean {
+  if (value === undefined) return false;
+  const v = value.trim().toLowerCase();
+  return v === "true" || v === "1" || v === "yes";
+}
+
 export async function ensureOpenCodeModelConfiguredAndAvailable(input: {
  model?: unknown;
  command?: unknown;
@@ -183,6 +189,16 @@ export async function ensureOpenCodeModelConfiguredAndAvailable(input: {
 }): Promise<AdapterModel[]> {
  const model = requireOpenCodeModelId(input.model);

+  // When the caller opts into OPENCODE_ALLOW_ALL_MODELS, OpenCode accepts any
+  // provider/model at run time (e.g. gateway-routed models that never appear in
+  // `opencode models` output). Honour that by skipping the availability probe;
+  // we still enforce the provider/model format above and do not second-guess
+  // the configured model. Prefer the explicit run env, then the process env.
+  const env = normalizeEnv(input.env);
+  if (isTruthyEnvFlag(env.OPENCODE_ALLOW_ALL_MODELS ?? process.env.OPENCODE_ALLOW_ALL_MODELS)) {
+    return [{ id: model, label: model }];
+  }
+
  const models = await discoverOpenCodeModelsCached({
    command: input.command,
    cwd: input.cwd,
@@ -65,6 +65,190 @@ describe("prepareOpenCodeRuntimeConfig", () => {
    await expect(fs.access(prepared.env.XDG_CONFIG_HOME)).rejects.toThrow();
  });

+  it("merges custom providers from PAPERCLIP_OPENCODE_PROVIDERS into the config", async () => {
+    const configHome = await makeConfigHome({ permission: { read: "allow" } });
+    const providers = {
+      bifrost: {
+        npm: "@ai-sdk/openai-compatible",
+        name: "Bifrost EU",
+        options: {
+          baseURL: "http://gateway.example.svc.cluster.local:8080/v1",
+          apiKey: "{env:ANTHROPIC_API_KEY}",
+        },
+        models: { "example/model-a": { name: "Model A" } },
+      },
+    };
+
+    const prepared = await prepareOpenCodeRuntimeConfig({
+      env: {
+        XDG_CONFIG_HOME: configHome,
+        PAPERCLIP_OPENCODE_PROVIDERS: JSON.stringify(providers),
+      },
+      config: {},
+    });
+    cleanupPaths.add(prepared.env.XDG_CONFIG_HOME);
+
+    const runtimeConfig = JSON.parse(
+      await fs.readFile(path.join(prepared.env.XDG_CONFIG_HOME, "opencode", "opencode.json"), "utf8"),
+    ) as Record<string, unknown>;
+    expect(runtimeConfig).toMatchObject({
+      permission: { read: "allow", external_directory: "allow" },
+      provider: providers,
+    });
+    expect(prepared.notes.some((n) => n.includes("bifrost"))).toBe(true);
+    await prepared.cleanup();
+  });
+
+  it("reads PAPERCLIP_OPENCODE_PROVIDERS from process.env when absent from the run env", async () => {
+    const configHome = await makeConfigHome({ permission: { read: "allow" } });
+    const providers = { bifrost: { npm: "@ai-sdk/openai-compatible", models: { "example/model-a": {} } } };
+    process.env.PAPERCLIP_OPENCODE_PROVIDERS = JSON.stringify(providers);
+    try {
+      const prepared = await prepareOpenCodeRuntimeConfig({
+        env: { XDG_CONFIG_HOME: configHome },
+        config: {},
+      });
+      cleanupPaths.add(prepared.env.XDG_CONFIG_HOME);
+      const runtimeConfig = JSON.parse(
+        await fs.readFile(path.join(prepared.env.XDG_CONFIG_HOME, "opencode", "opencode.json"), "utf8"),
+      ) as Record<string, unknown>;
+      expect(runtimeConfig).toMatchObject({ provider: providers });
+      await prepared.cleanup();
+    } finally {
+      delete process.env.PAPERCLIP_OPENCODE_PROVIDERS;
+    }
+  });
+
+  it("expands {env:VAR} placeholders in custom providers using the run/process env (bakes the literal vk)", async () => {
+    const configHome = await makeConfigHome({ permission: { read: "allow" } });
+    const providers = {
+      bifrost: {
+        npm: "@ai-sdk/openai-compatible",
+        options: { baseURL: "http://bifrost/v1", apiKey: "{env:ANTHROPIC_API_KEY}" },
+        models: { "example/model-a": {} },
+      },
+    };
+    const prepared = await prepareOpenCodeRuntimeConfig({
+      env: { XDG_CONFIG_HOME: configHome, PAPERCLIP_OPENCODE_PROVIDERS: JSON.stringify(providers), ANTHROPIC_API_KEY: "sk-bf-REALVK" },
+      config: {},
+    });
+    cleanupPaths.add(prepared.env.XDG_CONFIG_HOME);
+    const runtimeConfig = JSON.parse(
+      await fs.readFile(path.join(prepared.env.XDG_CONFIG_HOME, "opencode", "opencode.json"), "utf8"),
+    ) as { provider: { bifrost: { options: { apiKey: string } } } };
+    // The {env:...} placeholder must be replaced with the literal value, so OpenCode
+    // does not depend on its sandboxed process env carrying the key.
+    expect(runtimeConfig.provider.bifrost.options.apiKey).toBe("sk-bf-REALVK");
+    await prepared.cleanup();
+  });
+
+  it("leaves an unresolvable {env:VAR} placeholder intact", async () => {
+    const configHome = await makeConfigHome({ permission: { read: "allow" } });
+    const providers = { bifrost: { options: { apiKey: "{env:DEFINITELY_UNSET_VAR_XYZ}" }, models: { "x/y": {} } } };
+    const prepared = await prepareOpenCodeRuntimeConfig({
+      env: { XDG_CONFIG_HOME: configHome, PAPERCLIP_OPENCODE_PROVIDERS: JSON.stringify(providers) },
+      config: {},
+    });
+    cleanupPaths.add(prepared.env.XDG_CONFIG_HOME);
+    const runtimeConfig = JSON.parse(
+      await fs.readFile(path.join(prepared.env.XDG_CONFIG_HOME, "opencode", "opencode.json"), "utf8"),
+    ) as { provider: { bifrost: { options: { apiKey: string } } } };
+    expect(runtimeConfig.provider.bifrost.options.apiKey).toBe("{env:DEFINITELY_UNSET_VAR_XYZ}");
+    await prepared.cleanup();
+  });
+
+  it("pins small_model from PAPERCLIP_OPENCODE_SMALL_MODEL", async () => {
+    const configHome = await makeConfigHome({ permission: { read: "allow" } });
+    const prepared = await prepareOpenCodeRuntimeConfig({
+      env: { XDG_CONFIG_HOME: configHome, PAPERCLIP_OPENCODE_SMALL_MODEL: "example/model-a" },
+      config: {},
+    });
+    cleanupPaths.add(prepared.env.XDG_CONFIG_HOME);
+    const runtimeConfig = JSON.parse(
+      await fs.readFile(path.join(prepared.env.XDG_CONFIG_HOME, "opencode", "opencode.json"), "utf8"),
+    ) as { small_model?: string };
+    expect(runtimeConfig.small_model).toBe("example/model-a");
+    await prepared.cleanup();
+  });
+
+  it("ignores malformed PAPERCLIP_OPENCODE_PROVIDERS without writing a provider block and surfaces a note", async () => {
+    const configHome = await makeConfigHome({ permission: { read: "allow" } });
+    const prepared = await prepareOpenCodeRuntimeConfig({
+      env: { XDG_CONFIG_HOME: configHome, PAPERCLIP_OPENCODE_PROVIDERS: "not json" },
+      config: {},
+    });
+    cleanupPaths.add(prepared.env.XDG_CONFIG_HOME);
+    const runtimeConfig = JSON.parse(
+      await fs.readFile(path.join(prepared.env.XDG_CONFIG_HOME, "opencode", "opencode.json"), "utf8"),
+    ) as Record<string, unknown>;
+    expect(runtimeConfig.provider).toBeUndefined();
+    expect(prepared.notes).toContain(
+      "PAPERCLIP_OPENCODE_PROVIDERS contains invalid JSON; custom providers ignored.",
+    );
+    await prepared.cleanup();
+  });
+
+  it("surfaces a note when PAPERCLIP_OPENCODE_PROVIDERS is valid JSON but not an object", async () => {
+    const configHome = await makeConfigHome({ permission: { read: "allow" } });
+    const prepared = await prepareOpenCodeRuntimeConfig({
+      env: { XDG_CONFIG_HOME: configHome, PAPERCLIP_OPENCODE_PROVIDERS: "[1,2,3]" },
+      config: {},
+    });
+    cleanupPaths.add(prepared.env.XDG_CONFIG_HOME);
+    const runtimeConfig = JSON.parse(
+      await fs.readFile(path.join(prepared.env.XDG_CONFIG_HOME, "opencode", "opencode.json"), "utf8"),
+    ) as Record<string, unknown>;
+    expect(runtimeConfig.provider).toBeUndefined();
+    expect(prepared.notes).toContain(
+      "PAPERCLIP_OPENCODE_PROVIDERS is set but is not a JSON object; custom providers ignored.",
+    );
+    await prepared.cleanup();
+  });
+
+  it("surfaces skipped provider entries with non-object values and keeps the usable ones", async () => {
+    const configHome = await makeConfigHome({ permission: { read: "allow" } });
+    const prepared = await prepareOpenCodeRuntimeConfig({
+      env: {
+        XDG_CONFIG_HOME: configHome,
+        PAPERCLIP_OPENCODE_PROVIDERS: JSON.stringify({
+          bifrost: "http://gateway.example/v1",
+          usable: { options: { baseURL: "http://gateway.example/v1" } },
+        }),
+      },
+      config: {},
+    });
+    cleanupPaths.add(prepared.env.XDG_CONFIG_HOME);
+    const runtimeConfig = JSON.parse(
+      await fs.readFile(path.join(prepared.env.XDG_CONFIG_HOME, "opencode", "opencode.json"), "utf8"),
+    ) as { provider?: Record<string, unknown> };
+    expect(runtimeConfig.provider?.usable).toBeDefined();
+    expect(runtimeConfig.provider?.bifrost).toBeUndefined();
+    expect(prepared.notes).toContain(
+      "PAPERCLIP_OPENCODE_PROVIDERS: skipped provider(s) with non-object values: bifrost.",
+    );
+    await prepared.cleanup();
+  });
+
+  it("surfaces skipped provider entries when no usable entries remain", async () => {
+    const configHome = await makeConfigHome({ permission: { read: "allow" } });
+    const prepared = await prepareOpenCodeRuntimeConfig({
+      env: {
+        XDG_CONFIG_HOME: configHome,
+        PAPERCLIP_OPENCODE_PROVIDERS: JSON.stringify({ bifrost: "http://gateway.example/v1" }),
+      },
+      config: {},
+    });
+    cleanupPaths.add(prepared.env.XDG_CONFIG_HOME);
+    const runtimeConfig = JSON.parse(
+      await fs.readFile(path.join(prepared.env.XDG_CONFIG_HOME, "opencode", "opencode.json"), "utf8"),
+    ) as Record<string, unknown>;
+    expect(runtimeConfig.provider).toBeUndefined();
+    expect(prepared.notes).toContain(
+      "PAPERCLIP_OPENCODE_PROVIDERS: skipped provider(s) with non-object values: bifrost.",
+    );
+    await prepared.cleanup();
+  });
+
  it("respects explicit opt-out", async () => {
    const configHome = await makeConfigHome();
    const prepared = await prepareOpenCodeRuntimeConfig({
@@ -21,6 +21,69 @@ function isPlainObject(value: unknown): value is Record<string, unknown> {
  return typeof value === "object" && value !== null && !Array.isArray(value);
 }

+// Recursively replace {env:VAR} placeholders with the resolved value. Used to bake
+// gateway provider secrets (e.g. the LLM-gateway virtual key) into opencode.json
+// SERVER-SIDE, where the value is reliably present. OpenCode's own {env:...}
+// resolution happens inside the (possibly sandboxed) run process, whose env
+// plumbing is not guaranteed to carry the key to OpenCode's spawned server -- so
+// we resolve it here. Unresolvable placeholders are left intact for OpenCode to try.
+function expandEnvPlaceholders<T>(value: T, resolve: (name: string) => string | undefined): T {
+  if (typeof value === "string") {
+    return value.replace(/\{env:([A-Za-z_][A-Za-z0-9_]*)\}/g, (match, name: string) => {
+      const resolved = resolve(name);
+      return resolved !== undefined && resolved.length > 0 ? resolved : match;
+    }) as unknown as T;
+  }
+  if (Array.isArray(value)) {
+    return value.map((entry) => expandEnvPlaceholders(entry, resolve)) as unknown as T;
+  }
+  if (isPlainObject(value)) {
+    const out: Record<string, unknown> = {};
+    for (const [key, entry] of Object.entries(value)) {
+      out[key] = expandEnvPlaceholders(entry, resolve);
+    }
+    return out as unknown as T;
+  }
+  return value;
+}
+
+function parseProviderConfig(
+  raw: unknown,
+  resolveEnv: (name: string) => string | undefined,
+  notes: string[],
+): Record<string, unknown> | null {
+  if (typeof raw !== "string" || raw.trim().length === 0) return null;
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    // Surface the misconfiguration instead of silently dropping the provider
+    // block; an unparseable value would otherwise be undiagnosable.
+    notes.push("PAPERCLIP_OPENCODE_PROVIDERS contains invalid JSON; custom providers ignored.");
+    return null;
+  }
+  if (!isPlainObject(parsed)) {
+    notes.push(
+      "PAPERCLIP_OPENCODE_PROVIDERS is set but is not a JSON object; custom providers ignored.",
+    );
+    return null;
+  }
+  // Only keep provider entries that are themselves objects; surface the ones
+  // we drop so a malformed entry is just as diagnosable as malformed JSON.
+  const providers: Record<string, unknown> = {};
+  const skipped: string[] = [];
+  for (const [key, value] of Object.entries(parsed)) {
+    if (isPlainObject(value)) providers[key] = expandEnvPlaceholders(value, resolveEnv);
+    else skipped.push(key);
+  }
+  if (skipped.length > 0) {
+    notes.push(
+      `PAPERCLIP_OPENCODE_PROVIDERS: skipped provider(s) with non-object values: ${skipped.join(", ")}.`,
+    );
+  }
+  return Object.keys(providers).length > 0 ? providers : null;
+}
+
 async function readJsonObject(filepath: string): Promise<Record<string, unknown>> {
  try {
    const raw = await fs.readFile(filepath, "utf8");
@@ -81,13 +144,55 @@ export async function prepareOpenCodeRuntimeConfig(input: {
  const existingPermission = isPlainObject(existingConfig.permission)
    ? existingConfig.permission
    : {};
-  const nextConfig = {
+  const notes = [
+    "Injected runtime OpenCode config with permission.external_directory=allow to avoid headless approval prompts.",
+  ];
+
+  // Merge gateway/custom provider definitions supplied via PAPERCLIP_OPENCODE_PROVIDERS
+  // (a JSON object in OpenCode's `provider` shape). OpenCode resolves a `--model
+  // provider/model` only when that model exists in a provider's `models` map, and
+  // OPENCODE_ALLOW_ALL_MODELS does NOT bypass its internal getModel(). So routing a
+  // gateway model (e.g. an EU LLM gateway exposing OpenAI-compatible /v1) requires a
+  // custom provider with an explicit models map. We accept it as config (not
+  // hard-coded) so the gateway URL, key env, and model list stay declarative.
+  const resolveEnv = (name: string): string | undefined => input.env[name] ?? process.env[name];
+  const gatewayProviders = parseProviderConfig(
+    input.env.PAPERCLIP_OPENCODE_PROVIDERS ?? process.env.PAPERCLIP_OPENCODE_PROVIDERS,
+    resolveEnv,
+    notes,
+  );
+  const existingProvider = isPlainObject(existingConfig.provider) ? existingConfig.provider : {};
+  const nextProvider = gatewayProviders
+    ? { ...existingProvider, ...gatewayProviders }
+    : existingProvider;
+  if (gatewayProviders) {
+    notes.push(
+      `Injected ${Object.keys(gatewayProviders).length} custom OpenCode provider(s) from PAPERCLIP_OPENCODE_PROVIDERS: ${Object.keys(gatewayProviders).join(", ")}.`,
+    );
+  }
+
+  const nextConfig: Record<string, unknown> = {
    ...existingConfig,
    permission: {
      ...existingPermission,
      external_directory: "allow",
    },
  };
+  if (Object.keys(nextProvider).length > 0) {
+    nextConfig.provider = nextProvider;
+  }
+
+  // Pin OpenCode's auxiliary "small" model (used for session-title generation and
+  // other helper tasks) via PAPERCLIP_OPENCODE_SMALL_MODEL. OpenCode otherwise
+  // defaults the small model to a built-in provider default (e.g. a claude-* model
+  // for the anthropic provider); when that provider is repointed at a gateway that
+  // does not serve that exact model, the title-gen call fails and aborts the run.
+  // Setting small_model to a gateway-served model keeps every call on supported models.
+  const smallModel = (input.env.PAPERCLIP_OPENCODE_SMALL_MODEL ?? process.env.PAPERCLIP_OPENCODE_SMALL_MODEL)?.trim();
+  if (smallModel) {
+    nextConfig.small_model = smallModel;
+    notes.push(`Pinned OpenCode small_model to ${smallModel}.`);
+  }
  await fs.writeFile(runtimeConfigPath, `${JSON.stringify(nextConfig, null, 2)}\n`, "utf8");

  return {
@@ -95,9 +200,7 @@ export async function prepareOpenCodeRuntimeConfig(input: {
      ...input.env,
      XDG_CONFIG_HOME: runtimeConfigHome,
    },
-    notes: [
-      "Injected runtime OpenCode config with permission.external_directory=allow to avoid headless approval prompts.",
-    ],
+    notes,
    cleanup: async () => {
      await fs.rm(runtimeConfigHome, { recursive: true, force: true });
    },