From 5ee994c31f5c29e9b8dcbcbc06f2e26dfd15b8e5 Mon Sep 17 00:00:00 2001 From: Jay V Date: Thu, 31 Jul 2025 14:11:40 -0400 Subject: [PATCH] docs: edit providers doc --- .../web/src/content/docs/docs/providers.mdx | 180 ++++++------------ 1 file changed, 59 insertions(+), 121 deletions(-) diff --git a/packages/web/src/content/docs/docs/providers.mdx b/packages/web/src/content/docs/docs/providers.mdx index 7426500d..565ec3f5 100644 --- a/packages/web/src/content/docs/docs/providers.mdx +++ b/packages/web/src/content/docs/docs/providers.mdx @@ -45,72 +45,6 @@ You can customize the base URL for any provider by setting the `baseURL` option. --- -## Troubleshooting - -### Credential Loop Issue - -If you're stuck in a credential loop when adding a custom provider (like Cerebras), this usually happens when the provider configuration is incomplete. Here's how to fix it: - -1. **Complete the auth setup**: Make sure you've successfully added the credential using `opencode auth login` and selected **Other**. - -2. **Configure the provider**: The credential alone isn't enough. You must also configure the provider in your `opencode.json` file with the correct `npm` package, `baseURL`, and models. - -3. **Use the correct npm package**: - - For Cerebras: Use `@ai-sdk/cerebras` (not `@ai-sdk/openai-compatible`) - - For most other OpenAI-compatible providers: Use `@ai-sdk/openai-compatible` - -4. **Example working configuration**: - ```json title="opencode.json" - { - "$schema": "https://opencode.ai/config.json", - "model": "cerebras/qwen-3-235b-a22b", - "provider": { - "cerebras": { - "npm": "@ai-sdk/cerebras", - "name": "Cerebras", - "options": { - "baseURL": "https://api.cerebras.ai/v1" - }, - "models": { - "qwen-3-235b-a22b": { - "name": "Qwen-3-235b-a22b" - } - } - } - } - } - ``` - -### Global vs Local Configuration - -opencode looks for configuration in this order: - -1. **Local config**: `./opencode.json` in your current project directory -2. **Global config**: `~/.local/share/opencode/auth.json` (credentials only) - -:::tip -If you want to use a provider globally, add the provider configuration to a local `opencode.json` file in each project where you want to use it. The credentials from the global auth file will be automatically used. -::: - -**Best practice**: -- Store credentials globally using `opencode auth login` -- Store provider configurations locally in each project's `opencode.json` - -### Common Configuration Mistakes - -1. **Wrong npm package**: Using `@ai-sdk/openai-compatible` when a specific package exists (like `@ai-sdk/cerebras`) - -2. **Missing baseURL**: Always include the correct API endpoint in the `options.baseURL` field - -3. **Incomplete model configuration**: Make sure to define at least one model in the `models` object - -4. **API key format**: Different providers use different API key prefixes: - - OpenAI: `sk-...` - - Cerebras: `csk-...` - - Anthropic: Uses OAuth (no manual key needed) - ---- - ## Directory Let's look at some of the providers in detail. If you'd like to add a provider to the @@ -667,8 +601,6 @@ To add any **OpenAI-compatible** provider that's not listed in `opencode auth lo You can use any OpenAI-compatible provider with opencode. Most modern AI providers offer OpenAI-compatible APIs. ::: -#### Step 1: Add Credentials - 1. Run `opencode auth login` and scroll down to **Other**. ```bash @@ -682,7 +614,7 @@ You can use any OpenAI-compatible provider with opencode. Most modern AI provide └ ``` -2. Enter a unique ID for the provider (use lowercase, no spaces). +2. Enter a unique ID for the provider. ```bash $ opencode auth login @@ -695,7 +627,7 @@ You can use any OpenAI-compatible provider with opencode. Most modern AI provide ``` :::note - Choose a memorable ID - you'll use this in your config file. + Choose a memorable ID, you'll use this in your config file. ::: 3. Enter your API key for the provider. @@ -712,19 +644,60 @@ You can use any OpenAI-compatible provider with opencode. Most modern AI provide └ ``` -#### Step 2: Configure Provider +4. Create or update your `opencode.json` file in your project directory: -Create or update your `opencode.json` file in your project directory: + ```json title="opencode.json" "\"myprovider\"" {5-15} + { + "$schema": "https://opencode.ai/config.json", + "provider": { + "myprovider": { + "npm": "@ai-sdk/openai-compatible", + "name": "My AI ProviderDisplay Name", + "options": { + "baseURL": "https://api.myprovider.com/v1" + }, + "models": { + "my-model-name": { + "name": "My Model Display Name" + } + } + } + } + } + ``` -```json title="opencode.json" "myprovider" {5-15} + 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.headers**: Optionally set custom headers. + + More on the advanced options in the example below. + +5. Run the `/models` command and your custom provider and models will appear in the selection list. + +--- + +##### Example + +Here's an example setting the `apiKey` and `headers` options. + +```json title="opencode.json" {9,11} { "$schema": "https://opencode.ai/config.json", "provider": { "myprovider": { "npm": "@ai-sdk/openai-compatible", - "name": "My AI Provider", + "name": "My AI ProviderDisplay Name", "options": { - "baseURL": "https://api.myprovider.com/v1" + "baseURL": "https://api.myprovider.com/v1", + "apiKey": "{env:ANTHROPIC_API_KEY}", + "headers": { + "Authorization": "Bearer custom-token" + } }, "models": { "my-model-name": { @@ -736,15 +709,7 @@ Create or update your `opencode.json` file in your project directory: } ``` -#### Configuration Options - -| Field | Description | Required | -|-------|-------------|----------| -| `npm` | AI SDK package to use | ✅ | -| `name` | Display name in UI | ✅ | -| `options.baseURL` | API endpoint URL | ✅ | -| `models` | Available models | ✅ | -| `options.apiKey` | API key (if not using auth) | ❌ | +We are setting the `apiKey` using the `env` variable syntax, [learn more](/docs/config#env-vars). #### Common Examples @@ -789,46 +754,19 @@ Create or update your `opencode.json` file in your project directory: } } ``` +--- -**Local API (with custom headers):** -```json title="opencode.json" -{ - "$schema": "https://opencode.ai/config.json", - "provider": { - "local": { - "npm": "@ai-sdk/openai-compatible", - "name": "Local API", - "options": { - "baseURL": "http://localhost:8000/v1", - "headers": { - "Authorization": "Bearer custom-token" - } - }, - "models": { - "local-model": { - "name": "Local Model" - } - } - } - } -} -``` +## Troubleshooting -#### Step 3: Select Model +If you are having trouble with configuring a provider, check the following: -Run the `/models` command to select your custom provider's model: +1. **Check the auth setup**: Run `opencode auth list` to see if the credentials + for the provider are added to your config. -```bash -$ opencode -> /models -``` + This doesn't apply to providers like Amazon Bedrock, that rely on environment variables for their auth. -Your custom provider and models will appear in the selection list. - -#### Tips - -- **Provider ID**: Use lowercase letters and hyphens only (e.g., `my-provider`) -- **Model names**: Use the exact model ID from the provider's API documentation -- **Base URL**: Always include the full path (usually ending in `/v1`) -- **Testing**: Start with one model to test the configuration before adding more +2. For custom providers, check the opencode config and: + - Make sure the provider ID used in `opencode auth login` matches the ID in your opencode config. + - The right npm package is used for the provider. For example, use `@ai-sdk/cerebras` for Cerebras. And for all other OpenAI-compatible providers, use `@ai-sdk/openai-compatible`. + - Check correct API endpoint is used in the `options.baseURL` field.