Pi Provider 模板

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

​

清单

​

DeepSeek：Orbi 自身交付使用的配置

​

xAI：Grok 4.20 Reasoning

pi_providers = ".orbi/pi-providers.json"
pi_provider = "xai"
pi_model = "grok-4.20-0309-reasoning"

​

OpenRouter :free：一个 key、多个模型

mkdir -p .orbi
cp templates/pi-providers/openrouter.json .orbi/pi-providers.json
printf '%s\n' 'OPENROUTER_API_KEY=replace-me' > .orbi/env
chmod 600 .orbi/env

{
  "providers": {
    "openrouter": {
      "baseUrl": "https://openrouter.ai/api/v1",
      "api": "openai-completions",
      "apiKey": "$OPENROUTER_API_KEY",
      "models": [
        {"id": "google/gemma-4-31b-it:free", "name": "Gemma 4 31B (free)"},
        {"id": "cohere/north-mini-code:free", "name": "North Mini Code (free)"}
      ]
    }
  }
}

pi_providers = ".orbi/pi-providers.json"
pi_provider = "openrouter"
pi_model = "cohere/north-mini-code:free"

​

限额、请求与 429 状态

​

接入一家新 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 = "cf-workers"
pi_model = "@cf/meta/llama-3.1-8b-instruct-fp8"

​

实测一个 Orbi 任务的消耗

journal: provider=cf-workers 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

​

GitHub Models：免费原型额度历史快照

1. 在 GitHub token 设置 创建 fine-grained personal access token，并授予 Models: read 权限。只在本机保存 token；不要写入 Git、Issue、PR 或 journal：
   mkdir -p .orbi
   printf '%s\n' 'GH_MODELS_TOKEN=replace-me' > .orbi/env
   chmod 600 .orbi/env
   
2. 将 templates/pi-providers/github-models.json 复制为 .orbi/pi-providers.json，然后选择精确 ID：
   pi_providers = ".orbi/pi-providers.json"
   pi_provider = "github-models"
   pi_model = "openai/gpt-4.1-mini"
   
   模板使用 https://models.github.ai/inference、Pi 的 openai-completions API 和 $GH_MODELS_TOKEN。派发任务前运行 Runner 校验；校验只检查结构和 key 引用，不检查账号访问权或额度。

​

模型清单和限额（2026-09-04 核对）

​

GitHub Models 与 Copilot 的边界

​

使用 Sign in with ChatGPT：消耗 ChatGPT Plus/Pro 订阅额度

​

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

1. 启动交互式 Pi 会话：pi。
2. 在 Pi 提示符中执行 /login openai。Pi 会询问 Select authentication method for OpenAI:——选择 Sign in with ChatGPT（订阅路径；另一个选项是 Sign in with an API key）。不带 provider 参数的 /login 会先询问 Select authentication method:：选择 Sign in with an account，随后才会列出 provider OpenAI。
3. 在浏览器完成授权，并同意该 app 使用你的 ChatGPT 订阅额度。
4. 配置 Orbi 之前先检查登录：
   pi auth check --provider openai --model <slug-from-your-model-list> --json
   
   成功时应报告：
   {"status":"ready","provider":"openai","authType":"oauth"}
   
   "authType":"oauth" 说明正在使用已保存的 ChatGPT OAuth 凭据。若显示 "authType":"api_key"，说明 Pi 找到了 OPENAI_API_KEY；通常已保存的 OAuth 凭据优先，但如果要明确只用订阅，请从 .orbi/env 删除该变量。该命令默认会刷新过期 OAuth 凭据；不要在共享终端或 transcript 中使用 --credentials。

​

最小 Orbi 配置

source_repos = ["OWNER/YOUR-REPO"]
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"
pi_model = "<slug-from-your-model-list>"

​

选择账号可用的模型

ACCESS_TOKEN=$(jq -r '.openai.access' ~/.pi/agent/auth.json)
curl -sS https://api.openai.com/v1/models \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  | jq -r '.models[] | select(.visibility == "list") | .slug'

​

与 Codex OAuth 一节的差别

• Sign in with ChatGPT 使用 Pi 原生的 openai provider，走公网 Responses API https://api.openai.com/v1。这是 OpenAI 为 ChatGPT Plus/Pro 订阅额度记录的路径，新装 Orbi 应优先选择。
• Codex OAuth 使用 Pi 原生的 openai-codex provider，走 https://chatgpt.com/backend-api（Codex app-server 路由）。它仍是已有 Codex 环境的正确路径。

​

无头/服务器安装

ssh user@vm 'mkdir -p ~/.pi/agent'
scp -p ~/.pi/agent/auth.json user@vm:~/.pi/agent/auth.json

​

额度与计费边界

​

失败路径与修复

• 订阅额度用尽。 OpenAI 返回 subscription_sharing_usage_limit_exceeded（HTTP 429）或 subscription_sharing_usage_unavailable（HTTP 503）。Pi session 失败，Orbi 记录错误并把 Issue 标为 ai-blocked。修复：等待共享额度重置，在 ChatGPT Settings → Usage 调整该 app 的限额，或切换到另一家已配置的 provider。Orbi 永不回退到 API 账单。
• 未授予权限。 如果授权页未授予订阅用量权限，Pi 会以 OpenAI OAuth grant did not include chatgpt.tokens.use.direct 失败。修复：重新执行 /login openai 并同意订阅用量权限。
• 凭据过期或被撤销。 refresh token 过期（闲置 30 天）、在 ChatGPT 设置中断开该 app，或 Pi session 出现认证错误，都说明需要重新登录。修复：重新执行 /login openai。切换 provider 不会修复失效的 ChatGPT session。

​

证据边界

​

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"