Pi Agent 給你的是工作台，不是引擎

Pi Agent 走的是 BYOK——自帶金鑰。這個附加元件不會幫你決定要用哪家 AI，也不會幫你付錢：你得自己開帳號、建金鑰、貼進來。這件事帶來三個結果。

• 你自己挑模型，之後想換也不用重裝任何東西。
• 你直接付錢給供應商；附加元件本身不收費。
• 金鑰留在你自己的硬體上，只會送去你設定的那家供應商。

OpenRouter 這篇先示範它，有三個實際的理由：一支金鑰透過一個相容 OpenAI 格式的閘道，就能碰到好幾家廠商的模型家族；註冊只要一個 email 或它支援的登入方式，照當下頁面要求的驗證走就好；而且它本來就是為多地區的 API 存取設計的，只是模型與付款方式仍依國家而異。

它是一個閘道，不是模型開發商本身：一支金鑰接到的目錄會隨時間變動，而直接跟廠商申請的話，你拿到的只有那一家自己的目錄；資料怎麼處理，依循的是 OpenRouter 的條款加上你選的模型供應商，還有你自己的隱私設定。沒有哪家供應商什麼任務都是最強的，很多人會同時掛兩三家——那是第 6 篇的事。現在，先讓一支金鑰能動起來就好。

一段會花你錢的短字串

OpenRouter 金鑰是一段機密字串，通常開頭是 sk-or-v1-。Pi Agent 每次請求都會帶著它送出去；OpenRouter 收到後會檢查、把用量算進你的帳戶，再把請求送到你選的模型。

從 Pi Agent v0.13.0 起，供應商金鑰存在本機的 /data/pi-agent/models.json ，在你 Home Assistant 主機上、附加元件的持久化資料裡。WoowTech 收不到這支金鑰，但任何對主機或這份資料有足夠存取權的人，都讀得到這個檔案。

