cc-gw

中文 | English

cc-gw 是一个面向 Claude Code 与同类客户端的本地多模型网关，负责：

• 归一化 /v1/messages 请求并映射到不同 Provider / 模型
• 复刻 Claude API 的流式与工具调用语义
• 记录请求日志、Token（含缓存命中）、TTFT/TPOT 等运行指标
• 提供可视化 Web 管理台与守护进程 CLI
• 在同一个 OpenAI 接入点聚合多 Provider / 多模型，兼容 Responses 与 Chat Completions 双协议

提示（2025-10）：OpenAI 接入点仍为实验特性，我们会尝试将请求转换为 Anthropic /v1/messages 并推断所需 beta 头，但部分专为 Claude Code 适配的代理可能仍返回“暂不支持”。此类模型请直接使用 /anthropic/v1/messages 端点。

核心组件：

| 模块 | 说明 | | ---- | ---- | | @cc-gw/server | Fastify 服务，实现协议转换、模型路由、Provider 适配与日志存储（支持 Anthropic 原生 payload/headers 透传与缓存统计） | | @cc-gw/web | React + Vite Web UI，包含仪表盘、日志面板、模型管理、系统设置 | | @cc-gw/cli | CLI 守护工具，封装 start/stop/restart/status 并托管 PID/日志 |

🚀 快速开始

完整配置指南（新手必读）

以下是完整的配置流程，请按照步骤顺序操作：

步骤 1: 安装并启动服务

# 方式一：npm 全局安装（推荐）
npm install -g @chenpu17/cc-gw
cc-gw start --daemon --port 4100

# 方式二：从源码构建（开发者）
git clone <repository>
cd cc-gw
pnpm install
pnpm --filter @cc-gw/server build
pnpm --filter @cc-gw/web build
pnpm --filter @cc-gw/cli exec tsx index.ts start --daemon --port 4100

启动后访问 Web 管理界面：http://127.0.0.1:4100/ui

步骤 2: 配置模型提供商

1. 在 Web UI 中进入 模型管理 页面
2. 点击 添加提供商，配置至少一个 Provider：
   • Anthropic Claude：

     Base URL: https://api.anthropic.com
     API Key: sk-ant-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
     默认模型: claude-3-5-sonnet-20241022

   Roo Code / Claude CLI 可通过 OpenAI 接入点访问 Anthropic 模型，但部分第三方代理可能拒绝该路径；若收到“暂不支持”或类似错误，请改用 /anthropic/v1/messages。
   • Moonshot Kimi：

     Base URL: https://api.moonshot.cn/v1
     API Key: sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
     默认模型: kimi-k2-0905-preview

   • DeepSeek：

     Base URL: https://api.deepseek.com/v1
     API Key: sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
     默认模型: deepseek-chat

3. 配置完成后使用 测试连接 验证连通性

步骤 3: 生成网关 API Key

1. 在 Web UI 中进入 系统设置 → API Key 管理
2. 点击 生成新密钥，为不同客户端创建独立的密钥：
   • Claude Code IDE: sk-gw-ide-xxxxxxxx
   • Codex CLI: sk-gw-codex-xxxxxxxx
   • 其他工具: sk-gw-other-xxxxxxxx

步骤 4: 配置环境变量（关键步骤）

将以下命令添加到 ~/.bashrc、~/.zshrc 等 shell 启动脚本，或使用 direnv 等工具统一管理：

# Claude Code / VS Code
export ANTHROPIC_BASE_URL=http://127.0.0.1:4100/anthropic
export ANTHROPIC_API_KEY=sk-gw-ide-xxxxxxxxxxxxxxxx

# Codex CLI（Responses API）
export OPENAI_BASE_URL=http://127.0.0.1:4100/openai/v1
export OPENAI_API_KEY=sk-gw-codex-xxxxxxxxxxxxxxxx
export CC_GW_KEY=sk-gw-codex-xxxxxxxxxxxxxxxx

