1. 项目概述与核心价值

如果你和我一样，日常开发中同时用着 Claude Code、Codex CLI、Gemini CLI 这几个命令行 AI 助手，那你肯定也经历过那种“甜蜜的烦恼”。每个工具都有自己的配置、自己的 API 密钥、自己的账户体系，切换起来麻烦不说，账户配额用完了还得手动去换。更别提想用免费模型或者本地部署的模型来分担一下成本，那配置起来更是让人头大。CliGate 这个项目，就是来解决这个痛点的。它是一个运行在你本地的、多协议 AI API 代理服务器，你可以把它理解为你所有 AI 命令行工具的“统一网关”或“智能路由器”。

它的核心价值非常直接： 让你用一个统一的本地入口，来管理所有不同的 AI 服务 。你不再需要为每个工具单独设置环境变量或配置文件，而是让它们都把请求发到 CliGate（比如 localhost:8081 ），然后由 CliGate 来帮你决定这个请求应该用哪个账户、哪个 API 密钥、甚至哪个模型服务（包括免费的）来处理。它内置了一个功能相当完善的 Web 仪表盘，所有账户、密钥、路由规则、使用统计都在上面可视化操作，还支持通过 Telegram 或飞书（Feishu）来远程控制你的 AI 助手会话。简单来说，它把分散的、手动的 AI 工具管理，变成了集中的、自动化的、可观测的运维工作。

1.1 它解决了哪些具体问题？

  1. 账户池与自动切换 ：你可以添加多个 ChatGPT、Claude、Google（Antigravity）账户到 CliGate。当一个账户的配额用尽或令牌（Token）过期时，CliGate 可以自动切换到池子里的下一个可用账户（支持轮询、随机或粘性会话），并且会自动刷新过期的 OAuth 令牌，无需你手动干预。这直接解决了“账户不够用”和“令牌过期中断”的问题。

  2. API 密钥的统一管理与容错 ：同样，你可以把 OpenAI、Azure OpenAI、Anthropic、Google Gemini、Vertex AI 等众多服务商的 API 密钥都交给 CliGate 管理。它支持密钥的连通性测试、自动故障转移和负载均衡。这意味着即使某个服务商的 API 临时出问题，你的工作流也能自动切换到备选方案，保证了可用性。

  3. 智能路由与成本优化 ：这是 CliGate 的“智能”所在。你可以设置路由策略，比如“优先使用账户池”（节省 API 调用费用）还是“优先使用 API 密钥”（保证稳定性和功能）。更厉害的是 模型映射 和 免费模型路由 。例如，你可以将 Claude Code 请求的 claude-haiku 模型，映射到通过 Kilo AI 等渠道提供的免费模型（如 DeepSeek、Qwen），这样对于不那么关键的任务，就能实现零成本调用。同时，它也支持将请求路由到本地运行的模型服务（如 Ollama），为隐私敏感或离线场景提供了可能。

  4. 多端统一的操作层 ：通过集成 Telegram 和飞书频道，你可以在手机或公司聊天软件里，像在本地终端一样启动和控制 Codex 或 Claude Code 的运行时会话。所有的对话记录、任务状态、执行进度都会同步到 CliGate 的仪表盘上。这打破了开发环境的地域限制，让你能随时随地继续你的编码任务。

  5. 全面的可观测性 ：所有经过 CliGate 的请求都有完整的日志记录，并且提供了清晰的使用量统计和成本估算（基于内置的定价表）。这对于团队或个人管理 AI 使用预算、分析调用模式至关重要。你再也不用去各个服务商的后台拼凑账单了。

2. 核心架构与工作原理拆解

要玩转 CliGate，理解它的架构是关键。它不是一个简单的端口转发工具，而是一个具备协议转换、路由决策、会话管理和状态维护的中间层。我们来看一下它的核心工作流程。

2.1 整体架构视图

