From df72239940436c54ce5d3f8b47b4d22261fa5941 Mon Sep 17 00:00:00 2001 From: Aleh Mikhnovich Date: Mon, 3 Aug 2026 22:08:44 +0300 Subject: [PATCH] docs: add agentic tools tutorials --- .../2.agentic-tools/0.overview.md | 60 +++++ .../1.developers/2.agentic-tools/1.codex.md | 215 ++++++++++++++++++ .../2.agentic-tools/2.github-copilot.md | 55 +++++ .../2.agentic-tools/3.open-claw.md | 84 +++++++ .../2.agentic-tools/4.opencode.md | 73 ++++++ .../2.agentic-tools/5.claude-code.md | 86 +++++++ sidebars.js | 36 +++ 7 files changed, 609 insertions(+) create mode 100644 docs/tutorials/1.developers/2.agentic-tools/0.overview.md create mode 100644 docs/tutorials/1.developers/2.agentic-tools/1.codex.md create mode 100644 docs/tutorials/1.developers/2.agentic-tools/2.github-copilot.md create mode 100644 docs/tutorials/1.developers/2.agentic-tools/3.open-claw.md create mode 100644 docs/tutorials/1.developers/2.agentic-tools/4.opencode.md create mode 100644 docs/tutorials/1.developers/2.agentic-tools/5.claude-code.md diff --git a/docs/tutorials/1.developers/2.agentic-tools/0.overview.md b/docs/tutorials/1.developers/2.agentic-tools/0.overview.md new file mode 100644 index 000000000..e15bb64c9 --- /dev/null +++ b/docs/tutorials/1.developers/2.agentic-tools/0.overview.md @@ -0,0 +1,60 @@ +# Agentic Tools + +## Introduction + +Agentic coding tools — command-line agents and IDE assistants — run their turns against a model backend. This section shows how to point that backend at DIAL, so a DIAL-hosted model answers through the tool while DIAL applies its roles, quotas, and cost tracking. + +Each tutorial is self-contained and ends the same way: a model replying to you *through DIAL*, so you can see the connection working. Follow the one for the tool you use. + +> Refer to [DIAL as Agentic Platform](/docs/platform/0.architecture-and-concepts/4.agentic-platform.md) to learn how DIAL itself hosts and serves agents, as opposed to being used as a backend for one. + +- [Connect Codex to DIAL](/docs/tutorials/1.developers/2.agentic-tools/1.codex.md) — the command-line agent that speaks the OpenAI Responses API, direct or through a translating proxy +- [Connect GitHub Copilot to DIAL](/docs/tutorials/1.developers/2.agentic-tools/2.github-copilot.md) — add your DIAL deployments to the Copilot model picker in VS Code +- [Connect Open Claw to DIAL](/docs/tutorials/1.developers/2.agentic-tools/3.open-claw.md) — register DIAL as a model provider in the self-hosted agent gateway +- [Connect OpenCode to DIAL](/docs/tutorials/1.developers/2.agentic-tools/4.opencode.md) — add DIAL as a custom provider in the terminal coding agent +- [Connect Claude Code to DIAL](/docs/tutorials/1.developers/2.agentic-tools/5.claude-code.md) — point Anthropic's command-line agent at DIAL's native Anthropic Messages API + +## Prerequisites + +Every tutorial needs two things: + +- The URL of your DIAL host, written throughout as ``. +- A DIAL API key, written throughout as ``. + +Each tutorial lists any extra tools it needs at the top. Replace `` with your real host and `` with your real key everywhere they appear. + +## Before you begin + +### Check your DIAL version + +Some behavior depends on your DIAL release. The native Responses API — which lets Codex reach DIAL without a proxy — is only available from DIAL **v0.45** onwards, and how deployments handle request settings can vary by release. Ask the host for its version (no key needed): + +```bash +curl -s https:///version +``` + +On Windows, use `curl.exe`, or `Invoke-RestMethod` if curl is unavailable: + +```powershell +curl.exe -s https:///version +Invoke-RestMethod https:///version +``` + +It prints a bare version string such as `0.45`. Below v0.45, no deployment serves the Responses API, so Codex must use the proxy path regardless of any `responses_api` flag. + +### Azure-backed deployment settings + +Azure OpenAI–backed deployments (for example, GPT-5.x) need two extra request settings. If a call fails with one of these errors, apply the matching fix wherever the tutorial sets the DIAL URL or the output-token limit: + +- `api-version is a required query parameter` — append `?api-version=2025-04-01-preview` to the DIAL URL the tool calls (the chat-completions or `/responses` URL). +- `Unsupported parameter: 'max_tokens' … use 'max_completion_tokens'` — Azure-backed GPT-5.x reject the plain `max_tokens` field for any value. Switch the tool to its `max_completion_tokens` equivalent, or send no output cap at all, since uncapped requests are accepted. + +An output cap is never required. You only think about it when a tool sends one: GPT-5.x care about the field **name** above, while other deployments accept `max_tokens` but reject a **value** above that deployment's completion-token ceiling (`max_tokens is too large`). Not every deployment needs an `api-version` either, so leave both settings out unless you hit the matching error. + +**Note**: Do not trust a deployment's `max_tokens_supported` flag here — GPT-5.x report it `true` yet still reject `max_tokens`. + +## Additional Information + +Start with [Connect Codex to DIAL](/docs/tutorials/1.developers/2.agentic-tools/1.codex.md) — it is the most involved case, and shows both the direct and proxy paths. + +> Refer to the [Unified API reference](https://dialx.ai/dial_api) for the API every tool in this section calls. diff --git a/docs/tutorials/1.developers/2.agentic-tools/1.codex.md b/docs/tutorials/1.developers/2.agentic-tools/1.codex.md new file mode 100644 index 000000000..a151e0da7 --- /dev/null +++ b/docs/tutorials/1.developers/2.agentic-tools/1.codex.md @@ -0,0 +1,215 @@ +# Connect Codex to DIAL + +## Introduction + +From this tutorial, you will learn how to point Codex, the command-line coding agent, at DIAL and watch a DIAL-hosted model reply. Codex speaks only the OpenAI Responses API, so how it reaches DIAL depends on your deployment: one that exposes the Responses API natively connects directly, while a Chat-Completions-only deployment needs a small translating proxy. Step 1 shows which case you are in. By the end, `codex exec` sends a prompt and prints the model's reply, routed through your DIAL deployment with DIAL's roles, quotas, and cost tracking applied. + +## Prerequisites + +- A DIAL host and API key. Refer to [Prerequisites](/docs/tutorials/1.developers/2.agentic-tools/0.overview.md#prerequisites). +- [Codex](https://github.com/openai/codex) installed. +- For the proxy path only: [Docker](https://docs.docker.com/get-docker/) and [git](https://git-scm.com/downloads). + +## Step 1: Find out which path your deployment needs + +Ask DIAL for the deployment's metadata and read the `responses_api` flag: + +```bash +curl -s -H "Api-Key: " \ + "https:///openai/deployments/gpt-5.4-2026-03-05" \ + | grep -o '"responses_api":[^,]*' +``` + +On Windows (PowerShell), call `curl.exe` — PowerShell's `curl` is an `Invoke-WebRequest` alias — and pipe to `findstr`: + +```powershell +curl.exe -s -H "Api-Key: " ` + "https:///openai/deployments/gpt-5.4-2026-03-05" | findstr responses_api +``` + +If curl is unavailable, `Invoke-RestMethod` reads the flag directly and prints `True` or `False`: + +```powershell +(Invoke-RestMethod -Headers @{ "Api-Key" = "" } ` + "https:///openai/deployments/gpt-5.4-2026-03-05").features.responses_api +``` + +- `"responses_api":true` — follow [The direct path](#the-direct-path) and ignore the proxy. +- `"responses_api":false` — your deployment is chat-only; follow [The proxy path](#the-proxy-path). + +**Note**: The `responses_api` flag only means anything on DIAL v0.45+ (refer to [Check your DIAL version](/docs/tutorials/1.developers/2.agentic-tools/0.overview.md#check-your-dial-version)); on older DIAL every deployment is chat-only, so take the proxy path. Even on v0.45+, many deployments are still chat-only, so check the flag rather than assume. You can also test it functionally: a `POST` to `https:///openai/v1/responses` returns `200` on a Responses-capable deployment and `503` on a chat-only one. + +## The direct path + +Follow this path when Step 1 reported `responses_api: true`. + +### Step 2: Tell Codex about DIAL + +Open `~/.codex/config.toml` (on Windows, `%USERPROFILE%\.codex\config.toml`; create it if it does not exist) and paste the following. The `model_provider` and `model_providers` keys only take effect in this user-level file. + +```toml +model = "gpt-5.4-2026-03-05" # the DIAL deployment id; Codex sends it to DIAL as the model +model_provider = "dial" +disable_response_storage = true # DIAL doesn't store responses, so this must be on + +[model_providers.dial] +name = "DIAL (direct)" +base_url = "https:///openai/v1" # Codex appends /responses +wire_api = "responses" # the only valid value — Codex's old "chat" wire was removed +env_key = "DIAL_API_KEY" +env_http_headers = { "Api-Key" = "DIAL_API_KEY" } # DIAL authenticates on Api-Key +requires_openai_auth = false # don't enforce the sk- prefix check +query_params = { api-version = "2025-04-01-preview" } # Azure-backed deployments require this +``` + +**Note**: Put the `api-version` in `query_params`, not in `base_url`. Codex appends `/responses` to `base_url`, so a query string there lands in the wrong place. Drop the `query_params` line if your DIAL host does not require an Azure API version — refer to [Azure-backed deployment settings](/docs/tutorials/1.developers/2.agentic-tools/0.overview.md#azure-backed-deployment-settings). + +### Step 3: Set your API key + +Bash or Zsh: + +```bash +export DIAL_API_KEY="" +``` + +PowerShell: + +```powershell +$env:DIAL_API_KEY = "" +``` + +### Step 4: Check the wiring + +```bash +codex doctor +``` + +Your config loads cleanly and a row appears for the `dial` provider — `config.toml parse ok`, `auth ✓` with `provider auth env var DIAL_API_KEY (present)`, and `wire API responses`. The model line names your deployment, for example `gpt-5.4-2026-03-05 · dial`. + +### Step 5: Run Codex + +```bash +codex exec "Reply with exactly: PONG" +``` + +You see `PONG` printed back, routed Codex → DIAL with no proxy in between. Run plain `codex` for the interactive session you will use day to day. + +The direct path is complete. Skip to [Additional Information](#additional-information). + +## The proxy path + +Follow this path when Step 1 reported `responses_api: false`. Put a small translating proxy between Codex and DIAL. The proxy ([responses-proxy](https://github.com/chutesai/responses-proxy)) converts Codex's Responses calls into the Chat Completions calls DIAL understands and forwards your `Api-Key` header to DIAL. + +### Step 2: Build and run the proxy + +There is no published image, so build it from the repo — a one-time Rust build: + +```bash +git clone https://github.com/chutesai/responses-proxy && cd responses-proxy +``` + +**Warning**: Do not use the project's `install_codex.sh` one-liner for DIAL. It installs chutes' own fork of Codex and points it at their hosted proxy (`responses.chutes.ai`, whose backend is chutes — not DIAL), and the config it writes omits both `disable_response_storage` and the `Api-Key` header DIAL needs. Build and run the proxy yourself, as below. + +Point the proxy's `BACKEND_URL` at your DIAL chat deployment — the deployment id lives in the URL. If your DIAL's Chat Completions endpoint requires an Azure API version, append `?api-version=2025-04-01-preview` to `BACKEND_URL` (refer to [Azure-backed deployment settings](/docs/tutorials/1.developers/2.agentic-tools/0.overview.md#azure-backed-deployment-settings)). Start it either way: + +```bash +# Option A — Docker Compose (the maintainers' path). --build compiles the image; +# naming the service skips the bundled Caddy/TLS sidecar you don't need locally. +BACKEND_URL="https:///openai/deployments/gpt-5.4-2026-03-05/chat/completions" \ + docker compose up --build openai-responses-proxy +``` + +```bash +# Option B — plain Docker (build once, then run). +docker build -t responses-proxy . +docker run -d --name responses-proxy -p 8282:8282 \ + -e BACKEND_URL="https:///openai/deployments/gpt-5.4-2026-03-05/chat/completions" \ + responses-proxy +``` + +On Windows (PowerShell), the inline `VAR=… command` form and the `\` line-continuation do not work. Set the variable with `$env:` first and use a backtick to continue lines: + +```powershell +$env:BACKEND_URL = "https:///openai/deployments/gpt-5.4-2026-03-05/chat/completions" +docker compose up --build openai-responses-proxy # Option A +# or, after `docker build -t responses-proxy .` : +docker run -d --name responses-proxy -p 8282:8282 ` + -e BACKEND_URL="$env:BACKEND_URL" responses-proxy # Option B +``` + +The proxy now listens on `http://0.0.0.0:8282`. Confirm it is up: + +```bash +curl -s -o /dev/null -w "%{http_code}\n" http://0.0.0.0:8282/health +``` + +On Windows, use `curl.exe`, or `Invoke-WebRequest` if curl is unavailable: + +```powershell +curl.exe -s -o NUL -w "%{http_code}`n" http://0.0.0.0:8282/health +(Invoke-WebRequest -UseBasicParsing http://0.0.0.0:8282/health).StatusCode +``` + +You should see `200`. + +### Step 3: Tell Codex about the proxy + +Open `~/.codex/config.toml` (on Windows, `%USERPROFILE%\.codex\config.toml`; create it if it does not exist) and paste the following. The `model_provider` and `model_providers` keys only take effect in this user-level file. + +```toml +model = "gpt-5.4" # the DIAL deployment id you set in BACKEND_URL above +model_provider = "dial" +disable_response_storage = true # DIAL doesn't store responses, so this must be on + +[model_providers.dial] +name = "DIAL (via responses-proxy)" +base_url = "http://0.0.0.0:8282/v1" # the proxy; Codex appends /responses +wire_api = "responses" # the only valid value — Codex's old "chat" wire was removed +env_key = "DIAL_API_KEY" +env_http_headers = { "Api-Key" = "DIAL_API_KEY" } # forwarded through the proxy to DIAL +requires_openai_auth = false # don't enforce the sk- prefix check +``` + +### Step 4: Set your API key + +Bash or Zsh: + +```bash +export DIAL_API_KEY="" +``` + +PowerShell: + +```powershell +$env:DIAL_API_KEY = "" +``` + +### Step 5: Check the wiring + +Before running a real prompt, ask Codex to inspect its own setup: + +```bash +codex doctor +``` + +Your config loads cleanly and a row appears for the `dial` provider — `config.toml parse ok`, `auth ✓` with `provider auth env var DIAL_API_KEY (present)`, and `wire API responses`. The model line names your deployment, for example `gpt-5.4 · dial`. + +### Step 6: Run Codex + +```bash +codex exec "Reply with exactly: PONG" +``` + +You see `PONG` printed back, routed Codex → proxy → DIAL. Run plain `codex` for the interactive session you will use day to day. + +## Additional Information + +DIAL does not store responses or support `previous_response_id`, which is why `disable_response_storage = true` is required on both paths — without it, Codex breaks after the first turn. + +- Which path you need depends on the deployment. Re-run the Step 1 check for any new deployment — the flag can differ even between versions of the same model family. +- Codex sends the key as an `Authorization: Bearer` token; the `env_http_headers` line is what makes it also send the `Api-Key` header that DIAL authenticates on. On the proxy path, the proxy forwards it. +- On the proxy path, mind the proxy's own limits: only `function` tools are forwarded, file inputs must be inlined, and no session state is kept. + +> - Refer to [Connect Claude Code to DIAL](/docs/tutorials/1.developers/2.agentic-tools/5.claude-code.md) for another command-line agent, with no proxy needed. +> - Refer to the [Agentic Tools overview](/docs/tutorials/1.developers/2.agentic-tools/0.overview.md) for shared prerequisites and the other tools. +> - Refer to the [Unified API reference](https://dialx.ai/dial_api) for the API DIAL exposes. diff --git a/docs/tutorials/1.developers/2.agentic-tools/2.github-copilot.md b/docs/tutorials/1.developers/2.agentic-tools/2.github-copilot.md new file mode 100644 index 000000000..955c3631a --- /dev/null +++ b/docs/tutorials/1.developers/2.agentic-tools/2.github-copilot.md @@ -0,0 +1,55 @@ +# Connect GitHub Copilot to DIAL + +## Introduction + +From this tutorial, you will learn how to add your DIAL deployments to the GitHub Copilot model picker in VS Code, then chat with one of them. Turns you send through the picker run on DIAL, with DIAL auth, roles, quotas, and cost tracking applied. By the end, you pick a DIAL model in Copilot Chat and get a reply streamed back from your DIAL deployment. + +## Prerequisites + +- A DIAL host and API key. Refer to [Prerequisites](/docs/tutorials/1.developers/2.agentic-tools/0.overview.md#prerequisites). +- VS Code **1.110** or newer. +- The GitHub Copilot extension, installed and signed in. + +**Note**: The DIAL Chat Model Provider used below is a community extension, not published by GitHub, Microsoft, or EPAM. Review its source and install it at your own discretion. + +## Step 1: Install the DIAL extension + +Download the **DIAL Chat Model Provider** `.vsix` from either source: + +- [Open VSX](https://open-vsx.org/extension/sergey-zinchenko/dial-chat-model-provider) +- [GitHub releases](https://github.com/sergey-zinchenko/DialChatModelProvider/releases) + +In VS Code, open the Command Palette (`Ctrl+Shift+P` / `Cmd+Shift+P`), run **`Extensions: Install from VSIX…`**, and select the file you downloaded. When prompted, reload VS Code. **DIAL Chat Model Provider** now appears in the Extensions view, and new `DIAL:` commands are available in the Command Palette. + +## Step 2: Point at DIAL and sign in + +Open the Command Palette and run **`DIAL: Open Settings`**. Set: + +| Setting | Value | +| ----------------- | ------------------- | +| `dial.serverUrl` | `https://` | +| `dial.authMethod` | `openid` or `apikey` | + +Then run **`DIAL: Login`**: + +- `openid` — VS Code opens your browser, you sign in, and the tokens are stored in your OS keychain. +- `apikey` — run **`DIAL: Set API Key`** first, or paste the key when prompted. The key is sent as DIAL's `Api-Key` header on every request. + +## Step 3: Pick a DIAL model in Copilot + +Open Copilot Chat, open the model picker, and choose a deployment listed under **DIAL**. The deployments your DIAL role can access appear automatically, and vision-capable models are marked. + +Send a message — for example, *"What model are you?"* You get a reply streamed back from your DIAL deployment. + +## Additional Information + +- Only turns that go through the model picker (and other `vscode.lm.*` clients) reach DIAL. Inline ghost-text completions keep using GitHub's backend. +- The extension uses DIAL's Chat Completions surface. Deployments exposed only over the Responses API are not reachable this way. +- A deployment works correctly through the extension only when its DIAL model configuration explicitly declares token limits and a tokenizer. Deployments missing either may fail or misbehave in the picker. +- Copilot's prompt-cache markers (`cache_control`) are not forwarded to DIAL, so Bedrock-style prompt caching is not activated from Copilot turns. +- Auto-compaction does not work with this setup. When a conversation grows past the model's context window, Copilot will not summarize it down automatically — start a new chat instead. +- For `openid`, your DIAL admins must allow the extension's OIDC client registration and its redirect URI `http://127.0.0.1:47821/oauth-callback`. + +> - Refer to [Connect OpenCode to DIAL](/docs/tutorials/1.developers/2.agentic-tools/4.opencode.md) for a terminal agent that also uses Chat Completions. +> - Refer to the [Agentic Tools overview](/docs/tutorials/1.developers/2.agentic-tools/0.overview.md) for shared prerequisites and the other tools. +> - Refer to [DIAL Chat Model Provider on Open VSX](https://open-vsx.org/extension/sergey-zinchenko/dial-chat-model-provider) for the extension's current feature list and settings reference. diff --git a/docs/tutorials/1.developers/2.agentic-tools/3.open-claw.md b/docs/tutorials/1.developers/2.agentic-tools/3.open-claw.md new file mode 100644 index 000000000..5d16534c2 --- /dev/null +++ b/docs/tutorials/1.developers/2.agentic-tools/3.open-claw.md @@ -0,0 +1,84 @@ +# Connect Open Claw to DIAL + +## Introduction + +From this tutorial, you will learn how to add DIAL as a model provider in Open Claw, the self-hosted agent gateway, set it as the default, and run one agent turn. Every agent turn is then routed to your DIAL deployment, with DIAL roles, quotas, audit, and cost tracking applied. By the end, one agent turn runs against your DIAL deployment and names the model back to you. + +## Prerequisites + +- A DIAL host and API key. Refer to [Prerequisites](/docs/tutorials/1.developers/2.agentic-tools/0.overview.md#prerequisites). +- Node.js **22** or newer. +- [Open Claw](https://github.com/openclaw/openclaw) installed. + +## Step 1: Store your DIAL key + +Add it to `~/.openclaw/.env` (on Windows, `%USERPROFILE%\.openclaw\.env`): + +```bash +DIAL_API_KEY="" +``` + +## Step 2: Add a DIAL provider + +Edit `~/.openclaw/openclaw.json`. The DIAL deployment id is part of `baseUrl`, so you use one provider block per deployment you want to expose. + +```json +{ + "models": { + "mode": "merge", + "providers": { + "dial": { + "baseUrl": "https:///openai/deployments/gpt-5.4-2026-03-05", + "apiKey": "${DIAL_API_KEY}", + "headers": { "Api-Key": "${DIAL_API_KEY}" }, + "api": "openai-completions", + "models": [ + { + "id": "gpt-5.4", + "name": "GPT-5.4 (DIAL)", + "reasoning": false, + "input": ["text"], + "contextWindow": 128000, + "maxTokens": 4096 + } + ] + } + } + }, + "agents": { + "defaults": { + "model": { "primary": "dial/gpt-5.4" }, + "models": { "dial/gpt-5.4": {} } + } + } +} +``` + +## Step 3: Set the active model + +```bash +openclaw models set dial/gpt-5.4 +``` + +You see `Default model: dial/gpt-5.4`. To confirm the key was picked up, run `openclaw models status` and check that the `dial` provider is listed with auth present. + +## Step 4: Run one agent turn + +```bash +openclaw agent --local --agent main -m "Reply in one short sentence: what model are you?" +``` + +You see a reply naming your DIAL model — for example, *"I am the dial/gpt-5.4 model."* — followed by `stopReason=stop`. The `--local` flag runs the agent in-process, which is the quickest way to confirm the connection. For everyday use, start the gateway once with `openclaw gateway run` and drop the `--local` flag. + +## Additional Information + +- DIAL has no single `/v1/chat/completions` router: each deployment needs its own provider block whose `baseUrl` ends in that deployment id. To add a second model, copy the block (for example, as `dial-claude`) and reference it as `dial-claude/`. +- The `openai-completions` wire uses Chat Completions. To reach a Responses-only deployment, set `"api": "openai-responses"` and point `baseUrl` at `https:///openai/v1` instead. +- Open Claw also sends `Authorization: Bearer` from `apiKey`; the explicit `headers.Api-Key` entry above is what DIAL authenticates on. +- Tool calling, reasoning, and attachments work only when the DIAL deployment advertises those capabilities. +- On Azure-backed GPT-5.x deployments, expect the two settings from [Azure-backed deployment settings](/docs/tutorials/1.developers/2.agentic-tools/0.overview.md#azure-backed-deployment-settings): an `api-version` on the request URL and `max_completion_tokens` in place of `max_tokens`. Non-GPT-5.x deployments typically need neither. +- This wires only the model backend. Messaging channels still need their own Open Claw channel config and secrets. + +> - Refer to [Connect OpenCode to DIAL](/docs/tutorials/1.developers/2.agentic-tools/4.opencode.md) for another terminal agent that uses Chat Completions. +> - Refer to the [Agentic Tools overview](/docs/tutorials/1.developers/2.agentic-tools/0.overview.md) for shared prerequisites and the other tools. +> - Refer to the [Unified API reference](https://dialx.ai/dial_api) for the API DIAL exposes. diff --git a/docs/tutorials/1.developers/2.agentic-tools/4.opencode.md b/docs/tutorials/1.developers/2.agentic-tools/4.opencode.md new file mode 100644 index 000000000..25bad9654 --- /dev/null +++ b/docs/tutorials/1.developers/2.agentic-tools/4.opencode.md @@ -0,0 +1,73 @@ +# Connect OpenCode to DIAL + +## Introduction + +From this tutorial, you will learn how to register DIAL as a custom provider in OpenCode, the terminal coding agent, then run a prompt against it. OpenCode speaks Chat Completions, so it talks to DIAL directly — no proxy needed. Every turn then runs on your DIAL deployment. By the end, `opencode run` sends a prompt to your DIAL deployment and prints the reply. + +## Prerequisites + +- A DIAL host and API key. Refer to [Prerequisites](/docs/tutorials/1.developers/2.agentic-tools/0.overview.md#prerequisites). +- OpenCode installed — `npm i -g opencode-ai`, or the installer at [opencode.ai](https://opencode.ai). + +## Step 1: Set your DIAL key + +Bash or Zsh: + +```bash +export DIAL_API_KEY="" +``` + +PowerShell: + +```powershell +$env:DIAL_API_KEY = "" +``` + +## Step 2: Add DIAL as a provider + +Create `opencode.json` in your project directory (or globally at `~/.config/opencode/opencode.json`; on Windows, `%USERPROFILE%\.config\opencode\opencode.json`). DIAL's deployment id is part of `baseURL`, so add one provider/model entry per deployment. + +```json +{ + "$schema": "https://opencode.ai/config.json", + "provider": { + "dial": { + "npm": "@ai-sdk/openai-compatible", + "name": "DIAL", + "options": { + "baseURL": "https:///openai/deployments/gpt-5.5-2026-04-24", + "apiKey": "{env:DIAL_API_KEY}" + }, + "models": { + "gpt-5.5-2026-04-24": { + "name": "GPT-5.5 (DIAL)", + "limit": { "context": 200000, "output": 128000 } + } + } + } + } +} +``` + +When you give a model a `limit` block, OpenCode requires both `context` and `output`. Set `output` to the deployment's maximum completion tokens — `128000` for `gpt-5.5-2026-04-24`. DIAL rejects a turn that asks for more than the ceiling with `max_tokens is too large`, so never set it higher than the deployment allows. + +**Note**: Pick your deployment with the wire in mind. `@ai-sdk/openai-compatible` sends a plain `max_tokens` and no `api-version`, which `gpt-5.5-2026-04-24` accepts. Some other GPT-5.x deployments reject a plain `max_tokens` (wanting `max_completion_tokens`) or require an `api-version`, and OpenCode supplies neither — refer to [Azure-backed deployment settings](/docs/tutorials/1.developers/2.agentic-tools/0.overview.md#azure-backed-deployment-settings). DIAL accepts the key as a Bearer token via `apiKey`; if your DIAL only accepts the `Api-Key` header, add `"headers": { "Api-Key": "{env:DIAL_API_KEY}" }` under `options`. + +## Step 3: Run OpenCode + +```bash +opencode run --model dial/gpt-5.5-2026-04-24 "Reply with exactly: PONG" +``` + +You see `PONG`. Launch plain `opencode` for the interactive TUI and pick the DIAL model from the model switcher. + +## Additional Information + +- OpenCode uses Chat Completions, so it reaches DIAL directly — no proxy needed, unlike Codex. Deployments exposed only over the Responses API are not reachable this way. +- When a model has a `limit` block, OpenCode requires `limit.output`. Set it to the deployment's max completion tokens; DIAL rejects a value above that ceiling with `max_tokens is too large`. +- Add one provider entry per DIAL deployment — the deployment id lives in `baseURL`. +- Tool calling and vision work only when the DIAL deployment advertises those capabilities. + +> - Refer to [Connect Claude Code to DIAL](/docs/tutorials/1.developers/2.agentic-tools/5.claude-code.md) for a command-line agent that uses the native Anthropic Messages API. +> - Refer to the [Agentic Tools overview](/docs/tutorials/1.developers/2.agentic-tools/0.overview.md) for shared prerequisites and the other tools. +> - Refer to [OpenCode custom providers](https://opencode.ai/docs/providers) for the provider configuration reference. diff --git a/docs/tutorials/1.developers/2.agentic-tools/5.claude-code.md b/docs/tutorials/1.developers/2.agentic-tools/5.claude-code.md new file mode 100644 index 000000000..5456e6d9d --- /dev/null +++ b/docs/tutorials/1.developers/2.agentic-tools/5.claude-code.md @@ -0,0 +1,86 @@ +# Connect Claude Code to DIAL + +## Introduction + +From this tutorial, you will learn how to point Claude Code, Anthropic's command-line coding agent, at DIAL and watch a DIAL-hosted model reply. Claude Code speaks the native Anthropic Messages API, and DIAL exposes that same API at `/anthropic` — so Claude Code talks to DIAL directly, with no proxy and no extra config file. You set a handful of environment variables, then run a prompt. By the end, `claude -p` sends a prompt and prints the reply, routed through your DIAL deployment with DIAL's roles, quotas, and cost tracking applied. + +## Prerequisites + +- A DIAL host and API key. Refer to [Prerequisites](/docs/tutorials/1.developers/2.agentic-tools/0.overview.md#prerequisites). +- Claude Code installed — `npm i -g @anthropic-ai/claude-code`. + +## Step 1: Point Claude Code at DIAL + +Set the following environment variables. + +Bash or Zsh: + +```bash +export ANTHROPIC_BASE_URL="https:///anthropic" +export ANTHROPIC_API_KEY="" # keeps Claude Code out of its own login flow +export ANTHROPIC_CUSTOM_HEADERS="Api-Key: " # the header DIAL actually authenticates on +export ANTHROPIC_DEFAULT_OPUS_MODEL="anthropic.claude-opus-4-8" +export ANTHROPIC_DEFAULT_SONNET_MODEL="anthropic.claude-sonnet-4-6" +export ANTHROPIC_DEFAULT_HAIKU_MODEL="anthropic.claude-haiku-4-5-20251001-v1:0" +unset ANTHROPIC_AUTH_TOKEN # don't fall back to a personal token +export CLAUDE_CONFIG_DIR="/tmp/claude-ccr" # optional — see note below +``` + +PowerShell: + +```powershell +$env:ANTHROPIC_BASE_URL = "https:///anthropic" +$env:ANTHROPIC_API_KEY = "" +$env:ANTHROPIC_CUSTOM_HEADERS = "Api-Key: " +$env:ANTHROPIC_DEFAULT_OPUS_MODEL = "anthropic.claude-opus-4-8" +$env:ANTHROPIC_DEFAULT_SONNET_MODEL = "anthropic.claude-sonnet-4-6" +$env:ANTHROPIC_DEFAULT_HAIKU_MODEL = "anthropic.claude-haiku-4-5-20251001-v1:0" +Remove-Item Env:\ANTHROPIC_AUTH_TOKEN -ErrorAction SilentlyContinue +$env:CLAUDE_CONFIG_DIR = "$env:TEMP\claude-ccr" # optional — see note below +``` + +These values point Claude Code at DIAL's `/anthropic` surface, authenticate with your DIAL key, and map Claude Code's three model tiers (Opus, Sonnet, Haiku) to DIAL deployment ids. Use the exact deployment id for each — Claude Code sends it to DIAL unchanged. + +**Warning**: `ANTHROPIC_CUSTOM_HEADERS` is a full header line, not the bare key. Keep the `Api-Key: ` header name and replace only ``, so the value reads `Api-Key: your-real-key`. If you paste the bare key without the `Api-Key: ` prefix, DIAL sees no valid auth header and rejects the request with `401 "At least API-KEY or Authorization header must be provided"`. `ANTHROPIC_API_KEY`, directly above it, is the bare key. + +**Note**: `CLAUDE_CONFIG_DIR` is optional and only for trying this out. It points Claude Code at a throwaway config directory, so this experiment does not disturb the login of a Claude Code you may already use. For a permanent DIAL setup, leave it unset. + +## Step 2: Run Claude Code + +```bash +claude -p "Reply with exactly: PONG" +``` + +You see `PONG` printed back, answered by your DIAL deployment with no proxy in between. Run plain `claude` for the interactive session you will use day to day. + +## Make it permanent with `settings.json` + +Instead of re-exporting every shell, put the same values in Claude Code's settings file — `~/.claude/settings.json` (or `$CLAUDE_CONFIG_DIR/settings.json`; on Windows, `%USERPROFILE%\.claude\settings.json`). The JSON is identical on every platform; only the path differs: + +```json +{ + "env": { + "ANTHROPIC_BASE_URL": "https:///anthropic", + "ANTHROPIC_API_KEY": "", + "ANTHROPIC_CUSTOM_HEADERS": "Api-Key: ", + "ANTHROPIC_DEFAULT_OPUS_MODEL": "anthropic.claude-opus-4-8", + "ANTHROPIC_DEFAULT_SONNET_MODEL": "anthropic.claude-sonnet-4-6", + "ANTHROPIC_DEFAULT_HAIKU_MODEL": "anthropic.claude-haiku-4-5-20251001-v1:0" + } +} +``` + +For this permanent form you typically do not set `CLAUDE_CONFIG_DIR` — that was only to isolate the trial above. + +## Additional Information + +No proxy is needed: DIAL's `/anthropic` surface speaks the native Anthropic Messages API, so Claude Code reaches it directly, unlike Codex. To check that a host exposes it, `POST` to `https:///anthropic/v1/messages` — a configured host returns `200`, one without the surface returns `404`. + +- Why two key settings: DIAL does not accept the `x-api-key` header that Claude Code normally sends from `ANTHROPIC_API_KEY`; it authenticates on the `Api-Key` header (or an `Authorization: Bearer` token). That is why you set `ANTHROPIC_CUSTOM_HEADERS="Api-Key: …"`. `ANTHROPIC_API_KEY` stays set only so Claude Code treats itself as logged in and skips its own sign-in flow. +- Use exact deployment ids, and set all three tiers. Claude Code routes small background tasks to the Haiku tier, so a missing or wrong `ANTHROPIC_DEFAULT_HAIKU_MODEL` fails those turns. Haiku's full id is `anthropic.claude-haiku-4-5-20251001-v1:0` — a shortened form is rejected as an unknown deployment. +- Tool calling and vision work only when the chosen DIAL deployment advertises those capabilities. +- This tutorial was verified against DIAL **v0.46**. Other DIAL releases may not expose `/anthropic`; use the 200/404 check above to confirm yours does. + +> - Refer to [Connect Codex to DIAL](/docs/tutorials/1.developers/2.agentic-tools/1.codex.md) for a command-line agent that may need a translating proxy. +> - Refer to the [Agentic Tools overview](/docs/tutorials/1.developers/2.agentic-tools/0.overview.md) for shared prerequisites and the other tools. +> - Refer to the [Unified API reference](https://dialx.ai/dial_api) for the API DIAL exposes. diff --git a/sidebars.js b/sidebars.js index 31085d59a..e116ff494 100644 --- a/sidebars.js +++ b/sidebars.js @@ -240,6 +240,42 @@ const sidebars = { }, ], }, + { + type: 'category', + label: 'Agentic Tools', + items: [ + { + type: 'doc', + id: 'tutorials/developers/agentic-tools/overview', + label: 'Overview', + }, + { + type: 'doc', + id: 'tutorials/developers/agentic-tools/codex', + label: 'Connect Codex to DIAL', + }, + { + type: 'doc', + id: 'tutorials/developers/agentic-tools/github-copilot', + label: 'Connect GitHub Copilot to DIAL', + }, + { + type: 'doc', + id: 'tutorials/developers/agentic-tools/open-claw', + label: 'Connect Open Claw to DIAL', + }, + { + type: 'doc', + id: 'tutorials/developers/agentic-tools/opencode', + label: 'Connect OpenCode to DIAL', + }, + { + type: 'doc', + id: 'tutorials/developers/agentic-tools/claude-code', + label: 'Connect Claude Code to DIAL', + }, + ], + }, { type: 'category', label: 'Chat',