LoongPort

填域名、登录一次，Codex 与 Claude Code 即刻可用

🌐 官方网站：loongport.dev

📖 图文教程：从安装到第一次对话、自动故障切换、扩展资源与备份

简体中文 · 繁體中文 · English · 日本語

💬 QQ 群：773696474

中文 | English

它替你做什么

在中转站跑 Codex CLI 与 Claude Code，常规做法是一套繁琐流程：在中转站注册账号、定位控制台、手动创建 API Key、正确复制 base_url、找到并准确修改配置文件；更换 CLI 或档位后，整套流程还需重来一遍。

LoongPort 将其压缩为两步 —— 填入一个域名，登录一次。 应用会为账号可用的每个档位备好密钥，按各 CLI 的配置形状完成写入；此后更换档位只需一次点击，配置文件从头到尾不用你碰。

除中转站档位外，LoongPort 还内置官网直连档位（DeepSeek、智谱 BigModel、opencode），可在应用页管理，并在支持路由的配置中设置自动故障切换。站点提供生图档位时，还可以在 CLI 的对话里直接生图，且无需让出对话档位。

三分钟上手

给中转站负责人：本节可直接转发给你的用户。他们无需安装 cc-switch，也无需在 LoongPort 注册任何账号 —— 从下载到可用只有以下四步，且全程只与你的站点交互。若希望用户默认接入你的站点，见给中转站负责人。

1. 下载并打开 —— 见安装。首次接入从「连接你的第一个服务」开始；目标 CLI 需先安装并运行一次。
2. 粘贴中转站域名 —— 直接从浏览器地址栏整条复制亦可（如 https://example.com/usage，多余路径会自动去除）。
3. 注册或登录 —— LoongPort 会打开该站点自己的注册页。已有账号时，页面顶部的横幅可一键转至登录页。整个过程在该站点的真实页面中完成，LoongPort 仅获取登录后的凭据，不接触你的密码。
4. 确认应用配置 —— 为目标应用选择可用配置，按自己的意愿选择可选数据分享，再点「完成设置」。重启目标应用并发送一句测试消息，确认能够正常回复。此后：
   • 更换档位：点击「设为当前」即可
   • 充值：点击余额旁的按钮，打开该站点自己的充值页
   • 生图（站点提供生图档位时）：见在 CLI 里生图

无需修改配置文件，无需手动创建 API Key，无需记忆 base_url。

给中转站负责人

把 LoongPort 当作你自己站点的客户端发给新用户 —— 注册、充值、拿密钥都发生在你的站点上，新用户从下载到能用只剩「填域名、登录」两步。它是通用的 sub2api / new-api 客户端，不绑定任何一家站点：

• 接入文档可以省去。 用户无需按教程手动创建密钥、复制 base_url、查找配置文件。上述四步即为全部，其中三步发生在你的站点上。
• 不介入你与用户的关系。 LoongPort 没有账号体系、没有服务端。用户注册的是你的站点，充值走你的收款页，凭据仅存储在其本机（~/.loongport/ 的 SQLite）。
• 希望用户默认接入你的站点：LoongPort 会拉取一份带签名的远端配置，其中可包含「推荐站点」列表 —— 该列表显示在「选择服务站点」界面顶部，用户点击即可接入。提交 issue 告知即可。
• 支持 aff / 优惠码机制：同一份配置可携带你的邀请码与注册优惠码，在用户注册时自动附带（该机制目前面向 sub2api 站点）。

它替你完成的三件事，每一条均可在源码中核验：normalize_site_origin（relay/sub2api.rs，地址栏整条粘贴的域名亦可识别）、落至你自己注册页的自助注册（relay/login.rs，新站 /register、老用户 /login，邀请码随 URL 附带）、注入登录态的自助充值（relay/purchase.rs，打开 {你的域名}/purchase）。

收益、顾虑、技术前提与接入步骤见 loongport.dev/zh/for-relays。

不占用官方账号

两侧的官方登录均保留原状，可随时切回，无需手动修改任何内容 —— 但两者依赖的机制不同：

• Codex：ChatGPT 桌面版与命令行 codex 共用同一份凭据文件（~/.codex/auth.json），因此需要显式保留 —— LoongPort 默认开启保留，切换档位时不写入该文件。
• Claude：官方登录位于 ~/.claude/.credentials.json，而档位切换写入的是同目录的 settings.json，两个文件本就分离 —— 不存在被覆盖的问题。

安装

前往 Releases 页面下载。每个版本均由 GitHub Actions 自动构建：

ARM64 架构的 Windows 设备（如骁龙笔记本）请使用带 -arm64 后缀的两个文件。

没有界面？Ubuntu 20.04 及更老？用 loongport-cli

服务器（无桌面环境）和 Ubuntu 20.04 及更早等老系统装不了桌面版——为此提供了 loongport-cli：无 UI 版本，一条命令把中转站写进 codex / claude 等 7 个 CLI 的配置文件。静态单文件零依赖，任何 x86_64 Linux 可直接运行：

