> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orbi.build/llms.txt
> Use this file to discover all available pages before exploring further.

# Opencode

# OpenCode provider

本文是 Pi 原生 OpenCode provider 的 Orbi 接入说明，属于
[provider 文档系列](https://github.com/orbi-build/orbi/issues/305)。以下事实于
**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 文档](https://opencode.ai/docs/zen/)为准。
2. 启动交互式 Pi，会话中执行 `/login`，选择 **OpenCode Zen** 并粘贴 API
   key。Pi 将其存入用户 auth 文件（权限 `0600`）。这是 API-key 登录，不是
   浏览器 OAuth 流程。
3. 或通过 gitignored 的环境文件交给 Orbi service：

   ```bash theme={null}
   mkdir -p .orbi
   printf '%s\n' 'OPENCODE_API_KEY=replace-me' > .orbi/env
   chmod 600 .orbi/env
   ```

   已安装的 Orbi systemd unit 会加载 `.orbi/env`。手动检查前先在当前 shell
   导出：

   ```bash theme={null}
   set -a; . .orbi/env; set +a
   ```

不打印凭据地检查 readiness：

```bash theme={null}
pi auth check --provider opencode --model deepseek-v4-flash-free --json
```

没有 key 时，Pi 0.85.1 实测返回 `credentials_not_configured`。检查成功只说明
凭据已配置，不说明账号仍有额度。不要在 transcript 中使用 `--credentials`。

## 目录与 Orbi 配置

`opencode` 已内置于 Pi catalog。本页使用以下命令核对目录：

```bash theme={null}
OPENCODE_API_KEY=present-but-not-a-real-key pi --offline --list-models opencode
```

这个 placeholder 只用于让 Pi 显示 catalog，**没有**用于真实请求。截至
2026-09-08，Pi 列出了以下 `opencode` model ID（上下文/输出限制由命令显示，
本文不把它们误称为额度承诺）：

```text theme={null}
big-pickle, claude-fable-5, claude-fable-5-1, claude-haiku-4-5,
claude-opus-4-5, claude-opus-4-6, claude-opus-4-7, claude-opus-4-8,
claude-opus-5, claude-sonnet-4, claude-sonnet-4-5, claude-sonnet-4-6,
claude-sonnet-5, deepseek-v4-flash, deepseek-v4-flash-free,
deepseek-v4-flash-vision-exp, deepseek-v4-pro, gemini-3-flash,
gemini-3.1-pro, gemini-3.5-flash, gemini-3.5-flash-lite, gemini-3.6-flash,
gemini-3.7-flash, gemini-3.8-flash, glm-5, glm-5.1, glm-5.2, glm-5.3,
glm-5.3-flash, gpt-5, gpt-5-codex, gpt-5-nano, gpt-5.1,
gpt-5.1-codex, gpt-5.1-codex-max, gpt-5.1-codex-mini, gpt-5.2,
gpt-5.2-codex, gpt-5.3-codex, gpt-5.4, gpt-5.4-mini, gpt-5.4-nano,
gpt-5.4-pro, gpt-5.5, gpt-5.5-pro, gpt-5.6-luna, gpt-5.6-sol,
gpt-5.6-terra, gpt-6-astra, grok-4.5, grok-4.6, grok-build-0.1,
kimi-k2.5, kimi-k2.6, kimi-k2.7-code, kimi-k3, ling-3.0-flash-fin-free,
mimo-v2.5-free, minimax-m2.5, minimax-m2.7, minimax-m3,
muse-spark-1.2, muse-spark-1.2-contributor-free, muse-spark-1.3,
muse-spark-1.3-contributor-free, nemotron-3-ultra-free,
nemotron-3.5-lightning-free, qwen3.5-plus, qwen3.6-plus
```

同一 Pi catalog 还提供独立的 `opencode-go` provider。除非账号是 OpenCode Go
账号，否则不要切换到它；两者的 model ID 和套餐不同。认证或刷新 catalog
后可再次执行 `pi --list-models opencode`。

最小 Orbi 配置如下，model ID 必须与 Pi 输出完全一致：

```toml theme={null}
pi_provider = "opencode"
pi_model = "deepseek-v4-flash-free"
# 不写 pi_providers
```

**此配置不要创建 `.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：

```bash theme={null}
pi --provider opencode --model deepseek-v4-flash-free --print \
  "Reply with the single word: ok"
```

## 额度、限流与实测边界

当前价格、免费 model、账号套餐、限流和重置时间以 OpenCode 的
[Zen 页面](https://opencode.ai/docs/zen/)和 [OpenCode Go
页面](https://opencode.ai/docs/go/)为准。它们不是 Pi catalog metadata，不能从
`contextWindow`、`maxTokens` 或 model 名称推导。

截至上述日期，本 worktree **没有可用的 OpenCode 账号**：

* 真实 OpenCode 推理请求：**未实测**；
* 额度消耗或剩余额度：**未测量**；
* 限流/429 响应和重置时间：**未实测**；
* 真实 Orbi Issue 交付和 PR：**未实测**。

因此本文不声称任何数字额度或重置时间。凭据错误表示认证/配置不正确；上游
额度或限流错误表示账号/服务状态。Orbi 不会静默重试或轮换 provider。保留失败
run 证据，再手动修改选择项。

## 最小 fallback

认证、额度或限流失败后，只改 provider 选择，并使用该 provider 已有的配置：

```diff theme={null}
-pi_provider = "opencode"
-pi_model = "deepseek-v4-flash-free"
+pi_providers = ".orbi/pi-providers.json"
+pi_provider = "local-qwen"       # 或 "z-ai"
+pi_model = "Qwen3.8-27B"          # 或 "glm-5.3-flash"
```

从 `templates/pi-providers/` 复制匹配模板，把 key 放进 `.orbi/env`（local Qwen
使用其文档中的 dummy key），再运行 provider 校验和一次真实 `pi --print`。切换
必须手动完成；它不会修复无效的 OpenCode key，也不会创建自动 fallback。