# Roo Code / 旧式 OpenAI Chat Completions
export OPENAI_CHAT_BASE_URL=http://127.0.0.1:4100/openai/v1
export OPENAI_CHAT_PATH=/chat/completions

更新完毕后执行 source ~/.bashrc（或 source ~/.zshrc）让环境变量立即生效。完成后可以马上做一次快速连通性测试：

claude "你好，请简短回应"
codex ask "你好，请介绍一下自己"

若命令能够正常返回，同时可在 Web UI 的 请求日志 页面看到对应记录，即表明环境变量已经正确生效。

步骤 5: 配置客户端

• Claude Code / VS Code：在设置中选择自定义 API，填入 http://127.0.0.1:4100/anthropic 与 sk-gw-ide-xxxxxxxxxxxxxxxx。

• Codex CLI：编辑 ~/.codex/config.toml，内容示例：

  model = "gpt-5-codex"
  model_provider = "cc_gw"
  model_reasoning_effort = "high"
  disable_response_storage = true
  
  [model_providers.cc_gw]
  name = "cc_gw"
  base_url = "http://127.0.0.1:4100/openai/v1"
  wire_api = "responses"
  env_key = "cc_gw_key"

配置完成后，建议运行 codex status 或 codex chat "测试" 再确认一次终端输出。

5.1 OpenAI 接入点接入说明

• Responses API：推荐给支持新版 OpenAI Responses（例如 Codex CLI、最新 Agent 工具）的客户端，直接指向 http://127.0.0.1:4100/openai/v1/responses，即可自动在下游 Provider 间路由并返回标准 response 结构。
• Chat Completions API：针对 Roo Code、OpenAI CLI 等仍使用传统 POST /v1/chat/completions 的客户端，现可通过 http://127.0.0.1:4100/openai/v1/chat/completions 接入；工具仅需设置 Base URL（例如 Roo Code 的 “OpenAI Compatible” 配置）和 API Key 即可。
• 注意兼容性：OpenAI 入口为实验性最佳实践。若下游服务只支持 Claude Code 专用头部，可能仍返回“暂不支持”，此时改用 /anthropic/v1/messages。
• Anthropic Beta Header：若上游模型需要 beta 头（例如 Claude 4.5 预览），可设置环境变量 CC_GW_ANTHROPIC_BETA_<MODEL>（如 CC_GW_ANTHROPIC_BETA_CLAUDE_SONNET_4_5_20250929）或全局 CC_GW_ANTHROPIC_BETA_ALL；网关会在转发至 Anthropic 时尝试附加，也会针对 4.5 系列模型进行默认推断。
• 多模型聚合：无论使用 Responses 还是 Chat Completions，两种接口都会按配置聚合所有 Provider 模型，GET /openai/v1/models 将返回当前可用模型列表及默认 Provider。

步骤 6: 高级配置（可选）

6.1 模型路由配置

在 模型管理 → 路由配置 中，可以设置模型映射：

{
  "claude-3-5-sonnet-20241022": "kimi:kimi-k2-0905-preview",
  "claude-opus-4-1-20250805": "anthropic:claude-3-5-sonnet-20241022"
}

6.2 环境变量持久化

推荐使用 direnv 管理环境变量，在项目目录创建 .envrc：

# .envrc
export ANTHROPIC_BASE_URL=http://127.0.0.1:4100/anthropic
export ANTHROPIC_API_KEY=sk-gw-ide-xxxxxxxxxxxxxxxx
export OPENAI_BASE_URL=http://127.0.0.1:4100/openai/v1
export OPENAI_API_KEY=sk-gw-codex-xxxxxxxxxxxxxxxx
export CC_GW_KEY=sk-gw-codex-xxxxxxxxxxxxxxxx
# 若需兼容旧版 Chat Completions，可继续暴露聊天端点
export OPENAI_CHAT_BASE_URL=http://127.0.0.1:4100/openai/v1
export OPENAI_CHAT_PATH=/chat/completions
# 针对 Anthropic 新模型可设置 Beta Header（示例）
export CC_GW_ANTHROPIC_BETA_CLAUDE_SONNET_4_5_20250929=claude-code-20250219,interleaved-thinking-2025-05-14,fine-grained-tool-streaming-2025-05-14
export CC_GW_ANTHROPIC_BETA_ALL=claude-code-20250219,interleaved-thinking-2025-05-14,fine-grained-tool-streaming-2025-05-14

