Connect Coding Agents to WaveSpeedAI LLM

Use this guide when you want a coding assistant or developer agent to run through WaveSpeedAI LLM using an OpenAI-compatible endpoint. It covers Claude Code, OpenAI Codex, OpenClaw, and other custom model clients.

Recommended Mental Model

Most coding tools are built around one provider. WaveSpeedAI LLM is usually easiest to test when the tool supports an OpenAI-compatible custom provider:

Coding tool
  -> Custom OpenAI-compatible provider
  -> https://llm.wavespeed.ai/v1
  -> Selected WaveSpeedAI model

Quick Setup with the CLI

The WaveSpeed CLI configures a supported agent and checks that it works. If you have not installed it yet:

# 1. Install the CLI (needs Node.js 18 or later; see the CLI page for other options).
npm install -g @wavespeed/cli
 
# 2. Sign in with your WaveSpeed account.
wavespeed login

No Node.js? The CLI guide has a standalone download. Then configure your agent:

# codex, claude, gemini, opencode, openclaw, hermes, kilo, qwen, miniagent,
# crush, droid, aider, continue, goose, dsh, or cline (CLI)
wavespeed setup codex
 
# Preview first, choose a model, or undo later.
wavespeed setup codex --dry-run
wavespeed setup codex --model <model_id>
wavespeed setup codex --undo

The CLI only adds or changes the WaveSpeed entries, keeps a .wavespeed.bak copy of the original file, and sends one streamed test request before reporting success. Agents that read the key from an environment variable need WAVESPEED_API_KEY set in the shell that starts them. See WaveSpeed CLI for the full list and details. The sections below show the manual configuration.

Claude Code, OpenAI Codex, OpenClaw, or Custom OpenAI?

Universal OpenAI-Compatible Settings

Verify the Backend First

Before configuring an agent, confirm your key and model work with a small API call.

curl --fail-with-body --connect-timeout 10 --max-time 120 \
  https://llm.wavespeed.ai/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${WAVESPEED_API_KEY}" \
  -d '{
    "model": "deepseek/deepseek-v4.1-flash-1017",
    "messages": [
      {
        "role": "user",
        "content": "Reply with one sentence confirming you are ready for coding tasks."
      }
    ]
  }'

Verify Current Availability

Model availability changes over time. Confirm the model ID in the LLM Playground, then make the small request above before configuring an agent.

After the endpoint check passes, run a read-only prompt in your coding tool to confirm the selected provider, model, and project permissions before asking it to edit files.

For long coding sessions, keep project instructions, tool definitions, and repository context stable so the selected upstream model has a better chance of reusing cached prompt prefixes. See Prompt Caching for HTTP examples and cache-hit troubleshooting.

Before a Long Coding Session

Run a small prompt first:

Reply with exactly READY. Do not use tools.

This confirms that the client can complete a request before it starts reading or editing a large codebase. Do not rely on a model stating its own identity: a proxied model can give an incorrect model name. Verify the configured model ID in the client configuration or request logs instead.

Model Selection Tips

Claude Code

Claude Code uses Anthropic-style client settings. WaveSpeedAI exposes the compatible POST /v1/messages endpoint directly, so no additional gateway is required.

Claude Code
  -> https://llm.wavespeed.ai/v1/messages

Set the WaveSpeedAI values in the shell that launches Claude Code:

export ANTHROPIC_BASE_URL="https://llm.wavespeed.ai"
export ANTHROPIC_AUTH_TOKEN="YOUR_WAVESPEED_API_KEY"
export ANTHROPIC_MODEL="deepseek/deepseek-v4.1-flash-1017"
claude

Windows PowerShell:

$env:ANTHROPIC_BASE_URL = "https://llm.wavespeed.ai"
$env:ANTHROPIC_AUTH_TOKEN = "YOUR_WAVESPEED_API_KEY"
$env:ANTHROPIC_MODEL = "deepseek/deepseek-v4.1-flash-1017"
claude

These $env: values apply only to the current PowerShell session. Run claude in the same window. If you save them as Windows user environment variables instead, completely exit Claude Code and open a new terminal before starting it again.

If your Claude Code setup loads environment variables from ~/.claude/settings.json, add the WaveSpeedAI values under env.

{
  "env": {
    "DISABLE_AUTOUPDATER": "1",
    "ANTHROPIC_BASE_URL": "https://llm.wavespeed.ai",
    "ANTHROPIC_AUTH_TOKEN": "YOUR_WAVESPEED_API_KEY",
    "ANTHROPIC_MODEL": "deepseek/deepseek-v4.1-flash-1017"
  }
}

Set ANTHROPIC_MODEL to the model name accepted by your Claude Code runtime. Use the WaveSpeedAI model ID when your setup passes model names through, or use the local alias that maps to a WaveSpeedAI model upstream.

OpenAI Codex

For Codex clients that support custom OpenAI-compatible providers, configure WaveSpeedAI as the provider and use a tested WaveSpeedAI model ID.

Codex reads custom provider settings from the user-level configuration file. Provider settings in a project’s .codex/config.toml are ignored.

Create the .codex directory and config.toml file if they do not exist, then add:

model = "deepseek/deepseek-v4.1-flash-1017"
model_provider = "wavespeed"
 
[model_providers.wavespeed]
name = "WaveSpeedAI LLM"
base_url = "https://llm.wavespeed.ai/v1"
env_key = "WAVESPEED_API_KEY"
wire_api = "responses"

wire_api = "responses" is required because Codex custom providers use the Responses protocol. A Chat Completions request succeeding by itself does not prove that Codex streaming and tool calls are compatible.

