feat(config): allow unknown keys with warnings for forward compatibility

Change user-facing config schemas (Keybinds, Provider, Info) from .strict() to .passthrough() so unknown config keys are ignored rather than causing validation errors.

Add warning logs for unknown keys so users still get feedback about potential typos while configs from newer versions still work.

This enables configs with newer options (e.g., new keybinds) to work on older OpenCode versions that don't recognize those keys.

Author: CasualDeveloper

packages/opencode/src/cli/cmd/tui/context/keybind.tsx

@@ -15,7 +15,7 @@ export const { use: useKeybind, provider: KeybindProvider } = createSimpleContex
     const keybinds = createMemo(() => {
       return pipe(
         sync.data.config.keybinds ?? {},
-        mapValues((value) => Keybind.parse(value)),
+        mapValues((value) => (typeof value === "string" ? Keybind.parse(value) : [])),
       )
     })
     const [store, setStore] = createStore({

packages/opencode/src/config/config.ts

@@ -581,7 +581,7 @@ export namespace Config {
       terminal_title_toggle: z.string().optional().default("none").describe("Toggle terminal title"),
       tips_toggle: z.string().optional().default("<leader>h").describe("Toggle tips on home screen"),
     })
-    .strict()
+    .passthrough()
     .meta({
       ref: "KeybindsConfig",
     })
@@ -646,7 +646,7 @@ export namespace Config {
         .catchall(z.any())
         .optional(),
     })
-    .strict()
+    .passthrough()
     .meta({
       ref: "ProviderConfig",
     })
@@ -849,7 +849,7 @@ export namespace Config {
         })
         .optional(),
     })
-    .strict()
+    .passthrough()
     .meta({
       ref: "Config",
     })
@@ -882,6 +882,36 @@ export namespace Config {
     return result
   })
 
+  const INFO_KNOWN_KEYS = new Set(Object.keys(Info.shape))
+  const KEYBINDS_KNOWN_KEYS = new Set(Object.keys(Keybinds.shape))
+  const PROVIDER_KNOWN_KEYS = new Set(Object.keys(Provider.shape))
+
+  function warnUnknownKeys(raw: Record<string, unknown>, filepath: string) {
+    for (const key of Object.keys(raw)) {
+      if (!INFO_KNOWN_KEYS.has(key)) {
+        log.warn("unknown config key", { key, path: filepath })
+      }
+    }
+    if (raw.keybinds && typeof raw.keybinds === "object") {
+      for (const key of Object.keys(raw.keybinds)) {
+        if (!KEYBINDS_KNOWN_KEYS.has(key)) {
+          log.warn("unknown keybind", { key, path: filepath })
+        }
+      }
+    }
+    if (raw.provider && typeof raw.provider === "object") {
+      for (const [name, provider] of Object.entries(raw.provider)) {
+        if (provider && typeof provider === "object") {
+          for (const key of Object.keys(provider)) {
+            if (!PROVIDER_KNOWN_KEYS.has(key)) {
+              log.warn("unknown provider key", { provider: name, key, path: filepath })
+            }
+          }
+        }
+      }
+    }
+  }
+
   async function loadFile(filepath: string): Promise<Info> {
     log.info("loading", { path: filepath })
     let text = await Bun.file(filepath)
@@ -962,20 +992,21 @@ export namespace Config {
 
     const parsed = Info.safeParse(data)
     if (parsed.success) {
+      warnUnknownKeys(data, configFilepath)
       if (!parsed.data.$schema) {
         parsed.data.$schema = "https://opencode.ai/config.json"
         await Bun.write(configFilepath, JSON.stringify(parsed.data, null, 2))
       }
-      const data = parsed.data
-      if (data.plugin) {
-        for (let i = 0; i < data.plugin.length; i++) {
-          const plugin = data.plugin[i]
+      const result = parsed.data
+      if (result.plugin) {
+        for (let i = 0; i < result.plugin.length; i++) {
+          const plugin = result.plugin[i]
           try {
-            data.plugin[i] = import.meta.resolve!(plugin, configFilepath)
+            result.plugin[i] = import.meta.resolve!(plugin, configFilepath)
           } catch (err) {}
         }
       }
-      return data
+      return result
     }
 
     throw new InvalidError({

packages/opencode/test/config/config.test.ts

@@ -148,23 +148,24 @@ test("handles file inclusion substitution", async () => {
   })
 })
 
-test("validates config schema and throws on invalid fields", async () => {
+test("ignores unknown config fields for forward compatibility", async () => {
   await using tmp = await tmpdir({
     init: async (dir) => {
       await Bun.write(
         path.join(dir, "opencode.json"),
         JSON.stringify({
           $schema: "https://opencode.ai/config.json",
-          invalid_field: "should cause error",
+          unknown_future_field: "should be ignored",
+          theme: "known_theme",
         }),
       )
     },
   })
   await Instance.provide({
     directory: tmp.path,
     fn: async () => {
-      // Strict schema should throw an error for invalid fields
-      await expect(Config.get()).rejects.toThrow()
+      const config = await Config.get()
+      expect(config.theme).toBe("known_theme")
     },
   })
 })

packages/plugin/package.json

@@ -24,4 +24,4 @@
     "typescript": "catalog:",
     "@typescript/native-preview": "catalog:"
   }
-}
+}

packages/sdk/js/package.json

@@ -29,4 +29,4 @@
   "publishConfig": {
     "directory": "dist"
   }
-}
+}