团队使用 Codex 和 Claude Code，API Key 和模型权限怎么管？我开源了 Zentrola

一个人使用 AI Coding 工具时，事情很简单：申请一个 API Key，填进 Codex 或 Claude Code，然后开始工作。

但当使用者从一个人变成一个团队，原本简单的配置问题很快就会变成管理问题：真实 API Key 要不要发给每个人？新成员应该能用哪些模型？成员离职后如何撤销权限？上游服务商发生故障时，是否要通知所有人临时修改配置？月底看到一笔模型账单，又该怎么知道是谁、通过哪个模型产生的？

很多团队最初会选择共享 Key，再加一个简单的反向代理。这种方式能解决“请求如何转发”，却很难回答“谁可以调用什么、请求最终去了哪里、发生问题后怎么追踪”。

这正是我做 Zentrola 的出发点。

Zentrola 1.0.0 现已开源：

• GitHub：https://github.com/zentrola/zentrola

• Marketplace：https://github.com/zentrola/zentrola-marketplace

我不想再做一个普通的模型代理

模型代理已经有很多了。如果 Zentrola 只是把 OpenAI 或 Anthropic 请求转发到另一个地址，它解决的问题仍然有限。

我更关心的是：当 AI Coding 成为团队基础设施以后，能不能在不改变开发者习惯的前提下，为它补上一层治理能力？

所以 Zentrola 的位置是在 Codex、Claude Code 等客户端与企业模型订阅之间。开发者继续使用自己熟悉的工具，平台负责管理身份、权限、凭据、模型、路由、用量和操作记录。

Codex / Claude Code / OpenAI 兼容客户端
                    │
               Virtual Key
                    ▼
┌──────────────── Zentrola ────────────────┐
│ 身份认证 → Group 权限 → 逻辑模型         │
│          → Provider 路由 → Usage 记录    │
└──────────────────────────────────────────┘
                    │
        OpenAI / Anthropic / 兼容服务商
                    │
             PostgreSQL / Redis

这套设计主要想解决四个问题。

问题一：真实 Provider Key 不应该在团队里到处流转

共享真实 API Key 是最省事的开始，也往往是最难收拾的结局。

密钥被写进本地配置、脚本甚至聊天记录以后，管理员很难知道它已经流转到了哪里。一名成员离开团队，通常也不能只撤销这个人的权限，只能轮换整把 Key，再通知所有使用者更新配置。

在 Zentrola 中，研发人员拿到的是成员独立的 Virtual Key，而不是服务商的真实 Credential。真实凭据由平台统一保存，使用 Master Key 加密后写入数据库。

成员离职、权限变化或密钥泄漏时，管理员只需要撤销对应的 Virtual Key，不必影响其他人，也不必重新分发上游 Key。

管理面和调用面也被刻意分开：管理员使用 Admin JWT 访问管理接口，研发成员使用 Virtual Key 调用 Gateway。Admin JWT 不能直接调用模型，Virtual Key 也不能进入管理员接口。

问题二：团队权限不应该等同于“有没有拿到 Key”

拿到同一把上游 Key 的人，通常就拥有了相同的模型能力。但实际团队里，不同角色往往需要不同权限。

假设一个团队有后端组、前端组和外部协作成员：

• 后端组可以使用两个代码模型；

• 前端组可以使用代码模型和图像模型；

• 外部成员只能使用一个受限模型；

• 所有人都不应该接触真实 Provider Credential。

Zentrola 通过“成员—Group—逻辑模型”建立授权关系。管理员把成员加入不同 Group，再给 Group 配置模型白名单。成员调用 /v1/models 时，只能看到自己真正有权使用的逻辑模型。

这样，权限归属的是成员和团队角色，而不是一把被多人共享的密钥。

问题三：更换模型或服务商，不应该让所有人重新配置客户端

如果客户端直接填写某个服务商的物理模型名称，那么更换服务商、调整模型版本或更新 Endpoint 时，往往意味着逐台修改客户端配置。

Zentrola 在客户端和上游模型之间增加了“逻辑模型”这一层。客户端只使用团队内部约定的模型编码，逻辑模型背后可以配置多个带优先级的 Provider Model 映射。

例如，研发人员始终调用 coding-model。至于它当前映射到哪个服务商、哪个物理模型、使用哪份 Credential，由管理员在后台维护。调整完成后，客户端不需要跟着变化。

当首选路由暂时不可用时，Gateway 还可以按配置继续尝试候选路由。这不仅减少了故障期间的人工沟通，也避免把某一家服务商的变化直接传导给所有开发者。

问题四：调用发生以后，需要知道“谁用了什么”

团队共用一把 Key 时，用量通常只能看到一个总数。一旦出现费用异常、模型不可用或权限争议，很难继续向下追踪。

Zentrola 会把调用用量关联到成员、逻辑模型、服务商和 Credential，并在管理界面提供 Usage 仪表盘。重要的管理操作会进入 Operation Log，用来回答“谁在什么时候修改了什么”。

调用返回的 X-Trace-ID、X-Span-ID 或 request ID 还可以关联后端日志。排障时，不需要为了定位一次请求就在群里转发 Credential、prompt 或完整模型输出。

