diff --git a/packages/web/src/content/docs/config.mdx b/packages/web/src/content/docs/config.mdx
index 1474cb91558..6fb768a12fc 100644
--- a/packages/web/src/content/docs/config.mdx
+++ b/packages/web/src/content/docs/config.mdx
@@ -266,6 +266,37 @@ You can also configure [local models](/docs/models#local). [Learn more](/docs/mo
 
 Some providers support additional configuration options beyond the generic `timeout` and `apiKey` settings.
 
+##### OpenAI-compatible (custom) providers
+
+If you're adding a custom provider or any OpenAI-compatible endpoint, set `npm` to `@ai-sdk/openai-compatible` and configure the API host via `options.baseURL` (sometimes called the host parameter).
+
+```json title="opencode.json"
+{
+  "$schema": "https://opencode.ai/config.json",
+  "provider": {
+    "myprovider": {
+      "npm": "@ai-sdk/openai-compatible",
+      "options": {
+        "baseURL": "https://api.myprovider.com/v1",
+        "apiKey": "{env:MYPROVIDER_API_KEY}",
+        "headers": {
+          "X-Custom-Header": "value"
+        }
+      },
+      "models": {
+        "my-model-name": {}
+      }
+    }
+  }
+}
+```
+
+- `options.baseURL` - API host/base URL for the provider (typically the `/v1` root).
+- `options.apiKey` - Optional API key; omit if you use `/connect`.
+- `options.headers` - Optional custom headers.
+
+[Learn more about custom providers](/docs/providers#custom-provider).
+
 ##### Amazon Bedrock
 
 Amazon Bedrock supports AWS-specific configuration:
diff --git a/packages/web/src/content/docs/providers.mdx b/packages/web/src/content/docs/providers.mdx
index 2a7d2ffb424..c7d95c7bae3 100644
--- a/packages/web/src/content/docs/providers.mdx
+++ b/packages/web/src/content/docs/providers.mdx
@@ -1768,7 +1768,7 @@ You can use any OpenAI-compatible provider with opencode. Most modern AI provide
    └
    ```
 
-4. Create or update your `opencode.json` file in your project directory:
+4. Create or update your OpenCode config (global or project). Use `~/.config/opencode/opencode.json` for a global setup (all projects) or `opencode.json` in your project root for project-only settings.
 
    ```json title="opencode.json" ""myprovider"" {5-15}
    {
@@ -1790,12 +1790,16 @@ You can use any OpenAI-compatible provider with opencode. Most modern AI provide
    }
    ```
 
+   :::note
+   Config files are merged. Project config overrides global config on conflicting keys. [Learn more](/docs/config#locations).
+   :::
+
    Here are the configuration options:
    - **npm**: AI SDK package to use, `@ai-sdk/openai-compatible` for OpenAI-compatible providers
    - **name**: Display name in UI.
    - **models**: Available models.
-   - **options.baseURL**: API endpoint URL.
-   - **options.apiKey**: Optionally set the API key, if not using auth.
+   - **options.baseURL**: API host/base URL (for OpenAI-compatible providers this is usually the `/v1` root, e.g. `https://api.myprovider.com/v1`).
+   - **options.apiKey**: Optionally set the API key if you are not using `/connect`.
    - **options.headers**: Optionally set custom headers.
 
    More on the advanced options in the example below.