然后运行 direnv allow 自动加载。

6.3 HTTPS 配置

cc-gw 支持同时启动 HTTP 和 HTTPS 服务。

默认配置：

• HTTP: 端口 4100（默认启用，推荐用于本地开发）
• HTTPS: 端口 4443（默认关闭）
• 两个协议可独立启用/禁用，但至少要保持一个启用

⚠️ 重要提示：关于 HTTPS 证书

• 自签名证书无效：Claude Code 和大多数 AI 工具无法信任自签名证书，会导致 "Unable to connect to API" 错误
• 推荐方案：本地开发环境建议使用 HTTP 协议（127.0.0.1 本地访问非常安全）
• 如需 HTTPS：请使用受信任 CA（如 Let's Encrypt）签发的正式证书，或配置反向代理（如 Nginx/Caddy）处理 HTTPS

手动配置 HTTPS（通过配置文件）：

编辑 ~/.cc-gw/config.json：

{
  "http": {
    "enabled": true,
    "port": 4100,
    "host": "127.0.0.1"
  },
  "https": {
    "enabled": true,
    "port": 4443,
    "host": "127.0.0.1",
    "keyPath": "/path/to/your/ssl/key.pem",
    "certPath": "/path/to/your/ssl/cert.pem",
    "caPath": ""
  }
}

使用 HTTPS 访问：

# 重启服务使配置生效
cc-gw restart --daemon

# 访问 HTTPS 端点
curl https://127.0.0.1:4443/health

# Web UI HTTPS 访问
open https://127.0.0.1:4443/ui

环境变量配置：

# 推荐：使用 HTTP（默认）
export ANTHROPIC_BASE_URL=http://127.0.0.1:4100/anthropic
export OPENAI_BASE_URL=http://127.0.0.1:4100/openai/v1

# 如果使用 HTTPS（需要受信任的证书）
export ANTHROPIC_BASE_URL=https://127.0.0.1:4443/anthropic
export OPENAI_BASE_URL=https://127.0.0.1:4443/openai/v1

证书路径说明：

• keyPath: 私钥文件路径（必需）
• certPath: 证书文件路径（必需）
• caPath: CA 证书路径（可选，用于证书链）

6.4 自定义接入点（Custom Endpoints）

cc-gw 支持创建额外的自定义 API 端点，每个端点可以：

• 使用不同的协议（Anthropic、OpenAI）
• 配置独立的路由规则
• 支持多路径注册（一个端点支持多种协议）
• 自动路径扩展：只需配置基础路径（如 /my-endpoint），系统会根据协议自动注册完整的 API 路径

快速示例：

通过 Web UI 或配置文件创建自定义端点：

{
  "customEndpoints": [
    {
      "id": "claude-api",
      "label": "Claude 专用接入点",
      "path": "/claude",
      "protocol": "anthropic",
      "enabled": true
    }
  ]
}

配置后，客户端可以通过 http://127.0.0.1:4100/claude/v1/messages 访问（路径自动扩展）。

主要特性：

• 协议自动路径扩展：配置 /claude + anthropic 协议，自动注册 /claude/v1/messages
• 多协议支持：同时支持 Anthropic 和 OpenAI（Chat Completions / Responses API）
• 独立路由：每个端点可以配置独立的模型路由规则
• 路由模板：支持保存和应用路由预设，快速切换不同的 Provider 配置

详细文档：docs/custom-endpoints.md

⚠️ 如果 OpenAI 接入点仍返回“暂不支持”，请将客户端改用 /anthropic/v1/messages 端点并直接配置 Anthropic Provider。

常见问题排查