CliGate 作为一个本地服务器（默认运行在 localhost:8081 ），处于你的本地 CLI 工具（客户端）和远端的 AI 服务提供商（上游）之间。它的架构可以抽象为三层：

  1. 协议适配层 ：这是入口。不同的 CLI 工具使用不同的 API 协议。例如，Claude Code 使用 Anthropic 的 Messages API ( /v1/messages )，Codex CLI 使用 OpenAI 的 Chat Completions API ( /v1/chat/completions ) 或其内部 API ( /backend-api/codex/responses )，Gemini CLI 使用 Google 的 Gemini API ( /v1beta/models/* )。CliGate 需要理解这些不同的协议，并将它们标准化为内部可以处理的统一请求格式。同时，它也需要将内部处理后的结果，再转换回对应 CLI 工具期望的响应格式。这一步是它能“通吃”多种工具的基础。

  2. 路由决策与资源管理层 ：这是大脑。收到标准化请求后，CliGate 会根据你配置的规则进行决策：

    • 优先级模式 ：是先用账户池里的免费额度，还是先用付费的 API 密钥？
    • 路由模式 ：是自动根据模型名、可用性智能选择，还是手动为每个 App（如 Claude Code）指定固定的凭证？
    • 模型映射 ：请求的模型名（如 claude-haiku ）是否需要被替换成另一个模型（如 deepseek-chat ）？
    • 资源选择 ：根据上述决策，从账户池或 API 密钥池中选取一个当前最合适的、可用的凭证（包括令牌）。 这一层还负责管理所有资源的状态，比如令牌的自动刷新（仅在过期前5分钟内刷新，避免不必要的调用）、账户的启用/禁用、密钥的健康检查。

  3. 上游代理与响应处理层 ：这是执行者。使用选定的凭证，构造符合上游 API 要求的 HTTP 请求，并将请求发送出去。收到响应后，进行必要的处理（如记录日志、统计用量），再将响应返回给协议适配层，最终返回给客户端。

2.2 账户池与密钥池的协同工作

这是 CliGate 的核心资源管理机制，理解它们如何协同至关重要。

  • 账户池 ：主要针对提供免费额度或基于会话的 OAuth 服务，如 ChatGPT、Claude、Google Antigravity。CliGate 通过内置的浏览器模拟或 OAuth PKCE 流程，帮你登录并获取访问令牌（Access Token）。这些令牌是有生命周期的，CliGate 会监视其有效期，并在临近过期时自动刷新，甚至可以将刷新后的令牌写回原始 CLI 工具的配置文件（如 Claude Code 的 credentials.json ），实现双向同步。
  • API 密钥池 ：针对直接使用 API 密钥的服务，如 OpenAI、Anthropic、Gemini 等。这里管理的是静态的密钥字符串。CliGate 可以提供一键连通性测试，并支持在多个同类型密钥间进行负载均衡或故障转移。

协同策略 ：在“账户池优先”模式下，对于一个请求，CliGate 会先尝试从账户池中寻找匹配的、可用的账户。如果找不到，或者账户额度用尽，才会回退到使用 API 密钥池。在“API 密钥优先”模式下则相反。这种灵活性让你可以在免费额度和付费服务之间做出最适合自己成本结构的平衡。

2.3 频道网关与会话粘性

频道（Channel）功能是 CliGate 将 AI 助手能力扩展到移动端和协作场景的关键。它本质上是一个消息桥接器。

  • 连接 ：你将 Telegram Bot 或飞书自建应用的 Webhook/WebSocket 配置到 CliGate。这样，当你在这些聊天应用中发送消息时，消息会被转发到 CliGate。
  • 会话管理 ：CliGate 为每个频道对话（Chat）维护一个“运行时会话”状态。当你使用 /cx 或 /cc 命令启动一个任务时，CliGate 会创建一个与特定 AI 运行时（如 Codex）绑定的会话。此后，在该对话中发送的普通文本消息，都会被视为对同一会话的后续输入，直到你使用 /new 命令重置。这实现了 会话粘性 ，让你能进行连续的多轮对话，就像在本地终端一样。
  • 智能监督 ：CliGate 内置了一个简单的意图识别器。当你在频道中询问“进度如何？”、“总结一下”或说“开始新任务：...”时，它能理解这些意图，并从内存中的任务上下文进行回复，或启动新的任务，而不是机械地将所有消息都转发给 AI 运行时。这使得在移动端的交互更加自然和高效。

实操心得 ：飞书集成的“WebSocket 模式”是针对本地桌面环境的利器。与需要公网地址的 Webhook 模式不同，WebSocket 模式由 CliGate 主动与飞书服务器建立长连接，完美解决了内网穿透的麻烦。在配置飞书机器人时，务必在飞书开放平台的后台选择“启用 WebSocket 连接”。

3. 从零开始部署与配置实战

理论讲完了，我们上手把它跑起来。这里我会以 macOS/Linux 环境为例，Windows 用户操作类似，主要注意路径差异。

3.1 环境准备与安装

CliGate 基于 Node.js 开发，所以首先需要确保你的系统安装了 Node.js 18 或更高版本（推荐 LTS 版本）。你可以通过 node -v 命令检查。

安装 CliGate 有三种方式，我推荐第一种，最干净：

方式一：使用 npx 直接运行（无需永久安装） 

npx cligate@latest start

这条命令会下载最新版的 CliGate 并立即启动。适合快速体验或临时使用。关闭终端后服务即停止。

方式二：全局安装（推荐用于长期使用） 

npm install -g cligate

安装完成后，你就可以在任何终端使用 cligate 命令了。启动服务：

cligate start

首次运行会初始化配置文件和数据目录（通常在 ~/.cligate 下）。

方式三：桌面应用（Electron） 如果你更喜欢图形化的独立应用，可以去项目的 GitHub Releases 页面下载对应系统的桌面版。它本质上是一个包裹了 CliGate 服务器的 Electron 应用，自带系统托盘图标，管理起来更直观。

启动成功后，默认会在浏览器中打开 http://localhost:8081 仪表盘。如果没自动打开，你可以手动访问。

3.2 添加和管理你的 AI 资源

仪表盘首页会展示整体状态。接下来最关键的一步就是添加“燃料”——你的账户和 API 密钥。

3.2.1 添加 ChatGPT/Claude/Antigravity 账户
  1. 点击左侧导航栏的 “Accounts” 。
  2. 你会看到三个标签页：ChatGPT、Claude、Antigravity（Google）。
  3. 以添加 ChatGPT 账户为例，点击 “Add Account” 按钮。
  4. 这时会弹出一个系统默认浏览器窗口，引导你完成 OpenAI 的官方 OAuth 登录流程。 请务必使用你想要添加到池子里的那个 ChatGPT 账户登录。
  5. 登录授权成功后，浏览器页面会提示成功，你可以关闭它。回到 CliGate 仪表盘，刷新一下，应该就能看到新添加的账户了，包括其状态（可用/禁用）、已用/剩余额度等信息。

注意事项 ：

  • 安全提醒 ：整个 OAuth 流程发生在你的本地浏览器和 OpenAI 服务器之间，CliGate 服务器只接收最终的授权码（Code）来交换令牌。你的密码不会经过 CliGate。令牌也以加密形式存储在本地，权限为 0600 （仅所有者可读可写）。
  • 账户限制 ：确保你添加的账户类型支持 API 调用。例如，某些地区的 ChatGPT Plus 订阅可能不包含 API 访问权限。
  • 令牌刷新 ：CliGate 会在令牌过期前自动刷新。你可以在账户列表看到“刷新于”的时间戳。这个刷新操作也会尝试写回原始 CLI 工具的配置文件中（如果检测到），实现“一处刷新，处处更新”。
3.2.2 添加 API 密钥

如果你有直接的 API 密钥，或者想使用 Azure OpenAI 等服务，就需要在这里添加。

  1. 点击左侧导航栏的 “API Keys” 。
  2. 点击 “Add API Key” 。
  3. 在表单中，首先选择 Provider （提供商），例如 OpenAI、Azure OpenAI、Anthropic、Google Gemini 等。
  4. 根据选择的 Provider，表单会动态变化。例如：
    • OpenAI ：只需填入 API Key 。
    • Azure OpenAI ：需要填入 API Key 、 Endpoint （你的 Azure 资源终结点）、 Deployment Name （部署名称）和 API Version 。
    • Google Gemini ：需要填入 API Key 。
    • Vertex AI ：需要填入 Service Account Key JSON （整个 JSON 内容）、 Project ID 和 Location 。
  5. 填写后，强烈建议点击 “Test Connection” 按钮，验证密钥和配置是否正确。测试成功后再保存。
  6. 保存后，密钥会出现在列表中，你可以随时启用、禁用或编辑它。

3.3 配置你的 CLI 工具指向 CliGate

现在 CliGate 有了资源，下一步是让你的 AI 命令行工具知道它。CliGate 提供了最省事的“一键配置”功能。

  1. 在仪表盘左侧，进入 “Settings” 页面。
  2. 找到 “One-click CLI Configuration” 区域。
  3. 你会看到针对 Claude Code、Codex CLI、Gemini CLI 和 OpenClaw 的配置按钮。点击对应工具的“Configure”按钮。
  4. CliGate 会自动检测这些工具的安装路径和配置文件，并写入正确的代理设置。成功后会有提示。

如果你想手动配置，或者了解一下背后的原理，以下是各工具的手动配置方法：

Claude Code: 在你的 shell 配置文件（如 ~/.bashrc , ~/.zshrc ）中添加：

export ANTHROPIC_BASE_URL=http://localhost:8081
export ANTHROPIC_API_KEY=any-key-here # 这里可以填任意字符串，CliGate 会忽略它并使用池中凭证

然后重启终端或执行 source ~/.zshrc 。

Codex CLI: 编辑 Codex CLI 的配置文件（通常位于 ~/.codex/config.toml ），确保包含以下内容：

chatgpt_base_url = "http://localhost:8081/backend-api/"
openai_base_url = "http://localhost:8081"

Gemini CLI: Gemini CLI 的配置相对复杂，因为它需要修改 Node.js 模块内部的代码。因此， 强烈推荐使用仪表盘的一键补丁功能 ，这比手动操作可靠得多。

OpenClaw: 如果你使用 OpenClaw 扩展，可以在其配置文件中添加 CliGate 作为一个自定义提供商。同样，使用仪表盘的一键配置是最简单的。

配置完成后，尝试在终端运行 claude 或 codex 命令，它们发出的请求就应该被 CliGate 接收并代理了。你可以在 CliGate 仪表盘的 “Request Logs” 中看到实时的请求记录。

3.4 设置路由规则（按需优化）

默认情况下，CliGate 使用“自动路由”模式，它会根据一些启发式规则（如模型名称匹配）来选择凭证。但对于精细控制，你需要了解并设置路由规则。

在 “Settings” 页面的 “Routing” 部分：

  1. Priority Mode（优先级模式） ：

    • Account Pool First ：对于支持账户池的请求（如 ChatGPT、Claude），优先使用账户池里的免费额度。用尽后再回退到 API 密钥。 这是节省成本的推荐模式。
    • API Key First ：优先使用 API 密钥池。这能保证更稳定的服务质量和更一致的模型能力（因为 API 密钥通常对应着特定的付费模型版本）。

  2. Routing Mode（路由模式） ：

    • Automatic ：CliGate 自动为每个请求选择最合适的凭证。这是最简单的“开箱即用”模式。
    • App Assigned ： 手动为每个应用程序（App）绑定特定的凭证 。这提供了最强的控制力。例如，你可以指定所有来自 Claude Code 的请求都使用你添加的“Claude 账户 A”，而所有来自 Codex CLI 的请求都使用“OpenAI API 密钥 B”。你甚至可以绑定到某个本地运行时（Local Runtime）。

  3. Model Mapping（模型映射） ： 这是实现“免费模型路由”和“本地模型路由”的关键。例如，默认规则里有一条：将请求的 claude-haiku 模型映射到通过 Kilo AI 网关的免费模型。你可以点击“Edit”进行修改，将 claude-haiku 映射到其他免费模型，如 deepseek-chat 或 qwen-plus 。你也可以添加新规则，比如将 gpt-4 映射到你本地 Ollama 运行的 llama3.2 模型（需要先配置好本地运行时）。

3.5 配置频道（Telegram/Feishu）实现移动端控制

这个功能极大地提升了便利性。这里以配置 Telegram Bot 为例：

  1. 创建 Telegram Bot ：在 Telegram 中与 @BotFather 对话，创建一个新的 Bot，并获取它的 HTTP API Token 。
  2. 在 CliGate 中配置 ：
    • 进入仪表盘 “Channels” 页面。
    • 点击“Add Channel”，选择“Telegram”。
    • 将刚才从 BotFather 获取的 Token 粘贴到 “Bot Token” 字段。
    • “Polling Mode” 保持默认的 Webhook 即可（CliGate 会处理）。
    • 在 “Default Runtime Provider” 中，选择这个频道里默认使用哪个 AI 运行时（如 Codex）。
    • 设置 “Working Directory”，这是 Bot 执行文件操作时的基准路径。
    • 保存配置。
  3. 与你的 Bot 互动 ：
    • 在 Telegram 中找到你刚创建的 Bot，发送 /start 初始化。
    • 现在，你可以像在终端一样使用命令了：
      • /cx 写一个Python快速排序函数 - 启动一个 Codex 任务。
      • /cc 帮我分析这段错误日志 - 启动一个 Claude Code 任务。
      • 直接发送 如何优化这个循环？ - 如果当前有活跃会话，则作为后续输入；如果没有，则使用频道默认的运行时。
      • /new - 重置当前会话。
      • 进度如何？ - CliGate 会从内存中回复任务状态，而不是转发给 AI。

避坑指南 ：飞书（Feishu）的配置比 Telegram 稍复杂，因为它涉及企业自建应用和权限审核。关键点在于， 对于本地桌面使用，务必在 CliGate 中选择“WebSocket”模式 ，并在飞书开放平台的应用事件订阅设置中，选择“启用 WebSocket 连接”。这样可以避免需要公网 IP 或内网穿透工具的麻烦。具体步骤请参考项目 Wiki 或飞书官方文档。

4. 高级功能与深度使用技巧

基础配置完成后，CliGate 还有一些高级功能能进一步提升你的体验和效率。

4.1 本地模型集成（Ollama）

如果你在本地运行了 Ollama 并拉取了一些模型（如 llama3 , qwen2.5 ），你可以将它们接入 CliGate，实现部分请求的本地化处理。

  1. 确保 Ollama 服务运行 ：通常运行 ollama serve 后，API 服务在 http://localhost:11434 。
  2. 在 CliGate 中注册本地运行时 ：
    • 进入 “Local Models” 页面。
    • 点击 “Add Local Runtime”。
    • “Name” 可以自定义，如 “My Ollama”。
    • “Endpoint URL” 填写 http://localhost:11434 。
    • 点击 “Save”。
  3. 发现模型 ：保存后，点击该运行时条目旁的 “Refresh Models” 按钮。CliGate 会调用 Ollama 的 API 拉取已下载的模型列表。
  4. 启用本地路由 ：在 “Settings” -> “Routing” 中，确保 “Enable Local Model Routing” 是开启状态。
  5. 创建模型映射规则 ：现在，你可以去 “Model Mapping” 添加一条新规则。例如，将请求的模型 gpt-3.5-turbo 映射到本地运行时 My Ollama 中的模型 llama3.2 。这样，当 Codex CLI 请求 gpt-3.5-turbo 时，请求就会被转发到你本地的 Llama 3.2 模型。

实操心得 ：本地模型推理速度取决于你的硬件，且能力与云端大模型有差距。建议将一些对实时性要求不高、或对模型能力要求较低的调试、简单问答类任务路由到本地模型，以节省云端调用次数和成本。同时，注意本地模型可能不支持所有 OpenAI/Anthropic 的 API 参数，复杂的请求可能会失败。

4.2 使用统计与成本分析

CliGate 的 “Usage & Costs” 页面是你的 AI 支出仪表盘。它能按账户、按模型、按提供商统计 Token 使用量和估算成本。

  • 数据来源 ：成本估算是基于 CliGate 内置的一个定价注册表（Pricing Registry）。这个注册表包含了主流模型的大致公开价格（如 gpt-4o 每百万输入 Token 多少美元）。你可以在 “Pricing Registry” 页面查看和修改这些价格，如果你有企业合约价，可以在这里更新以获得更准确的成本估算。
  • 统计维度 ：你可以查看今日、本月或自定义时间范围内的总花费，也可以下钻查看是哪个账户（或密钥）、哪个模型（如 claude-3-5-sonnet ）消耗最多。这对于识别异常使用模式、优化资源分配非常有帮助。
  • 注意事项 ：这里的成本是 估算值 ，最终账单请以各 AI 服务商后台为准。对于账户池（如 ChatGPT）的免费额度，CliGate 可能无法获取精确的剩余额度，其“用量”统计更多是基于调用次数的相对值。

4.3 API Explorer 与调试

当你需要排查问题，或者想手动测试某个 CliGate 端点时， “API Explorer” 页面是你的瑞士军刀。

  1. 选择你想要测试的 Endpoint ，例如 POST /v1/chat/completions 。
  2. 在 Request Body 编辑器中，填入符合该端点要求的 JSON 数据。例如，对于 OpenAI Chat Completions，你可以填： 
    {
  "model": "gpt-4o",
  "messages": [{"role": "user", "content": "Hello, world!"}],
  "stream": false
}
  3. 点击 “Send Request” 。
  4. 下方会显示原始的 Request （包含 CliGate 添加的最终路由信息）和 Response 。

这个工具对于验证路由规则是否生效、检查某个 API 密钥是否有效、或者模拟特定 CLI 工具的请求非常有用。

4.4 工具安装器与资源目录

对于新手，或者想快速搭建完整环境的人，CliGate 内置的 “Tool Installer” 和 “Resources Catalog” 非常贴心。

  • Tool Installer ：它能自动检测你的系统是否安装了 Node.js、Claude Code、Codex CLI、Gemini CLI 和 OpenClaw。如果未安装，可以直接通过这个界面一键安装或更新。这大大降低了环境准备的复杂度。
  • Resources Catalog ：这是一个精选的免费和试用 LLM API 资源目录。它会列出像 Kilo AI、OpenRouter 等平台提供的免费模型资源，包括其限制、兼容性和获取方式。当你想要配置免费模型路由时，可以在这里找到可用的选项和配置提示。

5. 常见问题排查与维护心得

即使设计得再完善，在实际使用中也可能遇到问题。这里我总结了一些常见坑点和排查思路。

5.1 账户登录失败或令牌刷新失败

  • 症状 ：在添加账户时，浏览器登录后没有成功跳转回 CliGate；或者账户列表显示令牌过期且未能自动刷新。
  • 可能原因与解决 ：
    1. 浏览器拦截 ：某些浏览器或安全软件会拦截弹出窗口或重定向。确保允许 CliGate 打开浏览器窗口，并检查地址栏是否被重定向到 localhost:8081 的相关回调地址。
    2. 网络问题 ：OAuth 流程需要访问 OpenAI/Anthropic/Google 的服务器。检查你的网络连接，特别是如果使用了需要特殊配置的网络环境。
    3. 账户权限 ：确认你登录的账户确实有 API 访问权限。某些区域的 ChatGPT 订阅可能不包含 API。
    4. 手动刷新 ：对于已添加但令牌过期的账户，可以尝试在账户列表点击该账户的 “Refresh Token” 按钮进行手动刷新。如果失败，可能需要移除该账户后重新添加。

5.2 CLI 工具连接 CliGate 失败

  • 症状 ：运行 claude 或 codex 命令后，长时间无响应或报连接错误。
  • 排查步骤 ：
    1. 确认 CliGate 服务运行 ：访问 http://localhost:8081 ，看仪表盘是否能打开。
    2. 检查环境变量/配置 ：
      • 对于 Claude Code：执行 echo $ANTHROPIC_BASE_URL ，确认已设置为 http://localhost:8081 。
      • 对于 Codex CLI：检查 ~/.codex/config.toml 文件内容是否正确，特别是 openai_base_url 和 chatgpt_base_url 的路径和端口。
    3. 查看 CliGate 日志 ：在 CliGate 仪表盘的 “Request Logs” 页面，查看是否有来自对应工具的请求记录。如果没有，说明请求根本没到 CliGate，问题出在客户端配置。如果有记录但报错，则根据错误信息进一步判断。
    4. 检查防火墙/端口 ：确保没有防火墙规则阻止了 localhost:8081 端口的本地通信。

5.3 请求被路由到错误的模型或返回错误

  • 症状 ：请求成功发出，但返回的结果不对，或者提示模型不支持。
  • 排查步骤 ：
    1. 查看请求日志详情 ：在 “Request Logs” 中，找到那条请求，点击展开详情。重点关注：
      • Resolved Model ：CliGate 最终将请求路由到了哪个模型？
      • Provider ：使用了哪个提供商（账户或密钥）？
      • Response ：上游 API 返回的具体错误信息是什么？
    2. 检查模型映射规则 ：去 “Settings” -> “Model Mapping” ，确认是否有规则将你请求的模型映射到了一个不兼容的模型上。例如，将 claude-3-opus 映射到了一个只支持聊天补全格式的免费模型，而 Claude Messages API 的格式可能不被支持。
    3. 检查凭证状态 ：确认路由到的那个账户或 API 密钥是启用状态，并且有足够的配额或余额。
    4. 使用 API Explorer 测试 ：直接使用 API Explorer 模拟发送一个相同模型和参数的请求，观察是否能成功。这有助于隔离是路由问题还是上游 API 本身的问题。

5.4 频道（Telegram/Feishu）无法接收或响应消息

  • 症状 ：在聊天软件中发送命令，CliGate 没有反应。
  • 排查步骤 ：
    1. 检查频道配置状态 ：在 “Channels” 页面，查看对应频道的状态是否为 “Connected” 或 “Running”。如果是 “Error” 或 “Stopped”，检查配置信息（如 Token）是否正确。
    2. 查看频道日志 ：CliGate 仪表盘有实时日志流（SSE Log Stream），开启后可以看到详细的频道连接和消息处理日志。
    3. 对于 Telegram ：确保你的 Bot 没有被停止，并且你已经向它发送过 /start 命令。
    4. 对于飞书 WebSocket ：这是最复杂的。确保：
      • CliGate 配置为 WebSocket 模式。
      • 飞书开放平台应用的事件订阅设置中， 已启用“接收消息”等必要权限 ，并且 已启用“WebSocket 连接” 。
      • 飞书服务器能够连接到你运行 CliGate 机器的 IP 和端口（如果是家庭网络，可能需要公网 IP 或内网穿透，这也是为什么本地桌面推荐 WebSocket 模式的原因，因为它是 CliGate 主动向外连接）。

5.5 数据文件与备份

CliGate 的所有配置、账户令牌、API 密钥、日志都存储在本地目录中（通常是 ~/.cligate ）。定期备份这个目录是个好习惯，尤其是在你配置了大量账户和复杂路由规则之后。

  • 配置文件 ： ~/.cligate/config.json 包含了所有的路由规则、频道设置、本地运行时配置等。
  • 数据库文件 ： ~/.cligate/cligate.db （SQLite）存储了账户、密钥、使用记录、会话状态等。
  • 备份建议 ：在升级 CliGate 版本前，可以手动复制整个 ~/.cligate 目录进行备份。大多数情况下，新版 CliGate 能兼容旧版数据格式，但备份总是最安全的。

最后，CliGate 是一个活跃开发的开源项目。遇到任何问题，除了自己排查，也可以去项目的 GitHub Issues 或 Discord 社区寻求帮助。社区里有很多热心的开发者和用户，很多奇怪的坑可能已经有人踩过并提供了解决方案。

Logo
DeepSeek技术社区

欢迎加入DeepSeek 技术社区。在这里，你可以找到志同道合的朋友，共同探索AI技术的奥秘。

更多推荐

cover

DeepSeek-V4 长文本稳定性：实测 RAG 场景下 128K 上下文截断与补救方案

avatar DeepSeek技术社区
cover

DeepSeek-V4 推理优化：paged attention 显存效率实测与 vLLM 部署避坑

avatar DeepSeek技术社区
cover

DeepSeek RAG 置信区间控制：如何避免知识库问答的「幻觉安全区」陷阱

avatar DeepSeek技术社区