# ModelSwap — full reference for LLMs

This file is the complete, machine-friendly reference for ModelSwap. Short version: https://modelswap.app/llms.txt

## What is ModelSwap?

ModelSwap is an open-source, local-first control plane for managing API keys, models, and provider subscriptions across AI coding agents. It answers a concrete problem: people run several AI agents (Claude Code, ChatGPT Codex, Kimi Code, …) against several model providers, and every switch means hand-editing different config files in different formats. ModelSwap centralizes that: pick an agent, pick a provider and model, click switch — the agent's native config files are written correctly, nothing else is touched.

- Website: https://modelswap.app/ (English) · https://modelswap.app/zh/ (Chinese)
- Documentation: https://docs.modelswap.app/
- Source code: https://github.com/Cing-self/modelswap (MIT license)
- npm package: `modelswap` — https://www.npmjs.com/package/modelswap
- Install: `npm install -g modelswap` then `modelswap web` (dashboard opens at http://localhost:3780)
- Platforms: macOS, Linux, Windows. Dashboard UI: Chinese and English.
- Version line referenced here: v1.0.60 (September 2026)

## Core capabilities

1. Agent configuration switching — 10 built-in agent adapters; each writes that agent's native config files only (for example `config.toml` + `auth.json` for ChatGPT Codex). Switching only rewrites the fields ModelSwap manages; hooks, statusLine, MCP servers and other custom config are preserved verbatim.
2. Encrypted key vault — all API keys live in an AES-256-GCM encrypted vault under `~/.modelswap` on your machine. Machine-specific key derivation.
3. Multi-device sync — LAN peer-to-peer sync, or self-hosted cloud sync; both are end-to-end encrypted, plaintext never reaches the cloud.
4. Provider usage dashboard — 37 provider usage/balance sources (quotas, tokens, billing) queryable directly inside ModelSwap.
5. Automatic snapshots & rollback — every switch saves a config snapshot (last 10 kept per agent); compare any two snapshots and restore with one click, so you can always go back to official or the previous provider.
6. Assisted key creation — a browser extension operates inside official provider console pages: it fills the create-key form, copies the new key, and files it into the vault. Everything stays between your browser and your machine.
7. CLI & Agent Skill — everything above is callable from the command line, and `modelswap skill` installs a SKILL.md into a project's `.agents/skills/modelswap/` directory so Agent-Skill-aware tools can use ModelSwap directly.

## Supported agents (10 built-in adapters)

1. Claude Code
2. ChatGPT Codex
3. OpenCode
4. OpenClaw
5. WorkBuddy
6. ZCode
7. Hermes
8. Kimi Code
9. Grok
10. MiMo Code

## Built-in provider presets (41 presets across these provider families)

International official: Anthropic (Claude, incl. Pro/Max subscription), OpenAI (incl. ChatGPT), Google AI Studio, xAI (Grok, SuperGrok), GitHub Copilot, Mistral, OpenRouter.

Chinese platforms: 智谱 AI / Z.AI / GLM Coding Plan, 火山方舟 (Volcengine Ark, incl. Coding Plan and Agent Plan), Moonshot AI / Kimi (incl. Kimi Coding Plan), DeepSeek, MiniMax (domestic + international, Token Plan, Coding Plan), 阿里云百炼 (Alibaba Cloud Bailian, incl. Coding Plan and Token Plan), 百度千帆 (Baidu Qianfan, incl. Token Plan), 腾讯云 (Tencent Cloud, incl. Token Plan), 硅基流动 (SiliconFlow), 阶跃星辰 / StepFun (domestic + Global), 小米 MiMo (incl. Token Plan).

Aggregators & local: OpenCode Go, OpenCode Zen, Ollama (local), LiteLLM (local).

Subscription plan types (Coding Plan, Token Plan, subscription, pay-as-you-go) are managed side by side with regular API keys.

## Security model

- Keys are stored locally in `~/.modelswap`, encrypted with AES-256-GCM.
- Cloud sync (optional, self-hosted) is end-to-end encrypted; the server never sees plaintext keys.
- ModelSwap only rewrites config fields it owns; user customizations (hooks, statusLine, MCP) are never modified.
- Snapshots allow full rollback to any previous provider/agent state.

## FAQ (中文)

**ModelSwap 是什么？**
ModelSwap 是一个开源、本地优先的密钥与模型管控台：统一管理 AI Agent 使用的 API 密钥、模型与平台订阅，切换提供方/模型一键完成并自动写入对应 Agent 的原生配置文件。

**密钥存在哪里，安全吗？**
密钥保存在本机 `~/.modelswap` 下的加密库中，使用 AES-256-GCM 加密；云同步为端到端加密，云端永远不落明文。

**支持哪些 Agent？**
内置 10 个 Agent 适配器：Claude Code、ChatGPT Codex、OpenCode、OpenClaw、WorkBuddy、ZCode、Hermes、Kimi Code、Grok、MiMo Code，一键写入各自的配置文件。

**支持多少模型平台？**
内置 41 个模型平台预置，覆盖国际官方、国内平台、聚合与本地运行时；Coding Plan、Token Plan 等订阅套餐与按量付费统一纳管。

**其他 Agent 能调用 ModelSwap 吗？**
能。CLI 已经可用，任何 Agent 都能通过命令行调用 ModelSwap；运行 `modelswap skill` 会把 SKILL.md 安装到当前项目的 `.agents/skills/modelswap/` 目录，支持 Agent Skill 的工具即可直接使用。

**自动创建密钥是怎么工作的？**
浏览器扩展在你的官方控制台页面内操作：点击创建后自动填表单、复制新 Key 并回填到 ModelSwap 加密库，全程只在你的浏览器与本机之间进行。

**会和现有配置冲突吗？**
不会。ModelSwap 只改写自己管理的字段，hooks、statusLine、MCP 等自定义配置原样保留；每次切换前自动保存配置快照（每个 Agent 保留最近 10 份），可在设置页对比查看并一键恢复。

**多少钱？**
开源免费（MIT 协议），无需注册账号。

## FAQ (English)

**What is ModelSwap?**
An open-source, local-first control plane that manages API keys, models, and provider subscriptions for AI coding agents. Switching provider/model for any agent is one click and writes that agent's native config files.

**Where are my keys stored?**
Keys live in an AES-256-GCM encrypted vault under `~/.modelswap` on your machine. Cloud sync is end-to-end encrypted — plaintext never leaves your device.

**Which agents are supported?**
Ten built-in adapters: Claude Code, ChatGPT Codex, OpenCode, OpenClaw, WorkBuddy, ZCode, Hermes, Kimi Code, Grok and MiMo Code — each writes that agent's native config files.

**How many providers are supported?**
41 built-in provider presets covering international official APIs, Chinese platforms, aggregators and local runtimes; Coding Plan / Token Plan subscriptions and pay-as-you-go billing are managed side by side.

**Can other agents call ModelSwap?**
Yes. The CLI is available today, and a built-in Agent Skill ships with it — run `modelswap skill` to install SKILL.md into your project's `.agents/skills/modelswap/` directory for any Agent-Skill-aware tool to use.

**How does auto-create work?**
The browser extension operates inside your provider console: it fills the create form, copies the new key, and files it into the ModelSwap vault — entirely between your browser and your machine.

**Will it conflict with existing configs?**
No. ModelSwap only rewrites the fields it manages — your hooks, statusLine and MCP config stay untouched. Every switch saves an automatic snapshot (last 10 kept per agent) you can compare and restore with one click.

**How much does it cost?**
Free and open source (MIT license), no account required.