1. 连接失败：

   • 检查 cc-gw 服务状态：cc-gw status
   • 验证环境变量：echo $ANTHROPIC_BASE_URL
   • 查看请求日志确认错误信息

2. 认证错误：

   • 确认 API Key 正确且未过期
   • 检查环境变量是否正确加载
   • 验证 Provider 的 API Key 配置

3. 模型不可用：

   • 在"模型管理"中测试 Provider 连接
   • 检查模型路由配置
   • 确认上游服务模型名称正确

4. HTTPS 连接问题：

   • ⚠️ Claude Code 无法连接: 自签名证书会导致 "Unable to connect to API" 错误，建议使用 HTTP 协议（本地 127.0.0.1 访问安全）
   • 证书路径错误: 检查配置文件中的 keyPath 和 certPath 是否正确
   • 需要受信任证书: 如必须使用 HTTPS，请配置 Let's Encrypt 等受信任 CA 签发的证书
   • 两个协议都禁用: 至少要启用 HTTP 或 HTTPS 中的一个

✅ 完成以上 6 个步骤后，你的 cc-gw 网关就完全配置好了！所有 AI 客户端都可以通过统一的网关访问不同的模型服务。

推荐方式：npm 全局安装

npm install -g @chenpu17/cc-gw
cc-gw start --daemon --port 4100

