Verboo Code 在 CI 中的用法：用 vbk_ API key 实现无头认证

你的 CI 流水线调用 verboo 时,就算配置了密钥,认证还是失败吗?在 Verboo Code v0.15.17 及更早版本中,这是预期行为:CLI 的启动认证关卡只认 OAuth 会话,所以一个完全有效的 vbk_ API key,在没有交互式终端的环境里根本用不上。v0.15.18 修复了这个问题。本文给出今天就能用的确切命令,所有内容都直接在 verbeux-ai/code 源码中核实过。

为什么普通的 Verboo Code 登录在 CI runner 里行不通?

因为它依赖打开浏览器。当你在有交互式终端的机器上运行 verboo 时,CLI 会检测到会话缺失,自动打开 code.verboo.ai 完成 OAuth。GitHub Actions runner、GitLab CI runner,或者任何一次性容器,既没有交互式终端也没有浏览器,这个流程根本没法完成。

源码里的一条注释直接说明了这个设计:"Verboo 认证关卡。有 TTY 时自动打开浏览器,无头模式下抛出明确错误"(src/main.tsx,由原始葡萄牙语注释翻译而来)。

Verboo Code 用哪个环境变量来实现无浏览器认证?

ANTHROPIC_API_KEY。不是 Router 文档里建议直接调用 HTTP 接口时使用的 VERBOO_API_KEY:它和 Claude Code 生态系统里其他地方使用 API key 的变量是同一个,也是 Verboo Code 启动关卡最先读取的那个。如果这个值以 vbk_ 前缀开头,CLI 就会把它当作有效的无头会话:

export ANTHROPIC_API_KEY="你的vbk_密钥"
verboo -p "运行测试套件并修复失败的部分" --output-format json

这个密钥不会拿去校验 /api/me,因为那个接口会拒绝 API key。它是通过 Authorization: Bearer 直接对路由端点 code.verboo.ai/router/v1/models 做校验的。这个端点选择记录在引入该功能的代码评审里(verbeux-ai/code 仓库的 PR #43):团队是在确认第一个端点不接受这类密钥之后,才换了端点。

我在哪里创建 vbk_ 密钥?

在 code.verboo.ai 的控制面板上,右上角的 "Create API key" 按钮会带你到密钥管理页面。每个密钥都绑定一个模型组,所以在把值粘到 CI 密钥里之前,先选好你平时就在用的那个组。

能不能不用固定密钥,继续用 OAuth 会话,同时又不在服务器上开浏览器?

可以。verboo auth login --headless 会跑完整的 OAuth 流程,不依赖那台机器上的浏览器:CLI 会打印一个 URL,你在任意其他设备上打开它,确认登录,再把授权码粘贴回服务器的终端。这正是团队自己描述为"适合服务器/CI"的方案,但和 API key 有一个重要区别:这里始终有一个人参与一次,所以它更适合持久化服务器或自托管 runner,而不是那种每次运行都从零诞生又销毁的一次性 runner。

方式	是否需要人工介入	最适合
ANTHROPIC_API_KEY=vbk_...	不需要,一次都不需要	一次性 runner(GitHub Actions、GitLab CI)
verboo auth login --headless	需要,一次,在另一台设备上	持久化服务器或自托管 runner

密钥错误或过期时,屏幕上会显示什么?

一条具体的信息,不是泛泛的登录提示:"API key inválida ou expirada"(API key 无效或已过期)。如果既没有 vbk_ 密钥,也没有 OAuth 会话,且终端没有 TTY,信息会变成 "Não autenticado no Verboo. Execute verboo /login em um terminal interativo antes de usar o modo headless."(未在 Verboo 完成认证,请在交互式终端中执行 verboo /login 后再使用无头模式)。这两句话在源码里(verbooStartupAuth.ts)就是这样精确写死的,还有单元测试保证两者不会互相混淆。

API key 认证会跳过什么我应该知道的检查吗?

会,而且是有意为之。服务条款确认流程和权益检查(用来确认你的订阅是否有效)都依赖只接受 OAuth 的接口。走 API key 这条路径时,Verboo Code 会跳过这两步,直接进入会话。对常见场景来说这是安全的,但如果你的流水线需要在条款变更或订阅到期时阻止执行,光靠这个密钥是不会自动做到的。