# OpenCode Configuration

The OpenCode GUI client uses the OpenAI-compatible `chat/completions` protocol. After pointing a custom provider to 4AICode, you can use models such as `gpt-6-astra`, `gpt-5.6-sol`, `gpt-5.5`, `gpt-5.4`, `gpt-5.4-mini`, and `gpt-5.3-codex` in OpenCode.

## Prerequisites

- 4AICode token: Create one in [Dashboard → Manage Tokens](https://4aicode.com/tokens). The format is `sk-4ai-...`
- Provider ID: `4aicode`
- Base URL: `https://relay.4aicode.com/v1`
- Default model: `gpt-5.4`
- Code model: `gpt-5.3-codex`

## GUI Client Configuration

Open the gear settings in the lower-left corner, go to the Provider / Models configuration page, and add an OpenAI-compatible or Custom provider.

Fill in the interface fields as follows:

| Field | Value |
|---|---|
| Provider / Type | `OpenAI Compatible` or `Custom` |
| Name / Display name | `4AICode` |
| Provider ID | `4aicode` |
| Base URL / API Base URL | `https://relay.4aicode.com/v1` |
| API Key | `sk-4ai-xxxxxxxxxxxxxxxx` |
| Model ID | `gpt-5.4` |
| Small model ID | `gpt-5.4-mini` |
| Timeout / Request timeout | `600000` ms or `600` s |
| Chunk timeout / Stream timeout | `120000` ms or `120` s |

After saving, return to the main interface and select the following in the model picker at the bottom:

```text
4AICode / GPT-5.4
```

Then create a new conversation and send:

```text
Hello
```

If it responds normally, the GUI configuration is complete.

## Timeout Errors Shown in the GUI

When you see an error like the following, focus on checking the timeout fields in the GUI:

```text
Provider response headers timed out after 10000ms
```

This means the OpenCode GUI timed out while waiting for the provider response headers. The first response chunk from the Codex upstream may occasionally take longer than 10 seconds, so increase the timeout values in the GUI advanced settings:

| Field | Recommended value |
|---|---|
| Request timeout / Timeout | `600000` ms |
| Chunk timeout / Stream timeout | `120000` ms |

If your GUI version does not provide timeout input fields, use the `opencode.json` method below to add them.

## Configuration File Method

Suitable for GUI versions where timeout values cannot be entered directly. Create or edit:

```text
~/.config/opencode/opencode.json
```

Add:

```json
{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "4aicode": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "4AICode",
      "options": {
        "baseURL": "https://relay.4aicode.com/v1",
        "apiKey": "sk-4ai-xxxxxxxxxxxxxxxx",
        "timeout": 600000,
        "chunkTimeout": 120000
      },
      "models": {
        "gpt-6-astra": {
          "name": "GPT-6 Astra"
        },
        "gpt-5.6-sol": {
          "name": "GPT-5.6 Sol"
        },
        "gpt-5.6-terra": {
          "name": "GPT-5.6 Terra"
        },
        "gpt-5.6-luna": {
          "name": "GPT-5.6 Luna"
        },
        "gpt-5.5": {
          "name": "GPT-5.5"
        },
        "gpt-5.4": {
          "name": "GPT-5.4"
        },
        "gpt-5.4-mini": {
          "name": "GPT-5.4 Mini"
        },
        "gpt-5.3-codex": {
          "name": "GPT-5.3 Codex"
        }
      }
    }
  },
  "model": "4aicode/gpt-5.4",
  "small_model": "4aicode/gpt-5.4-mini"
}
```

After restarting the OpenCode GUI, select `4AICode / GPT-5.4` in the model picker.

## Add Credentials Interactively

Enter your project directory and start OpenCode:

```bash
opencode
```

Run the following in OpenCode:

```text
/connect
```

Select and enter the following as prompted:

```text
Provider: Other
Provider ID: 4aicode
API key: sk-4ai-xxxxxxxxxxxxxxxx
```

Then create or edit `opencode.json` in the project root directory, using the content from the “Configuration File Method” section above as a reference.

Return to OpenCode and run:

```text
/models
```

Select a model under `4AICode`.

## Environment Variable Method

Store the token in an environment variable. This is suitable for sharing `opencode.json` across a team.

```bash
export FOURAICODE_API_KEY="sk-4ai-xxxxxxxxxxxxxxxx"
```

`opencode.json`:

```json
{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "4aicode": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "4AICode",
      "options": {
        "baseURL": "https://relay.4aicode.com/v1",
        "apiKey": "{env:FOURAICODE_API_KEY}",
        "timeout": 600000,
        "chunkTimeout": 120000
      },
      "models": {
        "gpt-6-astra": {
          "name": "GPT-6 Astra"
        },
        "gpt-5.6-sol": {
          "name": "GPT-5.6 Sol"
        },
        "gpt-5.6-terra": {
          "name": "GPT-5.6 Terra"
        },
        "gpt-5.6-luna": {
          "name": "GPT-5.6 Luna"
        },
        "gpt-5.5": {
          "name": "GPT-5.5"
        },
        "gpt-5.4": {
          "name": "GPT-5.4"
        },
        "gpt-5.4-mini": {
          "name": "GPT-5.4 Mini"
        },
        "gpt-5.3-codex": {
          "name": "GPT-5.3 Codex"
        }
      }
    }
  },
  "model": "4aicode/gpt-5.4",
  "small_model": "4aicode/gpt-5.4-mini"
}
```

## Global Configuration Paths

Place user-level configuration here:

```text
~/.config/opencode/opencode.json
```

Place project-level configuration in the project root:

```text
opencode.json
```

Project-level configuration takes precedence and is suitable for pinning a provider and model for a specific code repository.

## Available Models

| Model | OpenCode model format | Use case |
|---|---|---|
| `gpt-6-astra` | `4aicode/gpt-6-astra` | New-generation flagship; billed at 15% of the official price |
| `gpt-5.6-sol` | `4aicode/gpt-5.6-sol` | Flagship model for complex coding, long-running tasks, and multi-file refactoring |
| `gpt-5.6-terra` | `4aicode/gpt-5.6-terra` | Balanced tier with strong value for money |
| `gpt-5.6-luna` | `4aicode/gpt-5.6-luna` | Lightweight tasks; cheaper and faster |
| `gpt-5.5` | `4aicode/gpt-5.5` | Previous-generation flagship |
| `gpt-5.4` | `4aicode/gpt-5.4` | Recommended default; more reliable for general tasks |
| `gpt-5.4-mini` | `4aicode/gpt-5.4-mini` | Lightweight tasks, quick validation, and cost-sensitive scenarios |
| `gpt-5.3-codex` | `4aicode/gpt-5.3-codex` | Code optimization and Codex-style tasks |

Use the full OpenCode format for model fields, for example, `4aicode/gpt-5.3-codex`. The display name in the interface can be `GPT-5.3 Codex`.

## FAQ

### Provider response headers timed out after 10000ms

This means the OpenCode GUI timed out while waiting for the provider response headers. The first response chunk from the Codex upstream may occasionally take longer than 10 seconds. Increase `timeout` and `chunkTimeout` in the configuration:

```json
{
  "provider": {
    "4aicode": {
      "options": {
        "baseURL": "https://relay.4aicode.com/v1",
        "timeout": 600000,
        "chunkTimeout": 120000
      }
    }
  }
}
```

Then send `Hello` using `gpt-5.4-mini` for a quick connectivity test. After confirming connectivity, switch back to `gpt-5.4` or `gpt-5.3-codex`.

### 401 Unauthorized

The API key has expired or was copied incorrectly. Create a new token in [Dashboard → Manage Tokens](https://4aicode.com/tokens), then update the `/connect` credentials or environment variable.

### 400 Model Not Supported

Use the literal model IDs listed in the table. Common choices are `4aicode/gpt-5.4` and `4aicode/gpt-5.3-codex`.

### The Model List Does Not Appear After Configuration

Check these three items:

- The Provider ID entered in `/connect` is `4aicode`
- The provider key in `opencode.json` is `"4aicode"`
- `model` uses the full format, such as `4aicode/gpt-5.4`

## References

- [OpenCode Providers](https://opencode.ai/docs/providers/)
- [OpenCode Config](https://opencode.ai/docs/config/)