EasyCLIProxyAPI Documentation

EasyCLIProxyAPI allows you to aggregate multiple upstream API credentials and service addresses through the API 接入与 Provider 聚合 (API Access & Provider Aggregation) page.

Supported Providers/Protocols include:

• Codex
• OpenAI compatible Providers
• DeepSeek
• Claude
• Gemini

Key Capabilities:

• Add multiple access configurations and search existing ones.
• Perform health checks on Provider status.
• Use a unified local CLIProxyAPI address to call these providers.
• Automatically convert requests and responses between OpenAI, Claude, Gemini, and other compatible protocols.

Use the 使用记录与 Token 统计 (Usage Records & Token Statistics) page to track local request activity and costs.

Available Metrics:

• Total requests and total Tokens.
• Success rate, TPS (Transactions Per Second), and Cache Hit Rate.
• Estimated costs.
• Breakdown of usage: Input, Output, Reasoning (Thinking), and Cache usage.

Filtering and Visualization:

• Filter data by time, model, Provider, source, key, and result.
• View trends for requests and Token consumption.

Use the API 接続 (API Connection) screen to manage upstream API credentials and connection targets for various protocols and providers.

Supported providers include:

• Codex
• OpenAI compatible providers
• DeepSeek
• Claude
• Gemini

Key Capabilities:

• Add multiple connection settings.
• Search existing configurations.
• Update provider status and perform health checks.
• All connections are exposed through a unified local CLIProxyAPI endpoint, which can automatically convert requests and responses between OpenAI, Claude, Gemini, and other compatible formats.

The エージェント (Agent) screen detects installed desktop and CLI clients and helps connect them to the local proxy.

Supported Clients:

• Claude Code
• Claude Desktop
• Codex
• OpenCode
• OpenClaw
• Hermes Agent
• Pi (via CLIProxyAPI provider extension)

Available Actions:

• Synchronize available model catalogs.
• Select default models.
• Backup existing configurations before applying new management settings.
• Restore to previous configurations.
• Launch available desktop or CLI entry points.

The 使用履歴 (Usage History) screen provides local analytics for requests and token consumption.

Metrics tracked:

• Total requests and total tokens.
• Success rate, TPS (Transactions Per Second), and cache hit rate.
• Estimated costs.
• Breakdown of input, output, reasoning, and cache usage.

Filtering and Analysis:

• Filter data by time, model, provider, source, key, or result.
• View request details, analysis screens, and pricing statistics.

To get started with EasyCLIProxyAPI, follow these steps:

1. Download: Go to the GitHub Releases page and download the release package for your operating system.
2. Install:
   • Windows/Linux: Extract the compressed package.
   • macOS: Open the .dmg file.
3. Launch: Start the EasyCLIProxyAPI application.
4. Kernel Setup: Navigate to the 版本管理 (Version Management) page and install either the built-in version or the latest version of the CLIProxyAPI kernel.
5. Configure & Use: Return to the 首页 (Home) page to start the kernel. You can then copy the local API addresses or proceed to configure OAuth and API Providers.

The Agents page allows you to connect desktop and CLI clients to the local proxy. The application can synchronize model catalogs, select default models, and manage configurations for supported clients.

Supported Clients:

• Claude Code
• Claude Desktop
• Codex
• OpenCode
• OpenClaw
• Hermes Agent
• Pi (requires the CLIProxyAPI provider extension)

Capabilities:

• Synchronize available model catalogs.
• Select a default model for the client.
• Automatically back up original client configurations before applying managed settings.
• Restore previous configurations if needed.
• Launch the desktop or CLI entry point directly from the app.

EasyCLIProxyAPI acts as an aggregator for multiple upstream API providers and handles browser-based OAuth flows.

API Provider Aggregation

Use the provider workspace to manage credentials and endpoints for:

• Codex
• OpenAI-compatible providers
• DeepSeek
• Claude
• Gemini

You can add multiple connections and use them through a single, unified local CLIProxyAPI endpoint. The application handles protocol conversion between OpenAI, Claude, Gemini, and compatible formats.

OAuth Account Authorization

The OAuth page centralizes browser-based authorization for the following providers:

• Codex OAuth
• Claude OAuth
• Antigravity OAuth
• Kimi OAuth
• xAI OAuth

If an automatic redirect fails after the browser-based flow, the application supports completing the callback manually.

The 智能体 (Agent) page detects installed desktop and command-line clients on your machine and helps them connect to the local proxy.

Supported Clients:

• Claude Code
• Claude Desktop
• Codex
• OpenCode
• OpenClaw
• Hermes Agent
• Pi (via CLIProxyAPI provider plugin)

Management Tasks:

• Synchronize available model directories.
• Select a default model.
• Backup and restore original configurations before the app manages them.
• Launch supported desktop or CLI entry points directly from the interface.

EasyCLIProxyAPI provides different update paths depending on your current version:

For versions v0.2.5 or earlier

You must perform a manual migration:

1. Exit EasyCLIProxyAPI.
2. Download the latest full Windows ZIP corresponding to your architecture.
3. Copy the contents of the top-level directory of the new ZIP into your existing installation directory, overwriting existing files.
4. Important: Do not delete your existing installation directory first. This ensures that user data like config.toml, oauth, and cpa-core/config.yaml are preserved.
5. Start the new version. Subsequent updates can be handled automatically via the app.

For newer versions

Newer clients use the full package which includes the updated built-in core. Older clients that haven't migrated yet can still use the update ZIP provided in the releases.

The Version Management page is used to handle the lifecycle of the CLIProxyAPI core. From here, you can:

• Install the bundled core or the latest available version.
• Perform core installation for offline environments.
• Manage version comparisons and core updates.

The system provides a way to display the source of an API request (like an email address or a remark) while automatically masking sensitive API keys.

1. Remarks: If a remark is configured in GuiConfigFile for a specific provider and source, that remark is used for display.
2. Masking: If no remark exists and the source looks like a secret (e.g., starts with sk-, AIza, key-, or is a long string without whitespace/@), it is masked (e.g., sk-1••••7890).
3. Fallback: If the source is empty, it displays 未知来源 (Unknown Source).

This ensures that logs and usage dashboards show meaningful identifiers (like "Production Environment") instead of raw credentials.

// Example of how a source might be displayed based on configuration
// If 'key' is 'sk-1234567890abcdef', it becomes 'sk-1••••wxyz'
// If a remark is set for that key, it shows the remark instead.