建立 API Key（權杖）

在 MoleAPI 裡，API Key 也常被稱為 權杖。它是你呼叫介面時的身分憑證，通常會以 sk-... 的形式出現。

建立完成後，你就可以把它填到 Chatbox、NextChat、沉浸式翻譯、OpenAI SDK 或其他支援自訂 OpenAI 介面的工具中使用。

建立前你需要準備什麼

開始前，建議先確認下面幾件事：

1. 你的帳戶已經註冊並可以登入 MoleAPI 控制台。
2. 帳戶裡有可用餘額，或者至少有新使用者贈送測試額度。
3. 你已經想清楚這個 Key 的用途，例如：
   • 日常測試
   • 本機開發
   • 某個正式專案
   • 團隊內某個獨立應用

第一步：進入 KEY 管理頁面

登入後，進入控制台左側邊欄的 KEY 管理 頁面：

• 路徑：控制台 → KEY 管理
• 直達位址：https://home.moleapi.com/console/token

進入頁面後，點擊上方的 新增權杖。

第二步：填寫建立表單

點擊後，會跳出「建立新的權杖」對話框。下面這張圖基於 MoleAPI 控制台真實介面：

如果你現在只想先把 Key 建起來，不想一口氣理解所有欄位，也可以先抓住最影響成敗的 4 項：

• 名稱：方便你自己後續辨識用途
• 權杖分組：決定目前 Key 走哪個模型分組
• 到期時間：決定這個 Key 會保留多久
• 模型限制：如果你不確定，第一次可以先不限制

下面依這個順序逐項說明。

1）名稱（必填）

這是你自己給這個 Key 取的備註名稱，用來區分用途。

推薦命名方式：

• dev-local
• chatbox-test
• nextchat-prod
• openclaw-docs

建議做到 見名知意，這樣後續在使用日誌、Key 管理、額度控制裡都更容易定位。

2）權杖分組

這裡用於決定該權杖走哪個分組。

通常分組會影響：

• 可用模型範圍
• 價格策略
• 通道穩定性或供應來源

如果你現在只是第一次建立，可以先使用預設分組。等你熟悉平台後，再根據價格、模型可用性和業務用途切換到更合適的分組。

3）到期時間（必填）

MoleAPI 支援手動選擇到期時間，也提供幾個快捷按鈕：

• 永不過期
• 一個月
• 一天
• 一小時

怎麼選更合適：

• 臨時測試：建議選 一天 或 一小時
• 本機開發：建議選 一個月
• 長期穩定服務：可以選 永不過期，但要搭配額度和安全策略一起使用

對新手來說，如果只是先跑通介面，建議先建一個短期 Key，確認沒問題後再補正式 Key。

4）新增數量（必填）

預設是 1，表示只建立一個權杖。

如果你要一次發給多個環境或多位成員獨立 Key，可以批次建立。批次建立時，系統會在名稱後追加隨機後綴，方便區分。

如果你只是第一次使用，保持 1 就可以。

5）額度

這裡是給單一權杖設定可使用額度上限。

需要注意：

• 這是 權杖自己的額度上限，不是帳戶總餘額。
• 即使這裡設定得很高，實際能不能消費，依然會受到 帳戶剩餘餘額 限制。

如果你希望這個 Key 只能用於小規模測試，可以給它設定一個較低額度，避免誤用。

6）無限額度

預設通常是開啟的。

開啟後，這個權杖本身不另外限制額度，只受帳戶餘額影響。

建議這樣理解：

• 臨時測試 Key：可以關閉無限額度，填一個小額度
• 正式服務 Key：是否開啟取決於你的風險控管策略

如果你對風控比較敏感，建議不要所有 Key 都開無限額度。

7）模型限制列表

這裡可以限制這個 Key 允許呼叫哪些模型。

如果不限制，通常代表它可以呼叫目前分組下允許的全部模型。

推薦做法：

• 測試用途：可以先不限制，方便探索
• 正式專案：只開放業務真正需要的模型
• 團隊協作：不同系統分配不同 Key，並限制模型範圍

這樣做的好處是：

• 避免誤呼叫高價模型
• 降低權限過大帶來的風險
• 更容易排查日誌和成本來源

8）IP 白名單

這裡可以填寫允許存取該 Key 的 IP，支援 CIDR 表示式。

如果你不填寫，預設不限制來源 IP。

適合開啟 IP 白名單的場景：

• 服務端部署在固定伺服器上
• 公司出口 IP 固定
• 你希望某個正式環境 Key 只能從指定環境呼叫

如果你還處在本機除錯階段，沒有固定出口 IP，可以先留空，後面再補。

第三步：提交並複製 API Key

所有內容確認後，點擊右下角的 提交。

建立成功後，你會在 KEY 管理清單裡看到新建的權杖。接下來請立即完成兩件事：

1. 複製完整的 API Key
2. 把它保存到安全的位置，例如：
   • 本機密碼管理器
   • 環境變數
   • 伺服器密鑰管理系統

給新手的推薦設定

如果你只是想先快速跑通 MoleAPI，建議你先這樣建立：

• 名稱：dev-local
• 權杖分組：預設分組
• 到期時間：一個月
• 新增數量：1
• 額度：依自己能接受的測試額度填寫，或者先開啟無限額度
• 模型限制：先不限制
• IP 白名單：先留空

這樣設定最容易成功，後續再逐步收緊權限。

建立後下一步做什麼

拿到 API Key 後，你通常還需要兩個資訊才能真正開始呼叫：

• Base URL：https://api.moleapi.com/v1
• API Key：你剛建立的 sk-...

建議繼續閱讀：

• API Key 是什麼？
• Base URL 是什麼？
• 渠道分組是什麼？
• API Key 安全設定

常見問題

為什麼我建立了 Key，但還是呼叫失敗？

常見原因有：

• Base URL 填錯，漏掉了 /v1
• 模型名稱寫錯
• 帳戶餘額不足
• 權杖分組下不支援該模型
• 權杖設定了模型限制或 IP 限制

一個帳號可以建立多個 API Key 嗎？

可以，建議依用途拆分多個 Key，而不是所有專案共用一個。

測試和正式環境要不要共用一個 Key？

不建議。更推薦：

• 一個測試 Key
• 一個正式環境 Key
• 必要時依專案再拆分

這樣更安全，也更方便控制成本和排查問題。