07/Integrations

Client Setups

Step-by-step setup for popular IDEs and tools.


In the examples below, replace <gateway-host> with your address and <token> with your Portway JWT token.

#Claude Code

Anthropic CLI tool with custom base URL support.

  1. 1Set environment variables before launching; ANTHROPIC_BASE_URL must end with /claude/.
  2. 2ANTHROPIC_AUTH_TOKEN and ANTHROPIC_API_KEY should both contain your JWT token.
  3. 3Pin the Opus/Sonnet/Haiku and subagent tiers to mapped model names.
shell
export ANTHROPIC_BASE_URL=https://<gateway-host>/claude/
export ANTHROPIC_AUTH_TOKEN=<token>
export ANTHROPIC_API_KEY=<token>
export CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1
export ANTHROPIC_DEFAULT_OPUS_MODEL=<mapped-model>
export ANTHROPIC_DEFAULT_SONNET_MODEL=<mapped-model>
export ANTHROPIC_DEFAULT_HAIKU_MODEL=<mapped-model>
export CLAUDE_CODE_SUBAGENT_MODEL=<mapped-model>
claude
Subagents and background tasks use Haiku/subagent variables — if unset, requests may fail with 404. ANTHROPIC_SMALL_FAST_MODEL is deprecated; use ANTHROPIC_DEFAULT_HAIKU_MODEL.

#Claude Desktop

Claude Desktop in third-party inference mode — routes chat through Portway as an Anthropic-compatible gateway.

  1. 1Developer Mode: Help → Troubleshooting → Enable Developer Mode.
  2. 2Developer → Configure third-party inference; provider = Gateway.
  3. 3Under Custom inference headers add X-Maestro-Client: claude-desktop (required).
  4. 4Pick models from discovery using the opaque id (claude-maestro-…).
config
Gateway base URL:  https://<gateway-host>/claude
Gateway API key:   <token>   (auth scheme: bearer)

inferenceCustomHeaders:
{ "X-Maestro-Client": "claude-desktop" }
Without the X-Maestro-Client header, claude-maestro-{hash} ids are not resolved (404). Discovery returns opaque ids; display_name shows the real catalog name.

#OpenClaw

Universal AI IDE plugin reading provider config from ~/.openclaw/openclaw.json.

~/.openclaw/openclaw.json
{
  "models": {
    "mode": "merge",
    "providers": {
      "portway": {
        "baseUrl": "https://<gateway-host>/openclaw",
        "apiKey": "<token>",
        "api": "openai-completions",
        "models": [{ "id": "<mapped-model>", "name": "<mapped-model>" }]
      }
    }
  }
}

#Codex (OpenAI)

Via the Desktop App launcher script (recommended) or the VS Code extension / CLI with env vars.

shell
# Desktop App — recommended (do NOT put /v1 in MAESTRO_URL)
MAESTRO_URL=https://<gateway-host> MAESTRO_TOKEN=<token> \
  MAESTRO_MODEL=<mapped-model> ./scripts/codex-maestro

# VS Code Extension / CLI
export OPENAI_BASE_URL="https://<gateway-host>/v1"
export OPENAI_API_KEY="<token>"
codex
The Desktop App uses the Responses API; Portway converts to Chat Completions on the fly and streams back Codex-compatible SSE. In-app model switching is unreliable with custom providers — use a model group.

#Cursor IDE

Editor using a custom OpenAI base URL. Also supports the Cursor AI provider node directly.

  1. 1Cursor Pro is required for custom API keys; Portway must be publicly reachable (VPS/tunnel).
  2. 2Settings → Models → OpenAI → Override Base URL.
Cursor
OpenAI API Key:            <token>
Override OpenAI Base URL:  https://<gateway-host>/cursor

#Grafana Assistant

Official Grafana plugin for AI-powered dashboards (Grafana ≥ 13.0.0).

Grafana
Backend URL:  https://<gateway-host>/grafana/assistant
API Token:    <token>

#VS Code

Claude Code, Codex and Kilo Code extensions are supported. Most work via env vars or the /v1 base URL.

settings.json (Codex/Kilo)
{
  "terminal.integrated.env.osx": {
    "OPENAI_BASE_URL": "https://<gateway-host>/v1",
    "OPENAI_API_KEY": "<token>"
  }
}
For dynamic model switching, select a Portway model group as the default model — swap members from the admin panel.

#Open WebUI

The chat UI bundled with Portway; open it from the Open WebUI link in the sidebar. It runs under /webui/ on the same address as the panel, with no extra port or domain.

  1. 1Open WebUI talks to Maestro over /v1 with the openwebui service user's token.
  2. 2Each request forwards the signed-in user's email in the trusted-client header (X-OpenWebUI-User-Email); Portway attributes it to the user with that email.
  3. 3Create a Portway user with the same email for every Open WebUI user; without a match the request gets 403.
  4. 4make openwebui syncs the service user, its token and the Open WebUI connection settings (make setup runs it for you).
shell
make openwebui
Portway admin accounts are never mapped — requests carrying an admin's email are rejected with 403. Use a separate non-admin Portway user for the Open WebUI admin.