flowchart LR
  A["你的瀏覽器"] --> B["你 HA 主機上的 pi-web"]
  B --> C["/data/pi-agent/models.json
金鑰存放的地方"]
  B --> D["https://openrouter.ai/api/v1
你設定的端點"]
  D --> E["上游模型
負責寫出回答"]

把它當成付款憑證看待。三個地方是安全的：Pi Agent 的 Models 面板；密碼管理器，例如 1Password、Bitwarden、Apple Passwords 或 KeePass，搭配夠強的主密碼與多因子驗證；以及你實際測過還原沒問題的加密離線備份。以下這些地方絕對不要放：

• 公開的程式碼倉庫。 掃描工具找外洩金鑰非常快，光刪掉最新那次 commit 沒用，只要值還留在 Git 歷史裡就等於沒刪。
• 聊天群組與社群討論串。 其他成員跟平台本身都可能留著這則訊息。
• 共用文件。 連結分享的權限設定很容易設錯，之後也可能被改動。
• 普通的電子郵件。 不要用信件寄送 API 金鑰。
• 截圖與錄影。 字小到肉眼看不清楚，OCR 照樣讀得出來。
• 求助貼文。 用一眼就看得出是假的範例，而且要遮掉整段機密，不是只遮尾巴： sk-or-v1-REDACTED。

附錄 B 說 debug 等級的 log 裡，憑證會被遮成 ***。就算如此，分享 log 之前還是自己先讀一遍再說。

在手機或電腦上建立金鑰

後台的文字標籤會變。如果跟下面寫的不一樣，一律以網站上實際看到的為準。

1. 步驟 1

   打開官方網站

   前往 https://openrouter.ai/settings/keys。確認網址列顯示的是 openrouter.ai，而不是長得很像的假網址，例如 openrouter.example。

2. 步驟 2

   登入，或建立新帳號

   用 OpenRouter 目前提供的登入方式，email 或它支援的身分供應商都行，照畫面要求完成驗證。不要沿用你的 Home Assistant 密碼。

3. 步驟 3

   先讀隱私與資料設定

   在儲值或送出任何私密內容之前先做這件事：請求可能會經過你選的模型供應商處理，所以設定跟模型要挑適合你要送出的內容的。

4. 步驟 4

   打開 API Keys 頁面

   在後台裡打開 API Keys ，在 Settings 裡面。如果文字標籤變了，就跟著官方設定頁當下的連結走。

5. 步驟 5

   點 Create Key

   OpenRouter 可能會讓你選填這支金鑰的額度上限。真的要設，就設一個符合你自己預算的數字。

6. 步驟 6

   取一個之後認得出來的名字

   用它所屬的安裝來命名： pi-agent-home, pi-agent-office, test-2026-08。分開的金鑰讓之後換金鑰、查用量都輕鬆很多。

7. 步驟 7

   建立後，用 Copy 按鈕複製

   用 Copy ，不要自己手動選字，才不會漏掉字元。這是唯一一次看得到完整值的機會；之後顯示的遮蔽預覽，像是 sk-or-v1-… ，是沒辦法還原回完整值的。

8. 步驟 8

   存進你的密碼管理器

   現在就好好存起來。暫時記在本機的一則備忘也可以——等下面的設定完成後就把它刪掉。

Token、額度，跟帳戶要求你做的事

OpenRouter 用 token 計算用量，而 token 數量因語言、因模型而異，所以不要用字數去推算帳單。Pi Agent 送出的是你的提示，加上 與 每次請求相關的對話上下文，而且回覆本身也要算 token。

費率跟可用性會變動。請以 OpenRouter 目錄跟你自己後台看到的數字為準，不要以任何教學（包括這篇）上印的數字為準。

盯著實際用量看，不要自己編一個月費估算。花費跟提示與回覆的長度、上下文長度、選的模型，以及在影片流程裡的生成步驟數都有關。如果後台提供單支金鑰的額度上限，就設一個；每個流程各自的用量各自檢查，不要假設有固定的花費。

一本路線登記簿，不是一份模型清單

工作區側欄左下角有三顆小按鈕： Models, Skills, Settings。Models 打開的是設定對話框裡的 Models 分頁——一本服務目錄，每張卡片代表你跟一家公司或閘道談好的一份約定，裡面有一個端點、一支憑證，跟它自己的模型清單。

• Add Provider 會再建一張卡片——現在用一次，第 6 篇還會再用一次接第二條路線。
• Test 是最關鍵的按鈕：綠燈代表這組設定真的能完成一次請求，不只是表單存檔而已。
• Save 會寫進 /data/pi-agent/models.json，這在官方文件記載的 Home Assistant 備份路徑裡有包含。

Add Provider 打開的是一份目錄，不是空白表單，分類方式是依供應商的連線方式，不是依品牌。

目錄清單最上面：一個自訂項目、六個用 OAuth 登入的訂閱制服務，接著是各家用 API 金鑰的供應商，各自標著模型數量。

• CUSTOM 底下只有一張卡片 ——「OpenAI／Anthropic compatible」，副標是 Custom endpoint format。這篇教學用的就是這張卡片，因為它要你自己手動填端點跟金鑰。
• SUBSCRIPTIONS 底下全部標著 OAuth。 這裡是登入你已經付費的方案，不是貼一段機密字串——順帶一提 OpenRouter 也出現在這裡，叫 OpenRouter OAuth，但這篇走的不是這條路。
• API KEY 卡片各自標著模型數量：Amazon Bedrock 121 個模型、Anthropic 14 個模型。這個數字代表這一個項目碰得到多少模型。

一個項目裡的廣度OpenRouter 一個項目就能碰到 366 個模型，Vercel AI Gateway 是 237 個，而大部分單一廠商的項目只列得出小貓兩三隻。

• OpenRouter，366 個模型，就用這個名字列在清單裡。一個帳號、一支金鑰，這個數字就是這篇選它示範的理由。
• 單一廠商的項目小很多 ——xAI 3 個、Z.AI 7 個、Together 21 個。每一家都得自己另外開帳號。
• Radius 顯示 0 個模型，所以出現在這份清單裡，不代表現在就有東西可以選。

所以進去的路有兩條。 OpenRouter 卡片會自動幫你填好端點；這篇是在自訂卡片上手動打出來，不管走哪條路，那三個要設的東西都一樣。

光有金鑰，Pi Agent 什麼都不知道

一段開頭是 sk-or-v1- 的值，只是一份憑證：Pi Agent 沒辦法從它推算出端點、API 模式或模型 ID。這是一次性的設定；之後你會回來 Models 面板，只會是為了換金鑰、加供應商，或改要用哪些模型。

三個都要對得上。上面那個模型 ID 是這篇教學在倉庫裡驗證過的；目錄會變動，所以先確認它還在清單裡，不在的話就複製一個目前可用模型的精確 ID。

1. 步驟 1

   打開 Models，選自訂項目

   點 Models，接著 Add Provider，選底下的卡片，在 CUSTOM ，標著 OpenAI / Anthropic compatible。表單裡有 Name、API mode、baseUrl、apiKey，接著是 Models 清單。

2. 步驟 2

   填一個之後看得懂的 Name

   OpenRouter 就夠了。Pi Agent 是靠 Name 分辨卡片，不是靠端點，所以同一個端點的第二支金鑰得取自己的名字，例如 OpenRouter-office。

3. 步驟 3

   把 API mode 設成 openai-completions

   有四個選項 openai-completions, openai-responses, anthropic-messages 與 google-generative-ai。這個 base URL 暴露的是相容 OpenAI 的 Chat Completions 介面，所以要選 openai-completions；模式選錯，回來的是 400 或 404，不會有什麼有用的提示。官方文件記載的直接 Anthropic 設定用的是 anthropic-messages，Google 對應的是 google-generative-ai，官方文件記載的 OpenAI Responses 端點用的是 openai-responses。附錄 B 是供應商對照表。

4. 步驟 4

   精確輸入 base URL

   Copy https://openrouter.ai/api/v1 不要多加任何東西。用 HTTPS。不要在後面加 /chat/completions，不要留結尾的斜線，也不要貼成後台裡的路徑，例如 /settings/keys。

5. 步驟 5

   把金鑰貼進 apiKey

   從你的密碼管理器貼過來。這個欄位預設會遮住值；眼睛圖示可以短暫顯示出來。檢查頭尾有沒有多餘的空白，有的話用 Backspace 或 Delete 刪掉——空白字元是這裡貼失敗最常見的原因。要看完整的值，用一個本機的文字欄位，絕對不要用共用文件或任何你可能會截圖的地方。

6. 步驟 6

   加模型，然後按 Test 跟 Save

   點 Add Model，輸入 anthropic/claude-sonnet-4 當名字，再從 contextWindow 這個數字要從那個模型自己的詳細頁面拿，絕對不要拿別的模型的。接著按 Test：綠色勾勾代表成功了，就按 Save ，關掉面板。不用重啟任何東西；下一次請求就會用新設定。

它出現在哪裡這是設定了另一條路線的機器上的下拉選單。你的畫面會列出你自己輸入的模型，不是這些。

• 訊息框下面那顆按鈕，寫的是目前的模型名稱 ——這裡是 GPT-5.6 Sol。點它會打開這份清單。
• 打勾的那一個 ，標的是這個對話會送去的模型。確定那是你剛剛測過的那一個。
• 清單只顯示模型名稱，不帶供應商前綴，所以每個模型都要取一個一眼就認得出來的 ID。

之後修改卡片，或刪掉一張

每張供應商卡片都有一個三點選單（⋮），裡面兩個動作，可逆的程度不一樣。

同一家供應商的第二支金鑰，在三種情況下值得另開一張卡：把家裡跟辦公室的用量分開，卡片命名成 OpenRouter-home 與 OpenRouter-office；在後台有提供的情況下，各自帶不同的額度上限，不過這不能取代限制 Home Assistant 管理員的存取權；還有在換另一支金鑰的過程中減少中斷。企業用的憑證與計費，照你組織自己的規定走。用 Add Provider加一張新卡，取不同的 Name，同樣的 baseUrl，換一支 apiKey，加上 anthropic/claude-sonnet-4 ，前提是它還在目前的目錄裡。

動手改東西之前，先讀懂錯誤訊息

Test 失敗會給明確的訊息。對照代碼查下面的表，不要亂改欄位。

有些失敗不會有狀態碼，只會在介面上顯現。

還有一些狀況，是金鑰根本還沒送到 Pi Agent 就出錯了。

接下來往哪走