​

Pi Provider 模板

pi_providers = ".orbi/pi-providers.json"
pi_provider = "z-ai"
pi_model = "glm-5.3-flash"

​

清单

​

接入一家新 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} 引用：
   mkdir -p .orbi
   printf '%s\n' 'ZAI_API_KEY=replace-me' > .orbi/env
   chmod 600 .orbi/env
   
   已安装的 [email protected] 通过 EnvironmentFile 加载此文件；key 绝不能进入 Git 或模板。字面量 key 只是降级方案：文件仍应 gitignored，并且要接受它可能通过本地文件和进程工具泄漏的风险。
4. 手动 tick 时 systemd 不会加载 .orbi/env。先导出变量，或在当前 shell 中 source：
   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

​

Google Gemini：AI Studio 免费层

1. 在 AI Studio 创建或选择 key，然后写入 Orbi 使用的 gitignored 环境文件：
   mkdir -p .orbi
   printf '%s\n' 'GOOGLE_API_KEY=replace-me' > .orbi/env
   chmod 600 .orbi/env
   
   已安装的 systemd unit 会加载 .orbi/env。手动 tick 时，先按上手指南导出变量。
2. 将 templates/pi-providers/gemini.json 复制为 .orbi/pi-providers.json。其中完整的选中条目如下：
   {
     "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：
   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。

​

免费层限流与实测表现

pi_providers = ".orbi/pi-providers.json"
pi_provider = "z-ai"       # 或清单中的其他 provider
pi_model = "glm-5.3-flash"

​

z.ai GLM：体验/免费额度

1. 在 z.ai 控制台创建 API key，然后放入本地 gitignored 环境文件：
   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 命令。
2. 将 templates/pi-providers/z-ai.json 复制为 .orbi/pi-providers.json，或复制其中的 provider 条目。选择精确的 ID：
   pi_providers = ".orbi/pi-providers.json"
   pi_provider = "z-ai"
   pi_model = "glm-5.3-flash"
   
   当前完整的 models 条目是：
   {
     "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 完成到 commit b81f77a，并到达 PR #304。这证明一次成功运行，不是额度保证。
• 本指南使用的材料中，z.ai 没有静态公布统一的体验/免费上限。确切额度、重置时间、并发和模型可用性取决于账号及 z.ai 当前政策；本文未实测。
• 本指南没有对耗尽或限流响应做受控测量；限流表现：未实测。以上游 HTTP 认证/限流错误为准，不要编造数字或增加重试循环。

​

额度用尽后的切换路径

pi_providers = ".orbi/pi-providers.json"
pi_provider = "openrouter"
pi_model = "google/gemma-4-31b-it:free"

​

Cloudflare Workers AI

printf '%s\n' 'CLOUDFLARE_API_TOKEN=replace-me' >> .orbi/env
chmod 600 .orbi/env

pi_providers = ".orbi/pi-providers.json"
pi_provider = "cloudflare-workers-ai"
pi_model = "@cf/meta/llama-3.1-8b-instruct-fp8"

​

实测一个 Orbi 任务的消耗

journal: provider=cloudflare-workers-ai model=@cf/meta/llama-3.1-8b-instruct-fp8 run_id=<run-id>
Cloudflare Workers AI usage: before=<n> neurons at <UTC>, after=<n> neurons at <UTC>, delta=<n>
PR: https://github.com/OWNER/REPO/pull/<number>

​

托管服务与本地 Qwen 的定位

​

本地 provider

​

Codex OAuth：使用 ChatGPT/Codex 订阅额度

​

第一次登录：必须按这个顺序

1. 启动交互式 Pi 会话：pi。
2. 在 Pi 提示符中执行 /login codex。
3. 在浏览器完成 Codex OAuth 授权。
4. 回到 Pi，用当前 Pi CLI 实际支持的命令检查登录：
   pi auth check --provider openai-codex --model gpt-5.6-luna --json
   
   成功时应报告 "status":"ready" 和 "authType":"oauth"。该命令默认会刷新过期 OAuth 凭据；不要在共享终端或 transcript 中使用 --credentials。
5. 检查成功后，再配置 Orbi 并运行真实 Issue。

​

最小 Orbi 配置

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"

​

额度与计费边界

​

应保留的真实 Issue 证据

journal: provider=openai-codex model=gpt-5.6-luna run_id=<run-id>
PR: https://github.com/OWNER/YOUR-REPO/pull/<number>
elapsed: <duration>
result: PR opened（之后按 Orbi 正常流程审查/合并）

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

​

额度或认证失败时切换 provider

-# 不写 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

​

Groq 免费档

pi_providers = ".orbi/pi-providers.json"
pi_provider = "groq"
pi_model = "groq/compound"