使用 OAuth PKCE 登录开桥 ​

开桥支持通过 OAuth 2.0 Authorization Code + PKCE 将账号授权给本地 Agent。使用这种方式时，无需创建、复制或保存开桥 API Key：Agent 会打开浏览器完成授权，并使用短期 Access Token 调用模型；插件会在 Token 过期前自动刷新。

目前支持以下 Agent：

授权流程 ​

这些集成使用相同的核心流程：

1. Agent 生成一次性的 PKCE code_verifier 和对应的 S256 code_challenge。
2. 浏览器打开开桥授权页，由用户确认账号和授权范围。
3. 开桥将一次性 Authorization Code 返回到 127.0.0.1 的临时回调端口。
4. 插件使用 Authorization Code 和 code_verifier 换取 Access Token 与 Refresh Token。
5. Agent 使用 Access Token 调用开桥，并在过期前自动刷新 Token。

这些官方包默认只请求以下权限：

• inference:invoke：调用模型。
• offline_access：在 Access Token 过期后刷新登录状态。

OpenClaw ​

安装插件并启动登录：

openclaw plugins install @openqiao/openclaw-plugin
openclaw models auth login --provider openqiao

在登录方式中选择 开桥 OAuth，然后在浏览器完成授权。返回 OpenClaw 后，选择一个 openqiao/... 模型即可使用。

OpenClaw 会将令牌保存在自己的认证配置中，并自动保存刷新后轮换的 Refresh Token。模型列表会动态发现，并把最近一次有效目录缓存到 ~/.cache/openclaw/openqiao/models.json。

Codex CLI 与 Codex App ​

全局安装认证工具：

npm install -g @openqiao/codex-oauth

配置 Codex 并登录：

openqiao-codex-auth install
openqiao-codex-auth login

完成后重启 Codex CLI 或 Codex App。install 会将开桥配置为 Responses Provider，并下载当前支持 Responses 协议的模型目录，但不会修改已有的模型名称。已有 ~/.codex/config.toml 会先备份。

可以使用以下命令检查或清除登录状态：

openqiao-codex-auth status
openqiao-codex-auth logout

如需完整移除集成，请先恢复 Codex 配置，再卸载 npm 包：

openqiao-codex-auth uninstall
npm uninstall -g @openqiao/codex-oauth

DeepSeek Harness ​

完整安装、代理和模型配置说明请参阅 DeepSeek Harness 接入开桥。

将开桥插件安装到 DSH Web Profile，然后启动 DSH：

dsh plugin --profile web add @openqiao/dsh-plugins
dsh web

在 DSH Web 中执行：

/openqiao login

浏览器授权完成并显示 开桥 connected 后，返回 DSH，在模型选择器中选择 开桥 · DeepSeek V4 Pro 或 开桥 · DeepSeek V4 Flash。

登录状态管理命令：

/openqiao status
/openqiao logout

OpenCode ​

在 OpenCode 配置中添加 OAuth 插件：

{
  "$schema": "https://opencode.ai/config.json",
  "plugin": ["@openqiao/opencode-oauth"]
}

然后执行：

opencode auth login -p openqiao -m "开桥 OAuth (PKCE)"

也可以在 OpenCode 中运行 /connect，依次选择 开桥 和 开桥 OAuth (PKCE)。完成授权后运行 /models，选择开桥模型。

OpenCode 会使用自己的凭据存储 Access Token 与 Refresh Token。模型目录按模型匹配 Anthropic Messages、OpenAI Responses 或 Chat Completions，并缓存到 ~/.cache/opencode/openqiao/models.json。

Pi ​

使用 Pi 安装扩展：

pi install npm:@openqiao/pi-openqiao-oauth

启动 Pi 后登录：

/login openqiao

浏览器授权完成后返回 Pi，运行 /model 并选择开桥模型。Pi 会在自己的 Provider 凭据存储中管理 Access Token 与 Refresh Token，并把模型目录缓存到 ~/.pi/agent/models-store.json。

Hermes Agent ​

完整安装、默认供应商配置、远程授权和故障排查请参阅 Hermes Agent 接入开桥。插件源码与其他安装方式见 开桥/hermes-plugin。

安装并启用插件：

hermes plugins install 开桥/hermes-plugin --enable
hermes gateway restart

没有运行 Gateway 时，重新启动 Hermes 即可；由 PM2 等进程管理器托管的 Gateway 请在对应管理器中重启。

登录并查看状态：

hermes auth add openqiao
hermes auth status openqiao

浏览器打开开桥授权页后，选择账户与计费方式并批准授权。OAuth 无需手动创建 API Key，但模型调用仍按所选账户和计费方式结算。

授权后运行 hermes model，选择插件的开桥供应商和模型，或显式指定：

hermes --provider openqiao -m google/gemini-2.5-flash-lite

发送一条测试消息并确认收到模型回复。openqiao 是 provider 名，模型必须使用完整 vendor/model slug，不要添加 openqiao/ 前缀。从 API Key 自定义端点迁移时，请将 provider 从 custom 切换为 openqiao，不要只替换凭据。

Hermes 将 Access Token 与 Refresh Token 保存在自己的凭据池中，通过凭据锁串行化 Refresh Token 轮换。插件读取实时模型目录，过滤纯图片/视频生成模型；有效但未列入目录的 slug 需要 Hermes 支持 ProviderProfile.model_listing_authoritative，最终仍以 API 权限和响应为准。

认证管理命令：

hermes auth list openqiao
hermes auth refresh openqiao
hermes auth logout openqiao

凭据与安全 ​

• 官方生产环境使用预置的 Native Public Client ID，不在插件包中保存 Client Secret。
• 回调监听器只绑定到 127.0.0.1 的临时端口，并校验 OAuth state。
• Access Token 过期前会自动刷新；服务端返回新的 Refresh Token 时，插件会保存轮换后的 Token。
• 不要把 OAuth Token 手动复制到模型配置、环境变量、日志或截图中。
• 不再使用某个 Agent 时，请同时在 Agent 中退出登录，并在开桥的已授权应用中撤销授权。

常见问题 ​

浏览器没有自动打开 ​

先复制终端中显示的授权链接到浏览器。Codex 还可以在启动登录前设置：

export OPENQIAO_OAUTH_NO_BROWSER=1
openqiao-codex-auth login

浏览器授权后，终端仍在等待 ​

OAuth 回调使用临时的 127.0.0.1 端口。确认防火墙没有阻止本地回环连接，并确认授权浏览器能访问运行 Agent 的回调端口。远程或容器环境不能假设浏览器的 127.0.0.1 就是 Agent 所在机器；OpenClaw 支持复制完整 Redirect URL 回终端；Hermes 请使用 --no-browser 并转发本次实际回调端口，参阅远程授权说明。

登录成功但看不到开桥模型 ​

重新打开 Agent 的模型选择器，并确认模型目录接口可访问。OpenClaw、OpenCode 和 Pi 会保留最近一次有效模型缓存；DeepSeek Harness 当前提供两个预置模型入口；Codex 的模型目录由 openqiao-codex-auth install 写入，模型目录更新后可以重新执行该命令。

Hermes 使用实时目录，不采用上述磁盘目录缓存。若提示 Unknown provider，先运行 hermes plugins list 确认插件安装和启用状态，并重启 Hermes / Gateway；若有效 slug 因不在目录而被拒绝，请更新 Hermes 和插件，详见 Hermes 故障排查。