mirror of
https://github.com/aljazceru/opencode.git
synced 2025-12-23 18:54:21 +01:00
docs: edit providers doc
This commit is contained in:
Jay V
@@ -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.
|
||||
|
||||
Reference in New Issue
Block a user