Skip to content

getting-started.md

Latest commit

 

History

History
103 lines (70 loc) · 3.56 KB

getting-started.md

File metadata and controls

103 lines (70 loc) · 3.56 KB
Raw

Getting Started

1. Install

The fastest path is npm:

npm install -g clipal

You can also download the right binary from Releases and place it on your PATH. Latest stable release: GitHub Releases latest

Platform-specific notes:

Verify the version:

clipal --version

2. Start Clipal

clipal

Common startup overrides:

clipal --config-dir /path/to/config
clipal --listen-addr 127.0.0.1
clipal --port 3333
clipal --log-level debug

By default, Clipal starts both:

  • the local proxy
  • the Web management UI at http://127.0.0.1:3333/

3. Configure Providers via Web UI

Open the Web UI in your browser and add your providers there — no config files needed:

http://127.0.0.1:3333/

From the Providers page you can:

  • Add, edit, or remove API-key providers (Claude, OpenAI, Gemini, and any OpenAI-compatible endpoint)
  • Start OAuth -> Codex for OpenAI, OAuth -> Claude for Claude, or OAuth -> Antigravity for Gemini and let Clipal append the provider automatically
  • Set base_url, api_key / api_keys, and routing weights for API-key providers
  • Reorder, pin, enable, or disable OAuth providers the same way as API-key providers

Changes take effect immediately without a restart.

OAuth upstream notes:

  • OAuth -> Codex supports OpenAI Responses requests
  • OAuth -> Claude supports Claude messages and count_tokens
  • OAuth -> Antigravity supports Gemini-compatible generateContent, streamGenerateContent, countTokens, model listing, and Gemini image models through generateContent. Imagen/Veo predict* endpoints use Google AI Studio API-key or Vertex providers instead.
  • For Claude and Codex OAuth, ordinary clients use an Agent SDK-compatible upstream envelope by default, with required transport fields handled by Clipal.
  • Client-supplied control fields win over defaults when supported by the target model: explicit tools, Claude thinking / context_management / output_config, and Codex reasoning / tool_choice / parallel_tool_calls are preserved.
  • OAuth credentials are stored locally outside YAML under ~/.clipal/oauth/
  • Clipal refreshes access tokens automatically before expiry when a refresh_token is available, and retries once after an upstream 401 by forcing a refresh
  • OAuth providers are usually added through the authorization flow; if you already have Codex CLI auth.json (~/.codex/auth.json), CLIProxyAPI single-account OAuth JSON, or a sub2api export JSON bundle, you can import it from the same Add Provider dialog

If you prefer to manage configuration as code, you can still edit YAML files directly. Field-level details and example templates live in Config Reference.

4. Verify It Is Running

curl -fsS http://127.0.0.1:3333/health
clipal status
clipal status --json

5. Connect Your Client

Clipal standardizes client ingress on:

  • /clipal

Compatibility aliases remain available for older setups:

  • /claudecode
  • /codex
  • /gemini

See Client Setup for exact client-side configuration.

6. What To Read Next