Skip to content

Commit 5ee994c

Browse files
jayairjayair
committed
docs: edit providers doc
1 parent fc73d4b commit 5ee994c

1 file changed

Lines changed: 59 additions & 121 deletions

File tree

‎packages/web/src/content/docs/docs/providers.mdx‎

Lines changed: 59 additions & 121 deletions
Original file line numberDiff line numberDiff line change
@@ -45,72 +45,6 @@ You can customize the base URL for any provider by setting the `baseURL` option.
4545

4646
---
4747

48-
## Troubleshooting
49-
50-
### Credential Loop Issue
51-
52-
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:
53-
54-
1. **Complete the auth setup**: Make sure you've successfully added the credential using `opencode auth login` and selected **Other**.
55-
56-
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.
57-
58-
3. **Use the correct npm package**:
59-
- For Cerebras: Use `@ai-sdk/cerebras` (not `@ai-sdk/openai-compatible`)
60-
- For most other OpenAI-compatible providers: Use `@ai-sdk/openai-compatible`
61-
62-
4. **Example working configuration**:
63-
```json title="opencode.json"
64-
{
65-
"$schema": "https://opencode.ai/config.json",
66-
"model": "cerebras/qwen-3-235b-a22b",
67-
"provider": {
68-
"cerebras": {
69-
"npm": "@ai-sdk/cerebras",
70-
"name": "Cerebras",
71-
"options": {
72-
"baseURL": "https://api.cerebras.ai/v1"
73-
},
74-
"models": {
75-
"qwen-3-235b-a22b": {
76-
"name": "Qwen-3-235b-a22b"
77-
}
78-
}
79-
}
80-
}
81-
}
82-
```
83-
84-
### Global vs Local Configuration
85-
86-
opencode looks for configuration in this order:
87-
88-
1. **Local config**: `./opencode.json` in your current project directory
89-
2. **Global config**: `~/.local/share/opencode/auth.json` (credentials only)
90-
91-
:::tip
92-
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.
93-
:::
94-
95-
**Best practice**:
96-
- Store credentials globally using `opencode auth login`
97-
- Store provider configurations locally in each project's `opencode.json`
98-
99-
### Common Configuration Mistakes
100-
101-
1. **Wrong npm package**: Using `@ai-sdk/openai-compatible` when a specific package exists (like `@ai-sdk/cerebras`)
102-
103-
2. **Missing baseURL**: Always include the correct API endpoint in the `options.baseURL` field
104-
105-
3. **Incomplete model configuration**: Make sure to define at least one model in the `models` object
106-
107-
4. **API key format**: Different providers use different API key prefixes:
108-
- OpenAI: `sk-...`
109-
- Cerebras: `csk-...`
110-
- Anthropic: Uses OAuth (no manual key needed)
111-
112-
---
113-
11448
## Directory
11549

11650
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
667601
You can use any OpenAI-compatible provider with opencode. Most modern AI providers offer OpenAI-compatible APIs.
668602
:::
669603

670-
#### Step 1: Add Credentials
671-
672604
1. Run `opencode auth login` and scroll down to **Other**.
673605

674606
```bash
@@ -682,7 +614,7 @@ You can use any OpenAI-compatible provider with opencode. Most modern AI provide
682614
└
683615
```
684616

685-
2. Enter a unique ID for the provider (use lowercase, no spaces).
617+
2. Enter a unique ID for the provider.
686618

687619
```bash
688620
$ opencode auth login
@@ -695,7 +627,7 @@ You can use any OpenAI-compatible provider with opencode. Most modern AI provide
695627
```
696628

697629
:::note
698-
Choose a memorable ID - you'll use this in your config file.
630+
Choose a memorable ID, you'll use this in your config file.
699631
:::
700632