macOS and Linux

Set the key and launch Codex from the same terminal:

export WAVESPEED_API_KEY="YOUR_WAVESPEED_API_KEY"
codex

Windows PowerShell

For a one-session test, set the key and launch Codex from the same PowerShell window:

$env:WAVESPEED_API_KEY = "YOUR_WAVESPEED_API_KEY"
codex

$env:WAVESPEED_API_KEY only applies to that PowerShell process and programs launched from it. Closing the window removes the value. Starting Codex separately from the Start menu or an already-running desktop app may not inherit it.

To save the key as a user environment variable for future PowerShell, Command Prompt, and desktop sessions:

[Environment]::SetEnvironmentVariable(
  "WAVESPEED_API_KEY",
  "YOUR_WAVESPEED_API_KEY",
  "User"
)

After saving it, completely exit all Codex windows and terminals, open a new session, and start Codex again. Do not put the API key directly in config.toml, source control, screenshots, or support messages.

Verify the setup

Check the installed version and configuration before opening a large repository:

codex --version
codex doctor

In the doctor output, confirm that the configuration loads and that there is no active model provider auth env var is missing error. Then make a small read-only request:

codex exec --ephemeral --sandbox read-only "Reply with exactly READY. Do not use tools."

This configuration uses WaveSpeedAI’s POST /v1/responses route. The first request can still be larger than the visible prompt because Codex sends its operating instructions and tool definitions to the model.

Codex may warn that the WaveSpeedAI model is unknown and that it is using fallback model metadata. A simple request can still work, but fallback context-window or capability metadata can affect longer sessions. Record codex --version, the warning, and the failing prompt when contacting support.

After configuring Codex, start with a read-only prompt such as:

Summarize this repository in three bullets. Do not edit files.

OpenClaw

For OpenClaw setups with custom OpenAI-compatible providers, add WaveSpeedAI as a provider and test a small prompt first.

{
  agents: {
    defaults: {
      model: { primary: "wavespeed/deepseek/deepseek-v4.1-flash-1017" },
    },
  },
  models: {
    mode: "merge",
    providers: {
      wavespeed: {
        baseUrl: "https://llm.wavespeed.ai/v1",
        apiKey: "${WAVESPEED_API_KEY}",
        api: "openai-completions",
        models: [
          {
            id: "deepseek/deepseek-v4.1-flash-1017",
            name: "DeepSeek V4 Flash via WaveSpeedAI",
            input: ["text"],
          }
        ],
      },
    },
  },
}

If your OpenClaw version uses a different provider config shape, keep the same base URL, API key, and model IDs while adapting the surrounding fields to that version.

After selecting the provider in OpenClaw, start with a read-only prompt before asking it to modify a project.

Codex Desktop App

The Codex desktop app reads the same ~/.codex/config.toml as the Codex CLI (%USERPROFILE%\.codex\config.toml on Windows), so the configuration in the OpenAI Codex section, or wavespeed setup codex, applies to both. Restart the desktop app after changing the file. Codex ignores model_provider settings in a project’s .codex/config.toml, so keep them in the user-level file. Custom models may show a generic label in the desktop model picker.

Claude Desktop

Claude Desktop can send its requests to a gateway that implements the Anthropic Messages API instead of Anthropic. This is the app’s third-party inference mode, and it is configured in the app, not with wavespeed setup.

1. Install Claude Desktop and do not sign in. Open Help → Troubleshooting → Enable Developer Mode, then Developer → Configure Third-Party Inference….
2. Set the provider to Gateway and fill in:

3. Click Apply Changes, then Save & Restart.

WaveSpeedAI serves POST /v1/messages with streaming and tool use. Claude Desktop only auto-discovers models whose IDs look like Claude models, so list the models you want in inferenceModels yourself. The app reads its configuration at launch, so fully quit and reopen it after any change. Third-party inference is an Anthropic feature with its own requirements (for example, Cowork needs macOS 14 or Windows 10 build 19041 or later); see Anthropic’s Claude Desktop documentation. This follows Anthropic’s gateway requirements; send one short chat first to confirm that your model works in the app.

GitHub Copilot CLI

Copilot CLI can use your own provider with environment variables only; it has no configuration file for this and needs no GitHub login in this mode.

export COPILOT_PROVIDER_BASE_URL="https://llm.wavespeed.ai/v1"
export COPILOT_PROVIDER_API_KEY="YOUR_WAVESPEED_API_KEY"
export COPILOT_MODEL="deepseek/deepseek-v4.1-flash-1017"
copilot -p "Reply with exactly READY. Do not use tools."

The default provider type is OpenAI-compatible Chat Completions, which matches the WaveSpeedAI endpoint. Copilot logs a harmless warning that the model is not in its built-in catalog; COPILOT_PROVIDER_MAX_PROMPT_TOKENS silences it.

Gemini CLI

Gemini CLI talks to the Gemini-compatible endpoint (/v1beta) of the gateway and sends your key in the x-goog-api-key header, which the gateway accepts on that route.

~/.gemini/.env:

GOOGLE_GEMINI_BASE_URL=https://llm.wavespeed.ai
GEMINI_API_KEY=wsk_live_...

~/.gemini/settings.json:

{
  "security": { "auth": { "selectedType": "gemini-api-key" } },
  "model": { "name": "deepseek/deepseek-v4.1-flash-1017" }
}

Gemini CLI reads ~/.gemini/.env only in folders it trusts. Accept the trust prompt on first start, or set GEMINI_CLI_TRUST_WORKSPACE=true for scripts and CI. wavespeed setup gemini writes both files for you.

Troubleshooting