ai-switch

KO | EN

gitlite — search

#command-line #llm #react-native #framework #gpt #large-language-models #java #deep-learning #mcp #rust

(★ 9)

本地 AI Key 中枢：一把 Key 改完，OpenClaw / OpenCode / Codex / Claude Code 立刻能用；坏 Key 自动踢出，不把工具搞挂。

File Explorer

ZIP Download

- - bug_report.md
  - config.yml
  - feature_request.md
- - release.yml
- __init__.py
- aider.py
- antigravity.py
- base.py
- claude_code.py
- cline.py
- codex_cli.py
- continue_dev.py
- copilot_cli.py
- cursor_cli.py
- devin.py
- goose.py
- grok_cli.py
- hermes.py
- kimi_code.py
- openclaw.py
- opencode.py
- qwencode.py
- trae_work.py
- workbuddy.py
- zcode.py
- ai-switch.js
- postinstall.js
- __init__.py
- audit.py
- batch_import.py
- crypto_backup.py
- crypto_secrets.py
- data.py
- diagnostics.py
- downstream.py
- endpoints.py
- health_checker.py
- health_history.py
- i18n.py
- metapi_import.py
- model_quality.py
- paths.py
- pricing.py
- providers.py
- remote.py
- scheduler.py
- usage_import.py
- version.py
- - 01-dashboard.png
  - 03-backends.png
  - 04-health.png
  - 05-task-center.png
  - 06-dashboard-dark.png
- adapter-contribution.md
- backends.md
- demo-script-30s.md
- growth-linuxdo-post.md
- growth-next.md
- posts-final.md
- product-optimization.md
- quickstart.md
- release-notes-2.0.5.md
- release-notes-2.2.0.md
- release-notes-2.3.0.md
- release-notes-2.4.0.md
- troubleshoot-codex.md
- en.json
- zh_CN.json
- zh_TW.json
- ai-switch.spec
- build_package.ps1
- build_package.sh
- sprite.svg
- style.css
- index.html
.gitignore
.npmignore
app.py
docker-compose.yml
Dockerfile
LICENSE
package.json
README-zh_CN.md
README-zh_TW.md
README.md
release.sh
requirements.txt
run.py
VERSION

# Use via CDN

jsDelivr

jsDelivr serves any public GitHub repository as a CDN with zero setup. Pick a version and a file to get a ready-to-paste link and snippet.

Version

File

Link

Example

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

<a href="README-zh_CN.md">简体中文</a> •
 <a href="README-zh_TW.md">繁體中文</a> •
 <a href="README.md">English</a>

<h1 align="center">AI Switch</h1>

Local AI API Key hub — change once, every tool works

<a href="#why">Why</a> ·
 <a href="#screenshots">Screenshots</a> ·
 <a href="#quick-start">Quick Start</a> ·
 <a href="#what-it-does">What it does</a> ·
 <a href="#docs">Docs</a> ·
 <a href="#supported-backends">Backends</a> ·
 <a href="#license">License</a>

---

## Why

If you juggle **relay / multi-vendor API keys** across **OpenClaw, OpenCode, Codex CLI, Claude Code**… you already know the pain:

| Pain | Without AI Switch | With AI Switch |
|------|-------------------|----------------|
| Rotate one key | Edit 5 config files by hand | Change once → push to installed tools |
| Bad key | Tool hangs / weird 401s | Health check → strip from backends |
| Wrong write | Silent overwrite | **Sync preview** · uninstalled = no write |
| Onboarding | “Where do I put the key?” | **3-minute path**: add → check → push → test |

**Positioning:** a local **Key hub** (manage · probe · push) — not another chat client.

> One key change. Every installed tool updates. Broken keys don’t take your stack down.

---

## Screenshots

---

## Quick Start