701633
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
712644
└
713645
```
714646
715-
#### Step 2: Configure Provider
647+
4. Create or update your `opencode.json` file in your project directory:
648+
649+
```json title="opencode.json" "\"myprovider\"" {5-15}
650+
{
651+
"$schema": "https://opencode.ai/config.json",
652+
"provider": {
653+
"myprovider": {
654+
"npm": "@ai-sdk/openai-compatible",
655+
"name": "My AI ProviderDisplay Name",
656+
"options": {
657+
"baseURL": "https://api.myprovider.com/v1"
658+
},
659+
"models": {
660+
"my-model-name": {
661+
"name": "My Model Display Name"
662+
}
663+
}
664+
}
665+
}
666+
}
667+
```
668+
669+
Here are the configuration options:
670+
671+
- **npm**: AI SDK package to use, `@ai-sdk/openai-compatible` for OpenAI-compatible providers
672+
- **name**: Display name in UI.
673+
- **models**: Available models.
674+
- **options.baseURL**: API endpoint URL.
675+
- **options.apiKey**: Optionally set the API key, if not using auth.
676+
- **options.headers**: Optionally set custom headers.
677+
678+
More on the advanced options in the example below.
679+
680+
5. Run the `/models` command and your custom provider and models will appear in the selection list.
681+
682+
---
683+
684+
##### Example
716685
717-
Create or update your `opencode.json` file in your project directory:
686+
Here's an example setting the `apiKey` and `headers` options.
718687
719-
```json title="opencode.json" "myprovider" {5-15}
688+
```json title="opencode.json" {9,11}
720689
{
721690
"$schema": "https://opencode.ai/config.json",
722691
"provider": {
723692
"myprovider": {
724693
"npm": "@ai-sdk/openai-compatible",
725-
"name": "My AI Provider",
694+
"name": "My AI ProviderDisplay Name",
726695
"options": {
727-
"baseURL": "https://api.myprovider.com/v1"
696+
"baseURL": "https://api.myprovider.com/v1",
697+
"apiKey": "{env:ANTHROPIC_API_KEY}",
698+
"headers": {
699+
"Authorization": "Bearer custom-token"
700+
}
728701
},
729702
"models": {
730703
"my-model-name": {
@@ -736,15 +709,7 @@ Create or update your `opencode.json` file in your project directory:
736709
}
737710
```
738711
739-
#### Configuration Options
740-
741-
| Field | Description | Required |
742-
|-------|-------------|----------|
743-
| `npm` | AI SDK package to use | ✅ |
744-
| `name` | Display name in UI | ✅ |
745-
| `options.baseURL` | API endpoint URL | ✅ |
746-
| `models` | Available models | ✅ |
747-
| `options.apiKey` | API key (if not using auth) | ❌ |
712+
We are setting the `apiKey` using the `env` variable syntax, [learn more](/docs/config#env-vars).
748713
749714
#### Common Examples
750715
@@ -789,46 +754,19 @@ Create or update your `opencode.json` file in your project directory:
789754
}
790755
}
791756
```
757+
---
792758
793-
**Local API (with custom headers):**
794-
```json title="opencode.json"
795-
{
796-
"$schema": "https://opencode.ai/config.json",
797-
"provider": {
798-
"local": {
799-
"npm": "@ai-sdk/openai-compatible",
800-
"name": "Local API",
801-
"options": {
802-
"baseURL": "http://localhost:8000/v1",
803-
"headers": {
804-
"Authorization": "Bearer custom-token"
805-
}
806-
},
807-
"models": {
808-
"local-model": {
809-
"name": "Local Model"
810-
}
811-
}
812-
}
813-
}
814-
}
815-
```
816-
817-
#### Step 3: Select Model
818-
819-
Run the `/models` command to select your custom provider's model:
759+
## Troubleshooting
820760
821-
```bash
822-
$ opencode
823-
> /models
824-
```
761+
If you are having trouble with configuring a provider, check the following:
825762
826-
Your custom provider and models will appear in the selection list.
763+
1. **Check the auth setup**: Run `opencode auth list` to see if the credentials
764+
for the provider are added to your config.
827765
828-
#### Tips
766+
This doesn't apply to providers like Amazon Bedrock, that rely on environment variables for their auth.
829767
830-
- **Provider ID**: Use lowercase letters and hyphens only (e.g., `my-provider`)
831-
- **Model names**: Use the exact model ID from the provider's API documentation
832-
- **Base URL**: Always include the full path (usually ending in `/v1`)
833-
- **Testing**: Start with one model to test the configuration before adding more
768+
2. For custom providers, check the opencode config and:
834769
770+
- Make sure the provider ID used in `opencode auth login` matches the ID in your opencode config.
771+
- 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`.
772+
- Check correct API endpoint is used in the `options.baseURL` field.

0 commit comments

Comments
 (0)