首启会在 ~/.cc-gw/config.json 生成配置模板，推荐直接通过 Web UI (http://127.0.0.1:4100/ui) 完成所有后续配置与调整。cc-gw status、cc-gw stop、cc-gw restart 可用于日常运维。

⚠️ Linux 安装提示：本项目依赖 better-sqlite3；该库已为 Node 20/22/24 在 glibc/musl（x64/arm64/arm）提供预编译二进制，通常无需额外工具。如果你的环境未命中预编译（例如更早版本的 Node 或稀有架构），请先安装 build-essential python3 make g++，再运行 npm install -g @chenpu17/cc-gw --unsafe-perm --build-from-source。

从源码构建（开发者）

前置：Node.js 18.18+（推荐 20 LTS）、pnpm 8+

pnpm install
pnpm --filter @cc-gw/server build
pnpm --filter @cc-gw/web build
pnpm --filter @cc-gw/cli exec tsx index.ts start --daemon --port 4100

✅ 首次启动后推荐直接使用 Web 管理台完成 Provider、模型、日志等设置；仅在自动化或高级场景下再手动编辑配置文件。

如需以 CLI 启动后配合本地脚本使用，可在 shell 中补充以下变量：

export ANTHROPIC_BASE_URL=http://127.0.0.1:4100/anthropic
export ANTHROPIC_API_KEY=$(cc-gw keys current)

将其写入 direnv/shell profile，即可让后续工具自动读取。

Web 管理台

强烈建议以 Web 管理台作为主要的配置入口，可视化界面涵盖仪表盘、请求日志、模型管理与系统设置，所见即所得，避免手工改动 JSON 引入错误。

访问 http://<host>:<port>/ui，主要页面：

• Dashboard：展示请求量、Token 使用、缓存命中、各模型 TTFT（Time To First Token）/TPOT（Total Processing Time）、SQLite 数据库占用。
• 请求日志：多条件筛选（时间、Provider、模型、状态），查看压缩日志详情，支持分页导出与清理。
• 模型管理：维护 Provider 列表、预置模型、路由策略；一键测试连通性（发送诊断 PROMPT），支持保存并应用 Anthropic 路由模板，实现不同 Provider 方案的“一键切换”。
• 系统设置：端口、日志保留策略、是否存储请求 payload、日志级别与访问日志开关、日志清理工具。
• 安全控制：在“系统设置 → 安全”中可启用 Web UI 登录校验，自定义用户名及密码并自动保护所有 /api/* 管理接口（模型请求端点仍保持开放）。
• 使用指南：提供图文步骤、常见问题与排查提示，帮助团队成员快速熟悉配置流程。

UI 支持中英文、深色/浅色主题以及移动端响应式布局，提供键盘可达性（Skip Link、焦点管理）。

界面预览

连接 Claude Code

1. 启动 cc-gw 并在“模型管理”完成 Provider 配置。
2. 确认第 4 步环境变量已写入当前 shell 或系统（ANTHROPIC_BASE_URL / ANTHROPIC_API_KEY）。
3. 在 Claude Code 终端或 VS Code 插件中选择“自定义 API”，填入 http://127.0.0.1:4100/anthropic 并粘贴密钥。
4. 运行 claude "hello" 或在 VS Code 新建对话，若能在 Web UI 的“请求日志”看到记录即成功。

连接 Codex（原 Claude Code for Repo）

1. 在 Web UI “路由配置”页设定 /openai 端点默认模型。
2. 设置环境变量 OPENAI_BASE_URL=http://127.0.0.1:4100/openai/v1 与 OPENAI_API_KEY=<第 3 步生成的密钥>。
3. 在 ~/.codex/config.toml 按前文示例声明 model_providers.cc_gw，或在 CLI codex config set 中写入相同配置。
4. 执行 codex status / codex ask 验证连通性；如遇 404，请确认是否调用了 /openai/v1/responses。

环境变量与客户端配置示例

（段落保留，已在上方详细说明，可用于快速复制粘贴。）

使用场景 / Usage Scenarios

1. 双端点适配 / Dual Endpoint Support：通过 /anthropic 与 /openai 端点，分别兼容 Claude Code 与 Codex 客户端。无需重启 cc-gw，即可在 Web UI 中为两个端点配置独立的默认模型与路由策略。
2. 日志追踪 / Request Auditing：在“请求日志”页按端点、Provider、API Key 等维度筛选记录，可直接查看和复制完整的请求/响应 payload，辅助排查联调问题。
3. 模型切换 / Cross-Provider Routing：利用“模型管理”页的路由映射，将 Claude Code 请求透明地转发到 GLM、Kimi K2、DeepSeek 等任意 OpenAI 兼容模型，实现一套 IDE 客户端、多家大模型的快速切换；对 Anthropic 端点可保存当前映射为模板（例如“fox”“glm”），后续一键切换整套路由。
4. 操作指引 / Built-in Guidance：左侧“Help”导航提供分步配置、日常运维建议及 FAQ，可作为新人上手或问题排查的快速参考。

配置说明

大多数场景请通过 Web 管理台调整设置，以下仅作为 ~/.cc-gw/config.json 结构参考，便于脚本化或排查：

{
  "http": {
    "enabled": true,
    "port": 4100,
    "host": "127.0.0.1"
  },
  "https": {
    "enabled": true,
    "port": 4443,
    "host": "127.0.0.1",
    "keyPath": "~/.cc-gw/certs/key.pem",
    "certPath": "~/.cc-gw/certs/cert.pem",
    "caPath": ""
  },
  "host": "127.0.0.1",
  "port": 4100,
  "providers": [
    {
      "id": "kimi",
      "label": "Moonshot Kimi",
      "type": "kimi",
      "baseUrl": "https://api.moonshot.cn/v1",
      "apiKey": "sk-...",
      "models": [
        { "id": "kimi-k2-0905-preview", "label": "Kimi K2" }
      ]
    },
    {
      "id": "anthropic",
      "label": "Claude",
      "type": "anthropic",
      "baseUrl": "https://api.anthropic.com",
      "apiKey": "sk-ant-...",
      "models": [
        { "id": "claude-3-5-sonnet-latest" }
      ]
    }
  ],
  "defaults": {
    "completion": "kimi:kimi-k2-0905-preview",
    "reasoning": "anthropic:claude-3-5-sonnet-latest",
    "background": "kimi:kimi-k2-0905-preview",
    "longContextThreshold": 60000
  },
  "modelRoutes": {
    "claude-sonnet-4-5-20250929": "kimi:kimi-k2-0905-preview",
    "claude-opus-4-1-20250805": "anthropic:claude-3-5-sonnet-latest"
  },
  "logRetentionDays": 30,
  "storeRequestPayloads": true,
  "storeResponsePayloads": true,
  "logLevel": "info",
  "requestLogging": true,
  "responseLogging": true
}

字段要点（建议仍以 Web UI "系统设置 / 模型管理" 进行操作，下列仅便于理解结构）：

• http / https：协议配置，支持独立启用/禁用，但至少要保持一个启用。
  • enabled：是否启用该协议
  • port：监听端口
  • host：监听地址
  • keyPath / certPath（仅 HTTPS）：SSL/TLS 证书路径
  • caPath（可选）：CA 证书链路径
• host / port：旧格式向后兼容字段，新配置会自动迁移到 http / https 格式。
• providers：定义上游服务；type 支持 openai | anthropic | kimi | deepseek | custom。
• 模型标识使用 providerId:modelId 形式供路由引用。
• modelRoutes：将 Claude 发起的模型名映射到上游模型；支持在源模型名中使用 * 通配符匹配，匹配度更高（字符更多）的规则优先，同等情况下按配置顺序取第一条；若希望直接透传请求的模型名，可将目标写成 providerId:*，此时会将源请求中的模型名原样发送给对应 Provider。
• routingPresets：可选字段，保存多个 anthropic（或其他端点）路由模板，供 Web UI “一键切换”；每个模板仅包含 name 与 modelRoutes。
• storeRequestPayloads / storeResponsePayloads：是否分别在 SQLite 中压缩保存请求原文与响应内容；关闭可减少敏感数据落盘。
• bodyLimit：单次请求允许的最大请求体大小（字节），默认 10 MiB。/compact 等场景会发送较大上下文，如遇 413 可按需增大。
• logLevel：控制 Fastify/Pino 控制台日志级别（fatal/error/warn/info/debug/trace）。
• providers[].authMode：仅在 type: "anthropic" 时生效，可选 apiKey（默认，发送 x-api-key）或 authToken（发送 Authorization: Bearer）。配置 Claude Code 使用 ANTHROPIC_AUTH_TOKEN 时，请选择 authToken 并在 apiKey 输入框填入该值。
• requestLogging：是否输出每个 HTTP 请求的进入日志。
• responseLogging：是否输出每个 HTTP 请求完成的日志，可独立于 requestLogging 控制。
• 推荐通过 Web UI 的“模型管理 / 系统设置”在线编辑并热加载，无需手工修改文件。

Anthropic Provider 额外说明

• 当 Provider type 设置为 anthropic 时，网关会保留 Claude Code 发来的完整 payload，并将其原样转发到 <baseUrl>/v1/messages，无需转换工具调用或 metadata 字段。
• 所有自定义 Header（如 x-stainless-*、anthropic-beta、anthropic-dangerous-direct-browser-access）会自动透传到下游，确保 Claude Code 的诊断与调试能力不受影响。
• usage 统计会解析 cache_read_input_tokens / cache_creation_input_tokens，从而在日志与 Web UI 的 Token 指标中显示缓存命中或写入量；Moonshot / Anthropic 若未返回上述字段，则 cached 会继续显示为空。

环境变量

| 变量 | 说明 | | ---- | ---- | | PORT | CLI 启动时临时覆盖监听端口 | | CC_GW_UI_ROOT | 指定 Web UI 静态目录（默认自动检测 @cc-gw/web build 结果） | | CC_GW_DEBUG_ENDPOINTS | 设为 1 可在日志中输出下游请求 URL |

CLI 守护

pnpm --filter @cc-gw/cli exec tsx index.ts start [--daemon] [--port 4100]
pnpm --filter @cc-gw/cli exec tsx index.ts stop
pnpm --filter @cc-gw/cli exec tsx index.ts restart [--daemon] [--port 4100]
pnpm --filter @cc-gw/cli exec tsx index.ts status

• 守护模式下 PID/日志存放于 ~/.cc-gw/cc-gw.pid 与 ~/.cc-gw/logs/cc-gw.log。
• status 会回显配置与日志路径，便于排查。
• cc-gw version（或 cc-gw --version）可输出与 npm 包同步的版本号，便于核对升级情况。

数据与日志

• 数据库：~/.cc-gw/data/gateway.db（better-sqlite3 管理的嵌入式 SQLite）。
  • request_logs：请求摘要、路由结果、耗时、TTFT/TPOT。
  • request_payloads：压缩的请求/响应正文（Brotli）。
  • daily_metrics：按日聚合的调用次数与 Token 统计。
• 日志：~/.cc-gw/logs/cc-gw.log，包含请求生命周期、Provider 调用与 usage 摘要（event: usage.metrics）。

常见问题

• Web UI 404：请确认执行过 pnpm --filter @cc-gw/web build，并在 CLI 启动时自动或手动设置 CC_GW_UI_ROOT。
• usage 中无 cached_tokens：部分 Provider（如火山 DeepSeek）需开启 stream_options.include_usage 或提供专有缓存参数；cc-gw 已在支持的适配器中自动注入，如仍为 null 需确认上游是否支持。
• 日志数据库过大：可在“系统设置”关闭 payload 保存或缩短保留天数；Web UI 亦提供手动清理工具。

English

cc-gw is a local gateway tailored for Claude Code and similar Anthropic-compatible clients. It normalizes /v1/messages, routes traffic across heterogeneous providers, mirrors Claude’s streaming & tool semantics, and records detailed metrics that surface in a bilingual Web console and CLI daemon.

Highlights

| Feature | Details | | ------- | ------- | | Protocol adaptation | Converts Claude-style payloads into OpenAI-, Anthropic-, Kimi-, and DeepSeek-compatible requests while preserving tool calls and reasoning blocks. | | Model routing | Maps incoming model IDs to configured upstream providers with fallbacks for long-context/background tasks, plus Anthropic routing presets for one-click provider swaps. | | Observability | Persists request logs, token usage (including cache hits), TTFT, TPOT, and daily aggregates via better-sqlite3 with Brotli-compressed payloads; request/response bodies can be stored independently. | | Web console | React + Vite UI with dashboards, filters, provider CRUD, bilingual copy, and responsive layout. | | CLI daemon | cc-gw command wraps start/stop/restart/status, manages PID/log files, and scaffolds a default config on first launch. |

Standard Onboarding Checklist

1. Install & launch: npm install -g @chenpu17/cc-gw && cc-gw start --daemon --port 4100. The first run scaffolds ~/.cc-gw/config.json and makes the Web UI available at http://127.0.0.1:4100/ui.
2. Add providers: In Model Management, create at least one provider by entering its base URL/API key and selecting default models. Templates for Anthropic, Kimi, DeepSeek, etc., are provided in the sidebar.
3. Issue gateway API keys: Navigate to System Settings → API Keys and mint a key for each client (IDE, Codex CLI, automation). This is what clients will send to cc-gw.
4. Export environment variables (required):

   export ANTHROPIC_BASE_URL=http://127.0.0.1:4100/anthropic
   export ANTHROPIC_API_KEY=sk-ant-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
   
   # Optional: OpenAI-compatible endpoint (Codex, Open Interpreter, ...)
   export OPENAI_BASE_URL=http://127.0.0.1:4100/openai/v1
   export OPENAI_API_KEY=$ANTHROPIC_API_KEY

   Drop these lines into your shell profile (or direnv) so that IDEs inherit them automatically.
5. Point your clients:
   • Claude Code / VS Code extension: enable custom API mode, paste http://127.0.0.1:4100/anthropic, and use the key from step 3. The extension appends /v1/messages?beta=true automatically.
   • Codex CLI: update ~/.codex/config.toml:

     model = "gpt-5-codex"
     model_provider = "cc_gw"
     model_reasoning_effort = "high"
     disable_response_storage = true
     
     [model_providers.cc_gw]
     name = "cc_gw"
     base_url = "http://127.0.0.1:4100/openai/v1"
     wire_api = "responses"
     env_key = "cc_gw_key"

     Then export CC_GW_KEY=<gateway api key>.
6. Smoke test: run a short prompt (claude "hello", codex ask, etc.) and confirm a matching entry appears in Request Logs. If not, re-check the environment variables and provider routing.

Once these six steps are complete, any Anthropic/OpenAI-style client can pivot to cc-gw. All further tweaks (providers, routing, logging) can be handled from the Web UI.

Quick reinstall / binary upgrade

npm install -g @chenpu17/cc-gw
cc-gw start --daemon --port 4100

cc-gw status, cc-gw stop, and cc-gw restart manage the daemon. The Web UI remains at http://127.0.0.1:4100/ui.

⚠️ Linux build note: cc-gw relies on better-sqlite3. Prebuilt binaries cover Node 20/22/24 on glibc & musl (x64/arm64/arm). For other combos install build-essential python3 make g++, then rerun npm install -g @chenpu17/cc-gw --unsafe-perm --build-from-source.

From Source (contributors)

pnpm install
pnpm --filter @cc-gw/server build
pnpm --filter @cc-gw/web build
pnpm --filter @cc-gw/cli exec tsx index.ts start --daemon --port 4100

Connect Claude Code after completing the onboarding steps above—the CLI and editor automatically append /v1/messages, and cc-gw will forward ?beta=true samples or tool metadata upstream. For Codex or other OpenAI-style integrations, use http://127.0.0.1:4100/openai/v1 (or the equivalent value from step 4) and hit POST /openai/v1/responses if the client requires an explicit path.

Configuration Snapshot

• Providers include type, baseUrl, apiKey, and models descriptions.
• When type is anthropic, cc-gw forwards the original Claude payload and all headers to <baseUrl>/v1/messages, so tool calls/metadata remain intact.
• Model routes use providerId:modelId syntax to remap Claude requests.
• storeRequestPayloads / storeResponsePayloads control whether prompts and completions are persisted; disable either switch to avoid storing sensitive data.
• bodyLimit: maximum request body size (in bytes). Defaults to 10 MiB—raise this if clients like Claude Code /compact hit HTTP 413.
• logLevel adjusts Fastify/Pino verbosity (fatal → trace).
• requestLogging controls whether per-request access logs are emitted to the console.
• responseLogging toggles completion logs separately so you can keep the console quieter while preserving metrics.
• Web UI allows editing without restarting; CLI restart will pick up bundle changes after rebuilds.

Observability & Storage

• SQLite file under ~/.cc-gw/data/gateway.db tracks logs and aggregated metrics.
• Dashboard surfaces per-model TTFT/TPOT, cache hits（including Anthropic cache_read_input_tokens / cache_creation_input_tokens）, and DB size.
• Logs can be filtered/exported/cleaned directly from the UI.

CLI Reference

| Command | Description | | ------- | ----------- | | cc-gw start [--daemon] [--port] | Launch the Fastify server, auto-creating config if missing. | | cc-gw stop | Send SIGTERM and remove stale PID files. | | cc-gw restart | Convenience wrapper for stop + start. | | cc-gw status | Show running status, PID, log directory, config path. |

Environment

| Variable | Purpose | | -------- | ------- | | PORT | Override listening port at launch. | | CC_GW_UI_ROOT | Manually point to the built web assets. | | CC_GW_DEBUG_ENDPOINTS=1 | Log upstream provider endpoints for debugging. |

Tips

• Always rebuild @cc-gw/server and @cc-gw/web before restarts to ensure the daemon picks up new code.
• If cache statistics remain zero, verify whether the upstream provider exposes cached_tokens or equivalent details.
• Back up ~/.cc-gw/ (config, logs, SQLite DB) for migrations or disaster recovery.
• Use the Help page in the Web UI to review setup steps, troubleshooting tips, and FAQs whenever a teammate needs a refresher.

欢迎通过 Issue / PR 反馈改进意见，也可以在 Web UI 的“关于”页查看贡献者信息与致谢。