loongport-cli --add-site https://example.com --key sk-xxx --app codex

完整安装与使用说明见 docs/loongport-cli.md。

macOS 首次打开会被系统拦截。 由于未做 Apple 签名与公证，Gatekeeper 会报「已损坏」—— 并非真的损坏，而是缺少签名。请先拖入「应用程序」、暂不打开，然后在终端执行一次：

xattr -dr com.apple.quarantine /Applications/LoongPort.app

之后即可正常打开，此操作仅需一次。该命令的作用与安全性说明见 loongport.dev/zh/download。

怎么用

1. 填入域名 —— 你的中转站域名。直接从浏览器地址栏整条粘贴亦可；不确定时留空使用默认站点。
2. 登录 —— 弹窗内加载该站点真实的登录页，注册或登录均在此完成。LoongPort 仅获取登录后的凭据，不接触你的密码。
3. 自动备好密钥 —— 每个可用档位一把。优先复用账号中名称匹配的现有密钥，仅在找不到时新建，因此反复刷新不会在账号中留下冗余密钥。
4. 点击要使用的档位 —— Codex 使用 OpenAI 系档位、Claude 使用 Anthropic 系档位，点击该档位的「设为当前」即可写入对应配置（~/.codex/config.toml 或 Claude 的 settings），随后 Codex 或 Claude Code 即可直接运行。

切换 Codex 档位时会自动退出并重新打开 ChatGPT 桌面版 —— 它仅在启动时读取配置，不重启则新档位不生效。macOS 上为「请求退出」：存在进行中的对话时它会弹出自己的确认框，可选择取消（该次切换随之中止）；Windows 上为强制结束进程，不弹框，因此切换前应用会先行告知一次。切换 Claude 档位不涉及该流程。

系统托盘支持快捷切换适用应用的档位。完整入口、模型选择和恢复步骤见使用指南。

凭据与站点信息在本机 ~/.loongport/ 中加密保存（明细与边界见数据与隐私），调用时作为 Bearer token 发送给你选定的中转站。LoongPort 没有账号体系、没有服务端，无法获取你的凭据。

自动故障切换：按已应用的优先级尝试备用档位

在「应用」页开启「自动故障切换」，当前档位请求失败时，会按已应用列表的优先级尝试其它兼容档位。支持 Claude Code、Codex、Gemini 与 Grok Build；具体档位是否参加，以界面的资格和跳过原因说明为准。

• 先添加至少两个可用的兼容档位，再打开自动故障切换
• 筛选、排序或选择模型后，检查「更改尚未生效」，点击「应用更改」才提交；也可取消
• 开启会准备本地路由与该应用的接管。关闭自动故障切换只停止自动换档，不等于恢复直连
• 退出某一应用的接管，或停止并恢复全部配置，请到「设置 → 连接设置 → 本地路由」操作

版本说明：v6.26.2 不提供旧“省心模式”的价格最低/响应最快自动择优策略。 当前行为、截图与逐步恢复操作以使用指南第 3 章为准。

官网直连（官方 API）

除中转站外，LoongPort 内置三家厂商的官网直连档位：DeepSeek 开放平台、智谱 BigModel（GLM 系列）与 opencode 官网账号（同一账号展开 Zen 按量计费与 Go 订阅两个档位）。在「官方 API」页登录一次，应用即自动完成密钥获取与各平台配置。

官网直连与中转站配置都可在应用页查看和选择；支持本地路由的配置可按应用的已应用列表参与自动故障切换。是否支持以该行说明为准。

模型验证

档位实际提供的模型是否与标称一致，直接影响计费与输出质量。LoongPort 提供两层核验：

• 主动验证 —— 在档位上发起「模型验证」，对所选模型逐项探测并留存记录，可随时复查。
• 被动观察 —— 本地路由运行期间，托管档位的响应会被被动比对模型指纹，不发起任何额外请求；发现「疑似换芯」即在档位看板标记异常。被动观察只报告异常、不为正常档位作背书，正常档位零打扰。

使用统计与扣费对账

开启请求用量记录后，经本地路由的流量会记录在本机：请求数、成功率、成本、输入/输出与缓存 token、按日趋势，以及按供应商与模型的分组统计。

中转站账号行提供「扣费对账」：将本地估算成本与站点余额快照的实际扣减按时间窗对照并给出比值，实际扣减显著高于估算的窗口会被标出，便于发现计费异常。该功能需要相应应用的本地请求记录与站点余额快照；没有对账数据时不能据此判断扣费。

数据与隐私

