From f232ae8b6103686580b8356cf5b5c68ec3808c61 Mon Sep 17 00:00:00 2001 From: Shivay Lamba Date: Sat, 5 Sep 2026 03:08:49 +0530 Subject: [PATCH] docs: add OpenCode provider guide --- README.md | 6 + docs/guides/README.md | 5 + docs/guides/configure-klaatu-in-opencode.md | 226 ++++++++++++++++++++ 3 files changed, 237 insertions(+) create mode 100644 docs/guides/README.md create mode 100644 docs/guides/configure-klaatu-in-opencode.md diff --git a/README.md b/README.md index 44dc269..3d0b36e 100644 --- a/README.md +++ b/README.md @@ -537,6 +537,12 @@ Version and platform still travel when you opt out — the server needs them to Sign-in is browser-based OAuth against your KlaatAI account — there are no API keys to generate or paste. `klaatcode login` opens a browser tab, you authenticate with KlaatAI, and a short-lived JWT plus refresh token are stored locally in `~/.klaatai/credentials.json` (mode `0600`, never synced or logged). The CLI silently refreshes the token in the background and recovers automatically from expiry mid-session; `klaatcode logout` clears everything. Every chat request goes straight to Klaatu over HTTPS with that token — the server enforces your plan's quota and never proxies your credentials anywhere else. +## Guides + +Step-by-step integration guides live in [`docs/guides`](docs/guides/README.md). + +- [Configure Klaatu in OpenCode](docs/guides/configure-klaatu-in-opencode.md) + ## Contributing We welcome contributions — see [CONTRIBUTING.md](CONTRIBUTING.md) for dev setup, the PR process, and what `bun run bench:selfcheck` needs to pass before a PR is reviewed. diff --git a/docs/guides/README.md b/docs/guides/README.md new file mode 100644 index 0000000..822cdec --- /dev/null +++ b/docs/guides/README.md @@ -0,0 +1,5 @@ +# Guides + +Use Klaatu's OpenAI-compatible API with other developer tools. + +- [Configure Klaatu in OpenCode](configure-klaatu-in-opencode.md) — connect OpenCode directly to Klaatu's Chat Completions API. diff --git a/docs/guides/configure-klaatu-in-opencode.md b/docs/guides/configure-klaatu-in-opencode.md new file mode 100644 index 0000000..fa5bd11 --- /dev/null +++ b/docs/guides/configure-klaatu-in-opencode.md @@ -0,0 +1,226 @@ +# Configure Klaatu in OpenCode + +KlaatAI exposes an OpenAI-compatible Chat Completions API. OpenCode can connect to it directly using the `@ai-sdk/openai-compatible` provider; no proxy is required. + +## Prerequisites + +You need: + +- [OpenCode](https://opencode.ai/docs/) installed +- A valid KlaatAI API key +- Access to `https://api.klaatai.com/v1` + +## 1. Add your KlaatAI API key + +Run: + +```bash +opencode auth login +``` + +When prompted, enter: + +```text +Provider: Other +Provider ID: klaatai +API key: +``` + +The provider ID must be exactly `klaatai`. Paste only the API key, without a `Bearer` prefix. + +OpenCode stores the credential in its local auth store. On Unix-like systems, the default location is: + +```text +~/.local/share/opencode/auth.json +``` + +Verify that it was saved: + +```bash +opencode auth list +``` + +You should see `klaatai` under **Credentials**. + +## 2. Configure the provider and model + +Create an `opencode.json` file. For project-specific configuration, place it in the project root: + +```text +your-project/opencode.json +``` + +For global configuration, use: + +```text +~/.config/opencode/opencode.json +``` + +Add this configuration: + +```json +{ + "$schema": "https://opencode.ai/config.json", + "model": "klaatai/klaatu", + "default_agent": "klaatu", + "provider": { + "klaatai": { + "npm": "@ai-sdk/openai-compatible", + "name": "KlaatAI", + "options": { + "baseURL": "https://api.klaatai.com/v1" + }, + "models": { + "klaatu": { + "name": "Klaatu" + } + } + } + }, + "agent": { + "klaatu": { + "description": "General-purpose coding agent powered by the Klaatu model router", + "mode": "primary", + "model": "klaatai/klaatu" + } + } +} +``` + +This defines: + +| Setting | Value | +|---|---| +| Provider ID | `klaatai` | +| Provider name | `KlaatAI` | +| API base URL | `https://api.klaatai.com/v1` | +| API protocol | OpenAI-compatible Chat Completions | +| Model ID | `klaatu` | +| OpenCode model ID | `klaatai/klaatu` | +| Default agent | `klaatu` | + +OpenCode uses `@ai-sdk/openai-compatible` for providers that implement `/v1/chat/completions`. See OpenCode's [custom provider documentation](https://opencode.ai/docs/providers/#custom-provider) for more detail. + +## 3. Verify the configuration + +Confirm that OpenCode recognizes the provider and model: + +```bash +opencode models klaatai +``` + +The output should include: + +```text +klaatai/klaatu +``` + +Confirm that the Klaatu agent exists: + +```bash +opencode agent list +``` + +You can also inspect the final merged configuration: + +```bash +opencode debug config +``` + +## 4. Start OpenCode + +Start normally: + +```bash +opencode +``` + +Or explicitly select the agent and model: + +```bash +opencode --agent klaatu --model klaatai/klaatu +``` + +Inside OpenCode, the status line should show: + +```text +Klaatu · Klaatu · KlaatAI +``` + +These values represent `Agent · Model · Provider`. + +## 5. Start a new session + +If OpenCode offers these choices: + +```text +New session +Continue the existing OpenCode session +``` + +Select **New session**. Existing sessions preserve the agent that was active when they were created, so continuing an older session may still show a different agent even after changing `default_agent`. + +You can also press Tab inside OpenCode to cycle between available primary agents. + +## Troubleshooting + +### “Model klaatai/klaatu is not valid” + +OpenCode did not load the custom provider configuration. + +Check that the model is registered: + +```bash +opencode models klaatai +``` + +Check the resolved configuration: + +```bash +opencode debug config +``` + +If you use project configuration, ensure `opencode.json` is in the directory where you run OpenCode or in the project root. You can explicitly specify its path: + +```bash +OPENCODE_CONFIG="$PWD/opencode.json" \ + opencode --agent klaatu --model klaatai/klaatu +``` + +Ensure that the schema and base URL are plain URLs rather than Markdown links. + +Correct: + +```json +"$schema": "https://opencode.ai/config.json" +``` + +Incorrect: + +```json +"$schema": "[https://opencode.ai/config.json](https://opencode.ai/config.json)" +``` + +### “Missing or invalid Authorization header” + +OpenCode has not stored a credential for the `klaatai` provider. + +Run `opencode auth login`, choose **Other**, use `klaatai` as the provider ID, and paste your API key. Then verify it with: + +```bash +opencode auth list +``` + +The provider ID used during authentication must match the provider key in `opencode.json`. + +### OpenCode still shows another agent + +The first value in OpenCode's status line is the agent name. If the status line shows another agent followed by `Klaatu · KlaatAI`, Klaatu is already being used as the model but an older agent remains active. + +To switch: + +- Start a new session. +- Press Tab until the `Klaatu` agent is selected. +- Or launch explicitly with `opencode --agent klaatu --model klaatai/klaatu`. + +The `default_agent` setting applies when creating a new session; it does not rewrite the agent stored in existing sessions.