Codex 和 Claude Code 可以继续照常使用

治理平台不应该迫使开发者更换工具。对大多数客户端来说，接入 Zentrola 只需要替换 Base URL 和 API Key。

OpenAI 兼容客户端可以这样配置：

export OPENAI_BASE_URL='https://<gateway-host>/v1'
export OPENAI_API_KEY='<virtual-key>'

Claude Code 和 Anthropic 兼容客户端则使用：

export ANTHROPIC_BASE_URL='https://<gateway-host>/anthropic'
export ANTHROPIC_API_KEY='<virtual-key>'

Zentrola 当前提供 OpenAI Compatible 和 Anthropic Compatible 两组入口，支持 Models、Chat Completions、Responses、Images、Messages、Count Tokens 等接口，也支持 SSE 流式响应和工具调用。

Gateway 会优先选择同协议上游，并在需要时进行协议转换。因此，团队不必先把所有人的客户端统一成同一种，Codex、Claude Code 和其他兼容 SDK 可以接入同一套治理体系。

模型目录同步目前为 OpenAI、Google、DeepSeek、智谱 AI、月之暗面、通义千问和 xAI 提供专用适配器；其他 OpenAI 或 Anthropic 兼容服务商也可以手动配置。

使用 Docker Compose 快速启动

Zentrola 提供独立发布包和 Docker Compose 部署方式。使用 Compose 时，先修改 compose.yaml 顶部的四项配置：

• PostgreSQL 密码

• Redis 密码

• Admin JWT Secret

• Master Key

然后启动完整服务栈：

docker compose up -d

默认情况下，Admin Web 位于 http://127.0.0.1:9528，Backend 位于 http://127.0.0.1:9527。首次打开 Admin Web 时需要创建第一位管理员，系统没有默认账号和密码。

进入管理界面后，完成一条最小调用链路需要：

1. 创建服务商并添加 Provider Credential；

2. 测试 Credential，同步或手动添加 Provider Model；

3. 创建逻辑模型并配置映射；

4. 创建成员和 Group，为 Group 授权模型；

5. 为成员签发 Virtual Key。

然后就可以查看该成员有权使用的模型：

curl http://127.0.0.1:9527/v1/models \
  -H "Authorization: Bearer <virtual-key>"

生产部署时，请使用 HTTPS，不要将 PostgreSQL 和 Redis 暴露到公网。数据库和 Master Key 必须作为同一个恢复集备份；Master Key 丢失后，已有的 Provider Credential 将无法解密。

技术实现与当前边界

Zentrola 后端使用 Go，按照 domain、application、infrastructure 和 transport 分层；HTTP 路由基于 chi，数据存储使用 PostgreSQL 17。Redis 用于 Gateway 缓存和短期路由冷却状态，暂时不可用时 Gateway 会回退到 PostgreSQL。

管理界面使用 Vue 3、TypeScript 和 Vite，提供中英文界面。项目同时包含数据库迁移、健康检查、独立二进制发布、Docker Compose、CI、安全检查和 Playwright 测试。

1.0.0 聚焦的是 Model Governance MVP，目前已经形成闭环的能力包括：

• 管理员、成员、Group 和逻辑模型管理；

• Provider、Endpoint、Credential 和模型映射管理；

• Virtual Key 签发、有效期控制和撤销；

• OpenAI 与 Anthropic 兼容 Gateway；

• 协议转换、流式响应、工具调用和服务商故障切换；

• Usage 仪表盘和 Operation Log；

• 中英文 Admin Web、发布包和 Docker Compose 部署。

我也希望把当前边界说清楚：Cost、Budget、计费、SSO、OIDC、LDAP、SCIM、Enterprise Knowledge、Skill Registry、Managed MCP 和完整高可用方案都还没有形成闭环。

所以，当前版本更适合团队验证以成员和 Group 为单位的模型治理方案。正式用于生产环境之前，仍然需要根据项目文档评估现有能力、部署方式和安全边界是否符合组织要求。

写在最后

我越来越确定，AI Coding 在团队里真正难管的并不是某一次模型调用，而是调用背后的身份、权限、凭据、路由和归属。

Zentrola 想做的，就是在不打断开发者工作习惯的前提下，把这一层补起来。它现在还只是 1.0.0，也有很多能力需要继续完善，但最基本的模型治理链路已经可以跑通。

如果你所在的团队也在面对共享 API Key、模型权限或多服务商接入问题，欢迎试用 Zentrola，也欢迎通过 Issue 和 Pull Request 一起完善它。

• GitHub：https://github.com/zentrola/zentrola

• Marketplace：https://github.com/zentrola/zentrola-marketplace

• 快速开始：https://github.com/zentrola/zentrola/blob/master/docs/getting-started.zh-CN.md

• 客户端接入：https://github.com/zentrola/zentrola/blob/master/docs/client-configuration.zh-CN.md

• 参与贡献：https://github.com/zentrola/zentrola/blob/master/CONTRIBUTING.zh-CN.md

Zentrola 使用 Apache License 2.0 开源。