• 凭据在本机加密保存。 API 密钥、OAuth 令牌、登录态、档位配置与 MCP 配置里携带的凭据，落在 ~/.loongport/ 的数据库与凭据文件中的都是密文；自动备份与云同步快照同样按这套保护处理。默认由系统凭据库解锁（macOS 钥匙串 / Windows 凭据管理器 / Linux Secret Service），不需要记口令；也可以自设保护口令，用于恢复数据和跨设备同步。
• 有一处仍然是明文：写进下游 CLI 的配置。 Codex 要读 ~/.codex/config.toml、Claude 要读它自己的配置，工具要能直接使用，那些文件就只能可读——这部分靠收紧文件权限降低暴露面，而不是靠加密。同样地，调用上游时凭据必须发给你选定的站点，所以不存在「密钥永不离开本机」。
• 完整使用记录与扣费对账在本机。 若开启下述数据共建，会外发已披露的聚合指标；不要把“本机记录”理解成没有任何统计上报。
• 两处上报，都可以随时关闭。 一是安装统计：已配置服务的注册域名、账号数量、应用版本、操作系统类型，以及一个随机生成、不含硬件指纹的安装标识（它的用途是去重，因此是持久的）；二是站点实测数据共建：按「站点 × 小时」聚合的首字耗时、错误率、token 与花费，来源标识每日轮换。两者都不含提示词、请求体、账号身份与密钥。新建安装在引导里确认一次——分享选项默认已勾选，取消勾选即可不参与；老版本升级上来的保留原有选择。开关在设置 → 通用 → 窗口行为。
• 准确的词是假名化，不是「匿名」：它不含直接身份字段，但安装标识是持久的，冷门站点的组合本身可能构成准标识符。另外，本地路由只监听 127.0.0.1，不对局域网或公网开放。

在 CLI 里生图

仅提供生图模型的档位收录在**「Codex 生图」标签页**（紧邻 Codex）。在其中一个档位上点击「启用」后，即可在 Codex、Claude Code 或 Gemini CLI 的对话中直接生成图片 —— 生图由 LoongPort 内置的工具（MCP server）完成。

四点说明：

• 该标签页不能单独使用，需配合对话档位。 它仅决定「图片从哪个档位产出」。
• 无需让出对话档位。 对话走 /v1/responses、使用 Codex 页选定的档位；生图走 /v1/images/generations、使用生图页选定的档位 —— 两个「当前项」相互独立，切换任一均不影响另一个。因此可以一边用 DeepSeek 对话、一边用站点的 4K 档位出图。
• 更换生图档位无需重启 CLI。 该选择存储在 LoongPort 自己的数据库中、每次生图时读取，CLI 的配置文件不作改动。仅首次添加生图档位时需要新开一个终端（此时才会向 CLI 配置写入该工具，而 CLI 仅在启动时读取配置）。
• 未提供生图分组的站点中该页为空，CLI 配置不作任何改动。1K 与 4K 档位之间的选择属于消费决策，LoongPort 不代为选择。

怎么升级

Windows Setup 安装版、macOS 版与 Linux AppImage 会自动检查更新：启动数秒后在后台查询一次，有新版本时在「设置 → 关于」中提示，点击即可下载、安装并重启。检查失败不会造成打扰（离线、无法连接 GitHub 的情况均属常见），也可随时手动点选「检查更新」。

Windows 免安装版不支持原地更新 —— 它无法替换正在运行的自身。该版本同样会提示新版本，但需回到 Releases 下载新的压缩包。这是免安装版的取舍：换得的是没有安装步骤、不会被安全软件拦截。

DeepSeek Harness（dsh）

LoongPort 提供 loongport npm Cordis bundle，可在 DeepSeek Harness（dsh）中使用已验证服务商。

dsh plugin --profile <profile> add loongport

安装后，在 Settings → LoongPort 选择服务商；需要账号时打开其自己的注册或登录页面，手动生成并粘贴 API Key，再选择 deepseek-v4-flash 或 deepseek-v4-pro 保存。默认服务商为 DeepSeek 官方 API，BestAPI 为已验证的中转站选项。完整安全边界、签名目录与 VeriDrop 的职责说明见 loongport.dev/zh/dsh。

浏览器授权不做自动化；高级自定义 endpoint 的 CLI 用法见官网。

支持范围

站点域名可自行填写，默认预置一个可用站点。三个平台提供同一套桌面版能力；切换 Codex 档位时关闭 ChatGPT 的方式，macOS 与 Windows 不同（macOS 发出退出请求、可以取消，Windows 直接结束进程）。

「AI CLI」一行指对话档位。 生图工具可安装至 codex、claude 与 gemini 三个 CLI ——「gemini 在做」指它尚不能作为对话档位的目标（配置写入形状尚未完成），并非完全未接入。

「在做」不是愿望清单。 gemini 与 grok 的档位映射表已经建全，缺的是各自的配置写入适配。如果你在运营其它类型的中转后端，欢迎提交 issue 评估接入。

充值与返利

LoongPort 本身免费，不经手付款、不从你的余额抽成。你充值的对象是中转服务商。

注册链接会附带我们的邀请码，我们可能因此从中转站获得返利。这不影响你的价格，域名可任意填写。两张表位于 src-tauri/src/relay/ 的 aff.rs 与 promo.rs。

上