**Easiest:** download a build from [Releases](https://github.com/kingkate2009-droid/ai-switch/releases)  
(Windows / macOS Intel / Apple Silicon / Linux) → extract → run `ai-switch` / `start.bat` / `start.sh`  
→ open **http://127.0.0.1:8787**

**From source:**

```bash
git clone https://github.com/kingkate2009-droid/ai-switch.git
cd ai-switch
pip install -r requirements.txt
python3 run.py
```

**npm (Node.js):**

```bash
npx github:kingkate2009-droid/ai-switch
# → http://127.0.0.1:8787
```

Or install globally:

```bash
npm install -g github:kingkate2009-droid/ai-switch
ai-switch
```

**Docker:**

```bash
docker compose up -d
# → http://127.0.0.1:8787
```

Requires **Python 3.9+** for source/npm installs.

**3-minute loop:** [docs/quickstart.md](docs/quickstart.md)

1. Add vendor + key (or smart import)  
2. Health check passes  
3. Push to backends (**preview first**)  
4. Send `hi` in OpenCode / Codex / Claude Code

---

## What it does

Only three outcomes matter day-to-day:

1. **One place for keys** — vendors, tags, batch import, MetaAPI merge, dedupe  
2. **Know what’s alive** — model-level endpoint detection, quality checks, readable errors, adaptive interval, **archive of dead keys**
3. **Safe sync** — verified models only · preview · primary/backup failover · never write to uninstalled tools

Also included when you need them: **vendor types (Public/Relay/Raw key)** with filtering in the model catalog & check-in, **archiving** (hide + exclude from health checks + restore), check-in URLs, budgets, encrypted profile export, diagnostics pack, downstream routes, desktop packages.

<details>
<summary>Feature list (expand)</summary>

- Multi-vendor + key table, search / tags / batch enable-disable-delete  
- 26+ built-in providers + custom OpenAI-compatible endpoints  
- Per-model endpoint detection (Chat, Responses, Messages, Gemini) with auto/manual selection
- Vendor-grouped quality checks with per-vendor and per-model actions
- **Vendor types (Public/Relay/Raw key) with filtering in catalog & check-in**
- **Archive view: hide dead vendors/keys everywhere, exclude from health checks, restore anytime**
- Health monitor (scheduled), auto-disable / primary-backup failover (optional)
- Sync to OpenClaw, OpenCode, Claude Code, Codex, Cline, Aider, Continue, …  
- Batch / backup / MetaAPI import with undo  
- Transactional SQLite state with one-time legacy JSON migration
- npm/npx launcher in addition to source, Docker and desktop packages
- Light/dark theme, EN / 简体 / 繁中  
- Drop-in backend adapters ([contribution guide](docs/adapter-contribution.md))

</details>

---

## Docs

| Doc | For |
|-----|-----|
| [3-minute quickstart](docs/quickstart.md) | First run |
| [Codex won’t connect](docs/troubleshoot-codex.md) | Responses / env / models |
| [Backends](docs/backends.md) | What each engine supports |
| [Adapter contribution](docs/adapter-contribution.md) | Add a backend |

**Issues / help:** [open an issue](https://github.com/kingkate2009-droid/ai-switch/issues)

- [#1 Install & start](https://github.com/kingkate2009-droid/ai-switch/issues/1)
- [#2 Codex connectivity](https://github.com/kingkate2009-droid/ai-switch/issues/2)
- [#3 Import & merge](https://github.com/kingkate2009-droid/ai-switch/issues/3)
- Latest: [v2.4.0 Release](https://github.com/kingkate2009-droid/ai-switch/releases/tag/v2.4.0) · [notes](docs/release-notes-2.4.0.md)

---

## Supported backends

| Backend | Notes |
|---------|--------|
| OpenClaw | `openclaw.json`, auth profiles, models |
| OpenCode | `auth.json`, `opencode.jsonc` |
| Claude Code | `settings.json`, `~/.claude.json` |
| Codex CLI | `auth.json`, `config.toml` + Responses health |
| Cline / Aider / Continue.dev | IDE / CLI configs |
| Hermes Agent, QwenCode, Kimi Code, TRAE Work | See [backends.md](docs/backends.md) |

Status on the Backends page: **Not installed** · **Stopped (syncable)** · **Running** — uninstalled tools are never written.

### Model endpoint types

| Type | Examples |
|------|----------|
| `openai_chat` | OpenAI, DeepSeek, OpenRouter, Groq, Moonshot, Qwen, … |
| `anthropic` | Anthropic-compatible |
| `gemini` | Google Gemini |
| `openai_responses` | Codex-oriented `/v1/responses` path |

Endpoint support is detected per model. Automatic mode uses verified endpoints; manual mode lets you choose among detected formats. Backend sync only includes models with a recent successful health and endpoint check. Quality checks send four short requests per model and may consume provider quota.

---

## Desktop packages

| Platform | Asset pattern on Releases |
|----------|---------------------------|
| Windows x64 | `ai-switch-<ver>-windows-amd64.zip` |
| macOS Intel | `ai-switch-<ver>-macos-amd64.tar.gz` |
| macOS Apple Silicon | `ai-switch-<ver>-macos-arm64.tar.gz` |
| Linux x64 | `ai-switch-<ver>-linux-amd64.tar.gz` |

```bash
# Local package
bash scripts/build_package.sh
# Multi-platform release via CI
./release.sh v2.4.0
```

---

## Configuration & security

| Item | Path |
|------|------|
| Data | `~/.ai-switch/ai-switch.db` |
| Usage | `~/.ai-switch/usage.json` |
| Port | `8787` (`AI_SWITCH_PORT`) |

Existing `data.json` state is imported once; legacy files are retained with a `.legacy` suffix for rollback. The configured port is fixed: startup exits with a clear error if the port is occupied.

> **Keys live only under `~/.ai-switch/`.** Never commit that directory. Optional access token in Settings for LAN exposure.

**Stack:** Python + Flask · vanilla JS · SQLite storage · pluggable adapters · Apache 2.0

---

## Links

- [Releases](https://github.com/kingkate2009-droid/ai-switch/releases)  
- [Issues](https://github.com/kingkate2009-droid/ai-switch/issues)  
- [Linux.do](https://linux.do/) — community discussion

## License

Apache 2.0

ai-switch

File Explorer

# Use via CDN

Was this content helpful?

Recent Feedback

Download README