跳转到主要内容
用 OpenCode API key 配置 Pi 原生的 OpenCode provider，然后在 Orbi provider 设置中选择它。 本文是 Pi 原生 OpenCode provider 的 Orbi 接入说明，属于 provider 文档系列。以下事实于 2026-09-08 使用 Pi 0.85.1（pi --version）核对。OpenCode 的目录和套餐由 服务端控制，可能变化；每次部署前都应重新执行目录命令。

​
认证方式

Pi 0.85.1 将 opencode 作为 API key provider，而不是 OAuth provider。Pi 的 provider 文档把它映射到 OPENCODE_API_KEY 以及 auth.json 中的 opencode 键。该 key 是 OpenCode Zen/OpenCode 账号 key，不是 Orbi token，也不是 OPENAI_API_KEY。 按以下任一路径准备认证：
  1. 在 OpenCode 账号中创建/复制 key，以官方 OpenCode Zen 文档为准。
  2. 启动交互式 Pi，会话中执行 /login，选择 OpenCode Zen 并粘贴 API key。Pi 将其存入用户 auth 文件（权限 0600）。这是 API-key 登录，不是 浏览器 OAuth 流程。
  3. 或通过 gitignored 的环境文件交给 Orbi service：
    已安装的 Orbi systemd unit 会加载 .orbi/env。手动检查前先在当前 shell 导出：
不打印凭据地检查 readiness：
没有 key 时，Pi 0.85.1 实测返回 credentials_not_configured。检查成功只说明 凭据已配置，不说明账号仍有额度。不要在 transcript 中使用 --credentials。

​
目录与 Orbi 配置

opencode 已内置于 Pi catalog。本页使用以下命令核对目录：
这个 placeholder 只用于让 Pi 显示 catalog，没有用于真实请求。Pi 的 catalog 会随上游 catalog 快照变化，因此请重新运行上面的命令，查看 Pi 当前提供的 model ID。 同一 Pi catalog 还提供独立的 opencode-go provider。除非账号是 OpenCode Go 账号，否则不要切换到它；两者的 model ID 和套餐不同。认证或刷新 catalog 后可再次执行 pi --list-models opencode。 最小 Orbi 配置如下，model ID 必须与 Pi 输出完全一致：
此配置不要创建 .orbi/pi-providers.json。 Pi 已经拥有 provider、endpoint、 API 类型、model metadata 和 API-key 映射。重复定义 opencode 可能遮蔽或冻结 原生 catalog。只有 Pi 没有原生提供的 provider（例如 Orbi 的 local-qwen 或 z-ai 模板）才使用 pi_providers 文件。 派发 Issue 前，用真实账号和选择的 model 执行一次不含秘密的 smoke：

​
额度、限流与实测边界

当前价格、免费 model、账号套餐、限流和重置时间以 OpenCode 的 Zen 页面和 OpenCode Go 页面为准。它们不是 Pi catalog metadata，不能从 contextWindow、maxTokens 或 model 名称推导。 截至上述日期，本 worktree 没有可用的 OpenCode 账号：
  • 真实 OpenCode 推理请求：未实测；
  • 额度消耗或剩余额度：未测量；
  • 限流/429 响应和重置时间：未实测；
  • 真实 Orbi Issue 交付和 PR：未实测。
因此本文不声称任何数字额度或重置时间。凭据错误表示认证/配置不正确；上游 额度或限流错误表示账号/服务状态。Orbi 不会静默重试或轮换 provider。保留失败 run 证据，再手动修改选择项。

​
最小 fallback

认证、额度或限流失败后，只改 provider 选择，并使用该 provider 已有的配置：
从 templates/pi-providers/ 复制匹配模板，把 key 放进 .orbi/env（local Qwen 使用其文档中的 dummy key），再运行 provider 校验和一次真实 pi --print。切换 必须手动完成；它不会修复无效的 OpenCode key，也不会创建自动 fallback。