> ## 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. # Providers # Pi Provider 模板 Issue #309 在 [`templates/pi-providers`](https://github.com/orbi-build/orbi/tree/main/templates/pi-providers) 提供每家 provider 一份完整的 `pi_providers` 文件。每份文件都是 Pi `models.json` 形状的有效 JSON：可以把整份复制为 `.orbi/pi-providers.json`，也可以把其中唯一条目复制到已有文件的 `providers` 对象中。然后在 `orbi.toml` 中只设置两个选择项： ```toml theme={null} pi_providers = ".orbi/pi-providers.json" pi_provider = "z-ai" pi_model = "glm-5.3-flash" ``` ## 清单 | Provider | 模板 | 环境变量 | 模型 | 状态 | #305 链接 | | --------------------- | ---------------------------- | ---------------------- | ------------------------------------ | --------------------------------------------- | ----------------------------------------------------- | | Google Gemini | `gemini.json` | `GOOGLE_API_KEY` | `gemini-3.8-flash` | 2026-09-04 实测：Pi 全链路 7 秒通过 | [#305](https://github.com/orbi-build/orbi/issues/305) | | z.ai GLM | `z-ai.json` | `ZAI_API_KEY` | `glm-5.3-flash` | 2026-09-04 实测：真实任务 #303 到达 PR #304 | [#305](https://github.com/orbi-build/orbi/issues/305) | | OpenRouter 免费层 | `openrouter.json` | `OPENROUTER_API_KEY` | `google/gemma-4-31b-it:free` | 未实测；不承诺免费目录持续可用 | [#305](https://github.com/orbi-build/orbi/issues/305) | | DeepSeek | `deepseek.json` | `DEEPSEEK_API_KEY` | `deepseek-chat` | 未实测 | [#305](https://github.com/orbi-build/orbi/issues/305) | | xAI | `xai.json` | `XAI_API_KEY` | `grok-4.20-0309` | 已根据 xAI 文档核对模型 ID；未测试额度 | [#305](https://github.com/orbi-build/orbi/issues/305) | | Groq 免费档 | `groq.json` | `GROQ_API_KEY` | `groq/compound` | 2026-09-04 核对 Free Plan 限流；真实请求/usage/429 未实测 | [#305](https://github.com/orbi-build/orbi/issues/305) | | 本地 Qwen | `local-qwen.json` | 无（dummy key `local`） | `Qwen3.8-27B` | 本地零成本示例；需要本地 OpenAI-compatible server | [#305](https://github.com/orbi-build/orbi/issues/305) | | Cloudflare Workers AI | `cloudflare-workers-ai.json` | `CLOUDFLARE_API_TOKEN` | `@cf/meta/llama-3.1-8b-instruct-fp8` | 托管免费额度；必须在账号中核对额度 | [#318](https://github.com/orbi-build/orbi/issues/318) | 模板出现在清单中不代表承诺额度、可用性、速度或模型支持。`未实测` 是有意保留的状态。 ## 接入一家新 provider 1. 复制最接近的模板并设置一个 provider id。`baseUrl`、`api`、`apiKey` 和非空 `models` 列表必须一起保留。选择的 `pi_model` **必须精确等于**某个 `models[].id`。 2. OpenAI-compatible endpoint 使用 `openai-completions`。Google Gemini 使用 `google-generative-ai`，其 `baseUrl` 保持为 `https://generativelanguage.googleapis.com/v1beta`。 3. 真实 key 放在 `.orbi/env`（gitignored、权限 `600`），提交的 JSON 只使用 `$VAR` 或 `${VAR}` 引用： ```bash theme={null} mkdir -p .orbi printf '%s\n' 'ZAI_API_KEY=replace-me' > .orbi/env chmod 600 .orbi/env ``` 已安装的 `orbi@.service` 通过 `EnvironmentFile` 加载此文件；key 绝不能进入 Git 或模板。字面量 key 只是降级方案：文件仍应 gitignored，并且要接受它可能通过本地文件和进程工具泄漏的风险。 4. 手动 tick 时 systemd 不会加载 `.orbi/env`。先导出变量，或在当前 shell 中 source： ```bash theme={null} set -a . .orbi/env set +a PYTHONPATH=src python3 -m orbi.runner --config orbi.toml ``` 5. `orbi.toml` 只选择 provider/model，不维护注释掉的 provider 配置块。真实任务前运行 loader/runner 校验；选中的 provider、model、endpoint、API 或 key 引用不正确时会 fail fast。 ### `thinkingLevelMap` 不要为 provider 猜测完整映射。Gemini 模板的已知安全写法正是 `{"off": null}`：其他 thinking level 使用 provider 默认映射。若把所有 level 都映射成 `null`，可能发送 provider 不支持的值并得到 `400`。其他 provider 若没有经过 Pi provider 契约验证，应省略此字段。 ### Google Gemini：AI Studio 免费层 在 Google 的 [AI Studio API key 页面](https://aistudio.google.com/app/apikey) 创建 API key。key 只保存在本机：提交的模板只引用 `GOOGLE_API_KEY`，不要把真实值写入 Git、Issue、PR 或 journal。 1. 在 AI Studio 创建或选择 key，然后写入 Orbi 使用的 gitignored 环境文件： ```bash theme={null} mkdir -p .orbi printf '%s\n' 'GOOGLE_API_KEY=replace-me' > .orbi/env chmod 600 .orbi/env ``` 已安装的 systemd unit 会加载 `.orbi/env`。手动 tick 时，先按[上手指南](/zh/getting-started#path-b-a-pi_providers-file-orbi)导出变量。 2. 将 [`templates/pi-providers/gemini.json`](https://github.com/orbi-build/orbi/blob/main/templates/pi-providers/gemini.json) 复制为 `.orbi/pi-providers.json`。其中完整的选中条目如下： ```json theme={null} { "providers": { "google": { "baseUrl": "https://generativelanguage.googleapis.com/v1beta", "api": "google-generative-ai", "apiKey": "$GOOGLE_API_KEY", "models": [ { "id": "gemini-3.8-flash", "name": "Gemini 3.8 Flash", "contextWindow": 1048576, "maxTokens": 65536, "thinkingLevelMap": {"off": null} } ] } } } ``` 3. 在 `orbi.toml` 中选择精确的 provider 和 model： ```toml theme={null} pi_providers = ".orbi/pi-providers.json" pi_provider = "google" pi_model = "gemini-3.8-flash" ``` `api`、`baseUrl`、model ID 和 `$GOOGLE_API_KEY` 引用都是已验证模板的一部分。除非重新核实当前 Pi/Gemini 契约，否则保持 Gemini 的 `thinkingLevelMap` 为 `{"off": null}`；把所有 thinking level 都映射为 `null` 可能导致上游 `400`。 #### 免费层限流与实测表现 截至 **2026-09-04** 核实，AI Studio Gemini API 免费层按 RPM、RPD、TPM 限流。官方[限流页面](https://ai.google.dev/gemini-api/docs/rate-limits)是动态页面，因此本文不抄写会变化的宣传数字。该账号真实的每日 RPD/TPD 上限**未测量**，应标为**未实测**，不能理解为不限量。 本机使用 provider `google` 和 model `gemini-3.8-flash` 的真实 Pi 请求约 15 秒起跑。burst 后上游返回 HTTP `429`，消息为 `You exceeded your current quota`；约 50 分钟后再次返回 HTTP `200`。这条有日期的观察说明是暂时性限流，不能证明 key 无效，也不能证明每日额度已耗尽。它只是一个账号的证据，不是额度保证。 Orbi 不会在 session 中静默重试或切换 provider。保留失败 run 的证据，等待暂时性限流恢复，或在下一次运行手动选择另一家已配置的 provider： ```toml theme={null} pi_providers = ".orbi/pi-providers.json" pi_provider = "z-ai" # 或清单中的其他 provider pi_model = "glm-5.3-flash" ``` 替换 provider 文件和匹配的环境变量，再次验证精确的 provider/model/key，然后执行一次真实 `pi --print` 检查。切换必须手动完成；[#313](https://github.com/orbi-build/orbi/issues/313)规划的按 provider 自动轮换尚不是当前行为。 ### z.ai GLM：体验/免费额度 如果 z.ai 账号有体验或免费额度，可使用这条路径。z.ai 提供 OpenAI-compatible API；Orbi 模板使用直连 endpoint `https://api.z.ai/api/paas/v4` 和 Pi 的 `openai-completions` API。key 获取流程以 z.ai 的 [API 快速开始](https://docs.z.ai/guides/overview/quick-start) 和 [API key 管理页](https://z.ai/manage-apikey/apikey-list)为准。页面可能变化；不要把 key 写入仓库、Issue、PR 或 journal。 1. 在 z.ai 控制台创建 API key，然后放入本地 gitignored 环境文件： ```bash theme={null} mkdir -p .orbi printf '%s\n' 'ZAI_API_KEY=replace-me' > .orbi/env chmod 600 .orbi/env ``` systemd service 会通过 `EnvironmentFile` 加载该文件；手动 tick 不会加载。手动运行前先执行 `set -a; . .orbi/env; set +a`，再运行[上手指南的手动 tick 命令](/zh/getting-started#6-run-one-tick-manually)。 2. 将 [`templates/pi-providers/z-ai.json`](https://github.com/orbi-build/orbi/blob/main/templates/pi-providers/z-ai.json) 复制为 `.orbi/pi-providers.json`，或复制其中的 provider 条目。选择精确的 ID： ```toml theme={null} pi_providers = ".orbi/pi-providers.json" pi_provider = "z-ai" pi_model = "glm-5.3-flash" ``` 当前完整的 `models` 条目是： ```json theme={null} { "id": "glm-5.3-flash", "name": "GLM 5.3 Flash", "contextWindow": 131072, "maxTokens": 32768 } ``` `reasoning` 是可选的 Pi model catalog 字段，用于表示模型是否支持 reasoning；`thinkingLevelMap` 将 Pi thinking level 映射为 provider 特定值。已提交的 z.ai 模板有意省略这两个字段：在没有经过 Pi/z.ai 契约核实前，本文不宣称 z.ai 的 reasoning 或 thinking 映射。不要把 Gemini 的 `{"off": null}` 映射复制给 z.ai。 3. 派发任务前验证条目。Runner 的 `_load_pi_providers` 会校验 provider、精确 model ID、endpoint/API 和非空 `ZAI_API_KEY`，但不会测试或承诺额度是否可用。 #### 已知的免费额度边界 * \*\*2026-09-04 已核实：\*\*使用 `glm-5.3-flash` 的真实 Orbi 交付从 Issue [#303](https://github.com/orbi-build/orbi/issues/303) 完成到 commit [`b81f77a`](https://github.com/orbi-build/orbi/commit/b81f77a)，并到达 PR [#304](https://github.com/orbi-build/orbi/pull/304)。这证明一次成功运行，不是额度保证。 * 本指南使用的材料中，z.ai 没有静态公布统一的体验/免费上限。确切额度、重置时间、并发和模型可用性取决于账号及 z.ai 当前政策；**本文未实测**。 * 本指南没有对耗尽或限流响应做受控测量；**限流表现：未实测**。以上游 HTTP 认证/限流错误为准，不要编造数字或增加重试循环。 #### 额度用尽后的切换路径 Orbi 不提供自动 fallback。保留 `orbi.toml` 中的选择字段，但要把 `pi_provider` 和 `pi_model` 改为[清单](#清单)中另一 provider 的匹配值；同时替换 provider 文件和 key，然后重新验证。例如切换到已有的 OpenRouter 模板及其选中模型： ```toml theme={null} pi_providers = ".orbi/pi-providers.json" pi_provider = "openrouter" pi_model = "google/gemma-4-31b-it:free" ``` 复制 [`openrouter.json`](https://github.com/orbi-build/orbi/blob/main/templates/pi-providers/openrouter.json)，在 `.orbi/env` 设置 `OPENROUTER_API_KEY`，派发前执行一次真实 `pi --print` 检查。OpenRouter 的 `z-ai/glm-5.2:free` 是另一条 provider 路径；本文**未实测也不承诺**它的可用性和额度。 ### Cloudflare Workers AI Cloudflare 的 OpenAI-compatible endpoint 按账号区分。复制 [`cloudflare-workers-ai.json`](https://github.com/orbi-build/orbi/blob/main/templates/pi-providers/cloudflare-workers-ai.json)，把 `baseUrl` 中的 `REPLACE_WITH_ACCOUNT_ID` 换成 Cloudflare Account ID，并创建同时具有 `Workers AI - Read` 和 `Workers AI - Edit` 权限的 API token（Cloudflare REST API 文档要求这两个权限）。token 放在 `.orbi/env`： ```bash theme={null} printf '%s\n' 'CLOUDFLARE_API_TOKEN=replace-me' >> .orbi/env chmod 600 .orbi/env ``` 在 `orbi.toml` 中选择： ```toml theme={null} pi_providers = ".orbi/pi-providers.json" pi_provider = "cloudflare-workers-ai" pi_model = "@cf/meta/llama-3.1-8b-instruct-fp8" ``` 模型 ID 来自 Cloudflare 当前的 [Workers AI 模型目录](https://developers.cloudflare.com/workers-ai/models/llama-3.1-8b-instruct-fp8/)，endpoint 路径来自 [Workers AI 配置文档](https://developers.cloudflare.com/workers-ai/configuration/)。Cloudflare [官方定价页](https://developers.cloudflare.com/workers-ai/platform/pricing/)说明每天免费 **10,000 Neurons**，在 **00:00 UTC** 重置（信息核对日期：2026-09-04）。超过免费额度后，若未启用计费，后续操作会失败。额度和价格可能变化，运行前请重新查看官方页面。 #### 实测一个 Orbi 任务的消耗 派发一个 Issue 前、PR 打开后，分别记录 Workers AI 账号的 Neurons 使用量（必须是同一 UTC 日）。任务消耗为 `after - before`；保留 dashboard/API 的 UTC 时间戳、模型、Issue 和 PR URL，但不要保留 token。Orbi journal 只能证明选中了 provider/model，不能代替 Neurons 计量。**本仓库尚未使用带 Cloudflare 账号的真实 Orbi 任务；真实请求和 Neurons 消耗未实测，不得推断或编造。** ```text theme={null} journal: provider=cloudflare-workers-ai model=@cf/meta/llama-3.1-8b-instruct-fp8 run_id= Cloudflare Workers AI usage: before= neurons at , after= neurons at , delta= PR: https://github.com/OWNER/REPO/pull/ ``` #### 托管服务与本地 Qwen 的定位 Workers AI 是托管服务：Cloudflare 提供推理服务和账号 Neurons 额度，适合没有高性能 GPU 的机器，但依赖网络、账号额度和 Cloudflare 的模型可用性。`local-qwen` 是自托管：不消耗 provider 额度，请求发往本地 OpenAI-compatible server，但操作者需要提供硬件、模型运行时和电力。轻量托管执行可选 Cloudflare；重视数据不出机和本地可控可用性时选本地 Qwen。 ### 本地 provider 本地 OpenAI-compatible server 仍需要非空的 `apiKey` 字段才能通过 provider 形状校验；本地模板使用无秘密的 dummy 值 `local`。模型 id 必须与 server 宣告的 id 一致（llama.cpp 可用 `--alias` 设置）。 ## Codex OAuth：使用 ChatGPT/Codex 订阅额度 这条路径使用 Pi 原生的 `openai-codex` provider 和 OAuth 凭据。**不使用 `OPENAI_API_KEY`，也不需要第二份 `pi_providers` JSON**。它消耗的是订阅/Codex 额度，不是 OpenAI API 账单。 ### 第一次登录：必须按这个顺序 1. 启动交互式 Pi 会话：`pi`。 2. 在 Pi 提示符中执行 **`/login codex`**。 3. 在浏览器完成 Codex OAuth 授权。 4. 回到 Pi，用当前 Pi CLI 实际支持的命令检查登录： ```bash theme={null} pi auth check --provider openai-codex --model gpt-5.6-luna --json ``` 成功时应报告 `"status":"ready"` 和 `"authType":"oauth"`。该命令默认会刷新过期 OAuth 凭据；不要在共享终端或 transcript 中使用 `--credentials`。 5. 检查成功后，再配置 Orbi 并运行真实 Issue。 ### 最小 Orbi 配置 如果存在 `pi_providers`，请删除；保持它**未设置**。不要复制或创建 `openai-codex` provider 条目。Pi 从自己的 `models.json` 提供 catalog，Orbi 的 per-run agent 目录复用 Pi 原生 auth。 ```toml theme={null} source_repos = ["OWNER/YOUR-REPO"] # Orbi checkout 提供 CLI、prompt、labels 和 systemd 模板。 repo_dir = "/path/to/your-repo" deploy_home = "/path/to/orbi" workspace_root = "/path/to" base_branch = "main" max_concurrency = 1 # 不要写 pi_providers = ... pi_provider = "openai-codex" pi_model = "gpt-5.6-luna" ``` Pi catalog 在 **2026-09-07** 检查到该模型的 API 是 `openai-codex-responses`，endpoint 是 `https://chatgpt.com/backend-api`；启用 reasoning，支持 text/image 输入，上下文限制 1,000,000 tokens，输出限制 128,000 tokens。其 catalog 的 thinking 映射支持 `minimal → low`、`xhigh → xhigh`、`max → max`；默认可不设 `pi_thinking`，也可设置这些已核实的级别。这些是 Pi 的请求限制，不是订阅额度承诺。 ### 额度与计费边界 OAuth 凭据消耗用户的 Codex/ChatGPT 订阅额度。它与 OpenAI API key、API organization 计费以及任何 `OPENAI_API_KEY` 余额相互独立。Pi catalog 的 `cost` 字段只是路由元数据，**不是账单或额度计数器**。额度、重置时间、限流、模型可用性和错误文本取决于账号计划且可能变化。2026-09-05 的真实运行来自一个本机账号；证据没有记录账号计划和确切额度，因此本文不做普遍额度承诺。额度耗尽或限流时，Pi session 中通常会出现上游认证/限流失败；请以当前 Codex UI/help 为准，不要用 catalog 推算剩余额度。 ### 应保留的真实 Issue 证据 在用户自己的仓库运行第一个 Issue，并保留不含秘密的证据。成功运行至少应记录： ```text theme={null} journal: provider=openai-codex model=gpt-5.6-luna run_id= PR: https://github.com/OWNER/YOUR-REPO/pull/ elapsed: result: PR opened（之后按 Orbi 正常流程审查/合并） ``` 本指南对应的 Orbi 已完成运行（2026-09-07）留下了以下脱敏、无秘密记录： ```text theme={null} journal: provider=openai-codex model=gpt-5.6-luna run_id=f3e26f87 PR: https://github.com/orbi-build/orbi/pull/487 elapsed: 4m 06s（09:11:18Z–09:15:24Z） result: PR opened ``` 这只是一个本机账号的证据，不代表额度保证；证据没有记录账号计划和确切额度。不要整份粘贴 session JSONL：先删掉凭据和包含秘密的 prompt。 ### 额度或认证失败时切换 provider 只替换选择项即可。切换到 Orbi 模板里的 provider 时，需要把对应文件加回来，因为 fallback 不再是 Pi 原生 provider： ```diff theme={null} -# 不写 pi_providers -pi_provider = "openai-codex" -pi_model = "gpt-5.6-luna" +pi_providers = ".orbi/pi-providers.json" +pi_provider = "local-qwen" # 或 "z-ai" +pi_model = "Qwen3.8-27B" # 或该文件中的 model id ``` 使用本页对应的模板和 secret 配置；绝不要把 OAuth token 或 API key 写入仓库、Issue、PR body 或 journal。认证失效时先用 `/login codex` 修复/重新登录；切换 provider 不会修复过期的 Codex session。 ## Groq 免费档 把 [`groq.json`](https://github.com/orbi-build/orbi/blob/main/templates/pi-providers/groq.json) 复制为 `.orbi/pi-providers.json`，再设置选择项和 key 引用： ```toml theme={null} pi_providers = ".orbi/pi-providers.json" pi_provider = "groq" pi_model = "groq/compound" ``` 模板使用 Groq 的 OpenAI-compatible endpoint（`api: "openai-completions"`）和 `$GROQ_API_KEY`；真实 key 放在 gitignored 的 `.orbi/env`，不要写入 JSON 或提交。 根据 Groq 的[限流表](https://console.groq.com/docs/rate-limits)，`groq/compound` 的 Free Plan 行为 **30 RPM / 250 RPD / 70K TPM**（2026-09-04 核对）。这是账号限额，不是 Orbi 承诺；实际使用前应重新查看官方表。[模型目录](https://console.groq.com/docs/models)列出该模型 131,072 token 上下文和 8,192 token 最大输出。TPM 较低，适合短小、边界清晰的 coding Issue 和小修复，不适合长上下文仓库分析。 额度命中时上游返回 HTTP `429`；Orbi 不会静默重试，也不会在 session 中途切换 provider。应把该 run 视为失败，保留 Issue/worktree 证据，并在下一次运行手动选择另一家已配置的 provider。[#313](https://github.com/orbi-build/orbi/issues/313)规划了按 provider 预算和 run 边界自动轮换；在该功能实现前，不要把它当作当前行为。本指南中的真实 Groq 请求、usage 计量和 429 响应**未实测**；没有脱敏证据时不要声称 Groq Issue 已跑通。 完整的 OpenAI-compatible 配置见[上手指南](/zh/getting-started#path-b-a-pi_providers-file-orbi)，provider 文章系列见 [Issue #305](https://github.com/orbi-build/orbi/issues/305)。 ## Related topics - [Release v0.3.3](/zh/release-v0.3.3.md) - [Testing](/zh/testing.md) - [Release v0.3.1](/zh/release-v0.3.1.md) - [Getting started](/zh/getting-started.md) - [Ollama pro](/zh/ollama-pro.md)