Development
Plugin
ccx
CCX is a high-performance AI API proxy and protocol translation gateway for Claude, OpenAI Chat, OpenAI Images, OpenAI Embeddings, Codex Responses, and Gemini.
Plugin Signal76/100Solid
maintained98
capable34
documented100
adopted77
Install
$ npx -y skills add BenedictKing/ccx --agent claude-code
Run the curl in your terminal, the rest in Claude Code.
Stats
3,936
Stars
313
Forks
Active
Maintenance
Go
Language
MIT
License
3d ago
Last commit
6mo ago
Created
Repo: BenedictKing/ccx
What's inside
Skills
4/model-update新增或更新 CCX 项目中的 Claude 模型注册。当用户提到新模型发布、添加模型、更新模型元数据、model registry、模型注册时触发。覆盖上游能力表、AgentModelProfile、优先级排序和代码生成。/store-update在 CCX Desktop 发布后下载 Store MSIX 并生成发布公告。用户提到 Store 上架、MSIX、从 GitHub Release 下载 store.msix、发布后同步 Windows Store、从 release 填写商店更新内容时必须使用此技能。该技能会下载最新 GitHub Release 的 amd64/arm64 MSIX，校验 sha256，从 Release body 生成 Store listing releaseNotes 预览，并输出手动上传指引。/upstream-check检查 Claude Code / Codex 上游版本变更，对比本地版本，识别协议/工具/用法相关更新并追加 TODO 提醒/version-bump升级项目版本号并提交git，支持patch/minor/major版本升级或指定具体版本号，自动从git log生成CHANGELOG
README
1Claude / OpenAI Chat / OpenAI Images / OpenAI Embeddings / Codex Responses / Gemini API Proxy - CCX
English | 简体中文
CCX is a high-performance AI API proxy and protocol translation gateway for Claude, OpenAI Chat, OpenAI Images, OpenAI Embeddings, Codex Responses, and Gemini. It provides a unified entrypoint, built-in web administration, channel orchestration, failover, multi-key management, and model routing.
Features
- Integrated backend + frontend architecture with single-port deployment
- Dual-key authentication with
PROXY_ACCESS_KEYand optionalADMIN_ACCESS_KEY - Web admin console for channel management, testing, logs, and monitoring
- Support for Claude Messages, OpenAI Chat Completions, OpenAI Images, OpenAI Embeddings, Codex Responses, and Gemini APIs
- Smart scheduling with priorities, promotion windows, health checks, failover, and circuit recovery
- Context routing filters candidate channels by actual model context window and max output capability
- Per-channel API key rotation, proxy support, custom headers, model allowlists, and route prefixes
- Responses session tracking for multi-turn workflows
- Embedded frontend assets for simple binary deployment
Sponsor
Screenshots
Channel Orchestration
Visual channel management with drag-and-drop priority adjustment and real-time health monitoring.
Add Channel
Supports multiple upstream service types and flexible API key, model mapping, and request parameter configuration.
Traffic Stats
Real-time monitoring of per-channel request traffic, success rate, and latency.
Architecture
CCX exposes one backend entrypoint:
Client -> backend :3000 ->
|- / -> Web UI
|- /api/* -> Admin API
|- /v1/messages -> Claude Messages proxy
|- /v1/chat/completions -> OpenAI Chat proxy
|- /v1/responses -> Codex Responses proxy
|- /v1/images/{...} -> OpenAI Images proxy
|- /v1/embeddings -> OpenAI Embeddings proxy
|- /v1/models -> Models API
`- /v1beta/models/* -> Gemini proxy
Images endpoints currently include:
POST /v1/images/generationsPOST /v1/images/editsPOST /v1/images/variations
See ARCHITECTURE.md for the detailed design.
Quick Start
Option 0: CCX Desktop
CCX Desktop provides a native desktop experience with GUI for managing channels, keys, and agent configuration.
| Platform | Install Method | Notes |
|---|---|---|
| Windows | Search CCX Desktop in Microsoft Store | Recommended. Auto-update, no manual signing. Also available as setup.exe from GitHub Releases. |
| macOS | brew tap BenedictKing/ccx && brew install --cask ccx-desktop | Or download .dmg (arm64/amd64) from GitHub Releases. |
| Linux | Download .AppImage from GitHub Releases | Mark as executable and run. |
See CCX Desktop Guide for detailed setup instructions.
Option 1: Binary
- Download the latest binary from Releases.
- Create a
.envfile next to the binary:
PROXY_ACCESS_KEY=your-proxy-access-key
PORT=3688
ENABLE_WEB_UI=true
APP_UI_LANGUAGE=en
- Run the binary and open
http://localhost:3000
On Windows, if the client runs from cmd, PowerShell, WSL, or Docker and localhost does not reach CCX, use the Windows host IPv4 address instead, for example http://192.168.1.23:3000. When BIND_HOST is empty, CCX listens on all interfaces by default through :PORT; set BIND_HOST=127.0.0.1 for local-only access.
For background startup without Docker, see Service Startup.
Option 2: Docker
docker run -d \
--name ccx \
-p 3000:3000 \
-e PROXY_ACCESS_KEY=your-proxy-access-key \
-e APP_UI_LANGUAGE=en \
-v $(pwd)/.config:/app/.config \
crpi-i19l8zl0ugidq97v.cn-hangzhou.personal.cr.aliyuncs.com/bene/ccx:latest
Run in the background with Docker Compose:
docker compose up -d
Enable Watchtower auto-update:
docker compose -f docker-compose.yml -f docker-compose.watchtower.yml up -d
Pull the latest image immediately after setup if needed:
docker compose pull ccx
docker compose up -d ccx
Option 3: Build From Source
Prerequisites: Go 1.25+, Bun, and Make (macOS: xcode-select --install).
git clone https://github.com/BenedictKing/ccx
cd ccx
cp backend-go/.env.example backend-go/.env
make install # install all dependencies (frontend + Go modules + dev tools)
make run
Useful commands:
make dev
make run
make build
make frontend-dev
Core Environment Variables
PORT=3688
ENV=production
ENABLE_WEB_UI=true
PROXY_ACCESS_KEY=your-proxy-access-key
ADMIN_ACCESS_KEY=your-admin-secret-key
APP_UI_LANGUAGE=en
LOG_LEVEL=info
Main Endpoints
- Web UI:
GET / - Health:
GET /health - Admin API:
/api/* - Claude Messages:
POST /v1/messages - OpenAI Chat:
POST /v1/chat/completions - Codex Responses:
POST /v1/responses - OpenAI Images:
POST /v1/images/generations,POST /v1/images/edits,POST /v1/images/variations - OpenAI Embeddings:
POST /v1/embeddings - Gemini:
POST /v1beta/models/{model}:generateContent - Models API:
GET /v1/models
Development
Recommended local workflow:
make dev
Frontend only:
cd "frontend"
bun install
bun run dev
Backend only:
cd "backend-go"
make dev
Additional Docs
- CCX Desktop
- Client Setup
- CCX Desktop (中文)
- Client Setup (中文)
- README.zh-CN.md
- backend-go/README.md
- ARCHITECTURE.md
- DEVELOPMENT.md
- ENVIRONMENT.md
- docs/service/README.md - non-Docker service startup
- RELEASE.md
Community
Join the QQ group for discussion: 642217364
Star History
Acknowledgments
License
MIT
File tree
1570BenedictKing/ccxView on GitHub
.agents/
skills
.claude/
skills/
github-release/
skill.md
model-update/
SKILL.md
store-update/
evals/
evals.json
scripts/
download_store_msix.py
SKILL.md
upstream-check/
scripts/
upstream-check.sh
SKILL.md
version-bump/
SKILL.md
.claudeignore
.dockerignore
.gitattributes
.github/
actions/
signpath-sign/
action.yml
dependabot.yml
scripts/
assert-authenticode-signature.ps1
workflows/
check-bindings.yml
deploy-docs.yml
docker-build.yml
release.yml
update-homebrew.yml
.gitignore
.prettierrc
.serena/
.gitignore
memories/
architecture/
reasoning-preservation-plan.md
memory_maintenance.md
project_ccx_desktop_premium_ui_refactoring.md
project_overview.md
style_and_conventions.md
suggested_commands.md
task_completion.md
vision-routing/
gemini-fallback-limitation.md
project.yml
AGENTS.md
backend-go/
.air.toml
.env.example
.gitignore
.serena/
.gitignore
memories/
memory_maintenance.md
project.yml
build.sh
CHANGELOG.md
CLAUDE.md
cli_options_test.go
cmd/
stream_verify/
main.go
DEV_GUIDE.md
docs/
MALFORMED_TOOLCALL_MEMO.md
go.mod
go.sum
internal/
autopilot/
ab_test_sampler_test.go
ab_test_sampler.go
ab_test_store.go
advisor_decision_store.go
advisor_hint_policy_test.go
advisor_hint_policy.go
advisor_privacy_test.go
afp_cost_evidence_test.go
afp_cost_evidence.go
async_writer_test.go
async_writer.go
auto_discovery_events_test.go
auto_discovery_resume_test.go
auto_discovery_routes_test.go
auto_discovery_routes.go
auto_discovery_test.go
auto_discovery.go
capability_floor_test.go
capability_floor.go
carry_forward_test.go
channel_profile_test.go
channel_profile.go
compshare_console_test.go
compshare_console.go
context_limit_memory.go
custom_managed_routes.go
deepseek_account_test.go
deepseek_account.go
discovery_task_store_test.go
discovery_task_store.go
document_capability_memory.go
effort_normalize_test.go
effort_normalize.go
endpoint_inventory_test.go
endpoint_inventory.go
endpoint_policy_prefer_auto_test.go
endpoint_policy_test.go
endpoint_policy.go
event_hub_test.go
event_hub.go
fast_decay_test.go
fast_decay.go
group_change_detector.go
group_change_test.go
handlers_abtest.go
handlers_advisor.go
handlers_auto_managed_test.go
handlers_auto_managed.go
handlers_billing_terms_test.go
handlers_billing_terms.go
handlers_cockpit.go
handlers_dryrun.go
handlers_endpoints_test.go
handlers_events_test.go
handlers_events.go
handlers_exchange_rates_test.go
handlers_exchange_rates.go
handlers_health_test.go
handlers_key_multiplier_test.go
handlers_key_multiplier.go
handlers_local_runtime.go
handlers_manual_intent.go
handlers_newapi_test.go
handlers_newapi.go
handlers_profile_coverage.go
handlers_provider_quality_test.go
handlers_provider_quality.go
handlers_recommendations.go
handlers_routing_config_test.go
handlers_routing_config.go
handlers_subscription_accounts_test.go
handlers_subscription_accounts.go
handlers_subscription.go
handlers_task_template.go
handlers_trace.go
handlers.go
health_analyzer_test.go
health_analyzer.go
integration_simulation_test.go
intent_matcher_test.go
intent_matcher.go
key_endpoint_profile_test.go
key_endpoint_profile.go
kimi_console_test.go
kimi_console.go
local_candidate_provider_test.go
local_candidate_provider.go
local_model_runtime_test.go
local_model_runtime.go
local_task_template_test.go
local_task_template.go
manager_discovery_fields_test.go
manager_emit_events_test.go
manager_integration_test.go
manager.go
manual_intent_store.go
manual_routing_intent_test.go
manual_routing_intent.go
mimo_console_test.go
mimo_console.go
minimax_token_plan_test.go
minimax_token_plan.go
model_frontier_scoring_test.go
model_frontier_scoring.go
model_frontier_test.go
model_frontier.go
model_profile_kimi_test.go
model_profile_store_active_test.go
model_profile_store.go
model_profile.go
model_resolver_frontier_test.go
model_resolver_test.go
model_resolver.go
model_routing_policy_test.go
model_routing_policy.go
newapi_adapter_test.go
newapi_adapter.go
newapi_group_guard_test.go
newapi_group_guard.go
newapi_subscription_sync_service.go
origin_tiebreaker_test.go
origin_tiebreaker.go
probe_worker_test.go
probe_worker.go
profile_change_detector_test.go
profile_change_detector.go
profile_changelog_test.go
profile_changelog.go
profile_coverage_test.go
profile_coverage.go
profile_store_test.go
profile_store.go
profiler_test.go
profiler.go
protocol_discovery_test.go
protocol_discovery.go
protocol_federation_routing_test.go
provider_quality_probe_test.go
provider_quality_probe.go
provider_quality_protocol.go
provider_quality_scoring.go
quality_trend_detector.go
quality_trend_test.go
rate_limit_applier_fix3_test.go
rate_limit_applier_test.go
rate_limit_applier.go
rate_limit_discovery_reason_test.go
rate_limit_discovery_test.go
rate_limit_discovery.go
recommendation_test.go
recommendation.go
request_correlation.go
request_profile_builder_test.go
request_profile_builder.go
request_profile_context.go
request_profile.go
resolve_api_key_test.go
response_header_timeout_test.go
response_header_timeout.go
route_target.go
routing_readiness_test.go
routing_readiness.go
routing_trace_actual_test.go
routing_trace_test.go
routing_trace.go
schema_migration_test.go
schema_migration.go
scoring_afp_test.go
scoring_test.go
scoring.go
smart_router_actual_channel_test.go
smart_router_channel_kind_test.go
smart_router_context_window_test.go
smart_router_document_constraint_test.go
smart_router_dryrun_constraints_test.go
smart_router_invariant_test.go
smart_router_learned_context_limit_test.go
smart_router_model_capabilities_test.go
smart_router_model_preview_test.go
smart_router_test.go
smart_router_trace_integration_test.go
smart_router.go
stability_hysteresis_test.go
stability_hysteresis.go
subscription_balance_fetcher_test.go
subscription_balance_fetcher.go
subscription_capability_test.go
subscription_capability.go
subscription_profile_test.go
subscription_profile.go
subscription_refresh_worker.go
task_classifier_test.go
task_classifier.go
task_complexity_test.go
task_complexity.go
task_domain_test.go
task_domain.go
time_series_test.go
time_series.go
trace_contract_test.go
trace_contract.go
trace_l3_lifecycle_test.go
trace_l4_http_test.go
trace_l5_smoke_test.go
trace_lifecycle_test.go
trace_lifecycle.go
trace_sse_golden_test.go
trusted_routing_advisor_test.go
trusted_routing_advisor.go
usage_metering_test.go
usage_metering.go
usage_pattern_accumulator_test.go
usage_pattern_accumulator.go
verify_endpoint_test.go
verify_endpoint.go
volcengine_coding_plan_test.go
volcengine_coding_plan.go
config/
account_uid_test.go
afp_routing_config_test.go
api_key_config_merge_test.go
auto_managed_kind_migration_test.go
autopilot_config_test.go
autopilot_config.go
bound_baseurl_test.go
builtin_models_manifest_test.go
builtin_models_manifest.go
channel_compat_cache_test.go
channel_compat_cache.go
channel_compat_context_limit_test.go
channel_compat_document_test.go
channel_compat_shared.go
channel_suspension_test.go
channel_uid_test.go
compat_seed_test.go
compshare_console_test.go
config_accounts.go
config_autopilot_migration_test.go
config_baseurl_test.go
config_blacklist_test.go
config_channel_name_test.go
config_chat.go
config_codex_compat_test.go
config_deprecated_grok_mapping_integration_test.go
config_deprecated_grok_mapping_test.go
config_gemini.go
config_images.go
config_loader_test.go
config_loader.go
config_messages.go
config_no_change_test.go
config_priority_placement_test.go
config_ratelimit_test.go
config_responses.go
config_tags_test.go
config_thinking_cache_test.go
config_upstream_snapshot_test.go
config_utils_test.go
config_utils.go
config_vectors.go
config.go
deprecated_param_cache_test.go
deprecated_param_cache.go
embedding_capability_test.go
embedding_capability.go
env_access_keys_test.go
env_https_test.go
env_ui_language_test.go
env.go
exchange_rate_graph_test.go
exchange_rate_graph.go
health_check_test.go
health_check.go
key_group_multiplier_test.go
key_group_multiplier.go
logical_channel_crud.go
logical_channel_test.go
logical_channel.go
mimo_console_test.go
model_registry_test.go
model_registry.go
origin_backfill_test.go
provider_templates_test.go
provider_templates.go
provider_usage_recover_test.go
runtime_timeouts.go
stream_timeout_validation.go
suspension_recovery_test.go
system_header_cache.go
timeout_validation.go
volcengine_access_key_test.go
volcengine_afp_pricing_test.go
volcengine_afp_pricing.go
volcengine_plan_scope_test.go
volcengine_plan_scope.go
conversation/
override_test.go
override.go
persistence.go
tracker_test.go
tracker.go
converters/
chat_roles_downgrade_test.go
chat_roles.go
chat_to_responses_codex.go
chat_to_responses_helpers_test.go
chat_to_responses_nonstream_test.go
chat_to_responses_request_test.go
chat_to_responses_stream_test.go
chat_to_responses_think_test.go
chat_to_responses.go
claude_converter.go
claude_to_responses_test.go
claude_to_responses.go
codex_history_test.go
codex_tool_search_tools.go
codex_tools_test.go
codex_tools.go
converter_test.go
converter.go
factory.go
gemini_claude_tool_test.go
gemini_converter_test.go
gemini_converter.go
... 1384 moreFAQ
ccx is a Claude Code plugin with 4 hand-picked skills for development work, indexed on Flowy. Install it with the command on its page. It includes model-update, store-update, upstream-check. Its skills do not fire on their own yet. Request auto-invocation to have Flowy route them as you prompt. Free and open source.
- What is ccx?
- CCX is a high-performance AI API proxy and protocol translation gateway for Claude, OpenAI Chat, OpenAI Images, OpenAI Embeddings, Codex Responses, and Gemini.
- How do I install ccx?
- Run these in Claude Code: npx -y skills add BenedictKing/ccx --agent claude-code. Then prompt normally.
- Does ccx auto-invoke its skills?
- Not yet. It is indexed on Flowy as a plain plugin. Request auto-invocation on its page and Flowy will route its skills for you as you prompt.
- Is ccx free?
- Yes. Flowy is free and open source, with nothing gated. You can read every skill in full before you install.