安裝 goose 並設定自訂供應商

goose 是一款在你的電腦上執行的通用 AI 助理。除了程式設計外，它還能處理研究、寫作、自動化與資料整理。你可以透過桌面應用程式、終端機或 API 使用它，且桌面版與終端機版共用相同的模型設定。它適合處理重複性的程式設計任務，也能連線至 GitHub、資料庫與檔案。

開始之前

goose 提供兩種安裝選項：桌面版與 CLI。桌面版是帶有視窗的圖形介面版本，而 CLI 則是透過在終端機輸入指令來使用。兩者共用相同的核心設定，包括供應商（Provider）與模型。供應商是告知 goose 使用哪個模型服務的連線設定。

想要視窗介面

goose Desktop

• 在 macOS 下載 zip
• 或使用 brew cask
• 在 Linux 使用安裝套件

僅限終端機

goose CLI

• download_cli.sh
• 或 Homebrew CLI
• 接著執行 goose session

Windows

先選擇環境

• Git Bash 或 MSYS2
• 你也可以使用 PowerShell
• 若找不到指令，請將其加入 PATH

開始之前，請準備好目前模型清單中的模型 ID。模型 ID 是模型服務用來識別特定模型的名稱，使用時必須複製完整的 ID。

首次安裝與啟動

如果你需要圖形視窗

macOS 有兩種記錄在案的安裝方法：

• 從安裝頁面下載。該頁面提供 macOS Silicon 與 macOS Intel 版本。下載後，解壓縮 zip 檔並執行其中的應用程式。
• 或者，使用 Homebrew：

brew install --cask block-goose

這會下載相同的應用程式，並能處理更新。

如果你使用 Apple Mac M3 且開啟應用程式後沒有出現視窗，請檢查 ~/.config 是否可讀寫。goose 使用此目錄來寫入記錄檔。

對於 Linux 桌面版本，請從安裝頁面下載。可用的套件包括 Ubuntu/Debian 的 DEB、RHEL/Fedora 的 RPM 以及 Flatpak。在 Debian 或 Ubuntu 上，下載 DEB 檔案，開啟儲存目錄，執行 sudo dpkg -i (filename).deb，然後從應用程式選單開啟 goose。將 (filename) 替換為實際的檔案名稱。

對於 Windows 桌面版本，請從安裝頁面下載，解壓縮 zip 檔並執行其中的應用程式。

如果你只需要終端機版本

在 macOS 與 Linux 上，請執行：

curl -fsSL https://github.com/aaif-goose/goose/releases/download/stable/download_cli.sh | bash

若要在安裝期間跳過互動式設定，請在 bash 前加入 CONFIGURE=false：

curl -fsSL https://github.com/aaif-goose/goose/releases/download/stable/download_cli.sh | CONFIGURE=false bash

在 macOS 上，你也可以執行：

brew install block-goose-cli

若要更新已安裝的 CLI，請執行：

goose update

在 Windows 上，需要以下三種環境之一：Git Bash（隨 Git for Windows 附帶，建議使用）、MSYS2 或 Windows 10/11 內建的 PowerShell。在 Git Bash 與 MSYS2 中，使用上述相同的 download_cli.sh 指令。在 PowerShell 中，請先下載指令碼再執行：

Invoke-WebRequest -Uri "https://raw.githubusercontent.com/aaif-goose/goose/main/download_cli.ps1" -OutFile "download_cli.ps1"
.\download_cli.ps1

如果系統提示找不到 goose，請依照安裝頁面說明，將 ~/.local/bin 或 %USERPROFILE%\.local\bin 加入目前的 Shell 設定，然後重新開啟終端機。PATH 是一組終端機搜尋程式的目錄。如果安裝目錄未包含在內，你可能無法透過直接輸入名稱來執行已安裝的程式。

截至 2026 年 10 月 9 日，CLI 版本為 1.54.0。預設情況下，安裝指令碼會將程式放置於 ~/.local/bin。你可以使用 GOOSE_BIN_DIR 環境變數變更此目錄。如果你變更了目錄，指令碼將不會自動更新 Shell 設定，終端機將回報該目錄不在 PATH 中。請將該目錄加入 PATH 或使用完整路徑執行 goose。

首次使用 goose 時，它會要求你設定供應商。你可以跳過內建供應商，並依照下一節說明加入自訂供應商。在終端機中，切換至你想要工作的目錄並執行：

goose session

從 OmniProxy 取得連線數值

準備好你自己的 OmniProxy 執行個體的位址、金鑰與模型名稱。自訂供應商範例使用以 /v1/chat/completions 結尾的 base_url，因此本指南採用相同格式：

API URL:  https://your-omniproxy-origin.example/v1/chat/completions
API Key:  <YOUR_OMNIPROXY_API_KEY>
Models:   Copy from the current OmniProxy model list; separate multiple models with commas

從目前的 OmniProxy 清單中複製完整的模型名稱，包含任何斜線。截至 2026 年 10 月 9 日，供應商文件中的兩個參考 ID 為 Grok 的 grok-4.7 與 OpenAI 文件中的 gpt-6-luna。gpt-6-luna 支援 Chat Completions；Chat Completions 中的函式呼叫僅在 reasoning_effort 設定為 none 時才支援。請勿複製清單中未出現的名稱。

進入工具設定

自訂供應商可以使用 OpenAI、Anthropic 或 Ollama 相容格式。相容格式意味著該工具會根據通用 API 規範傳送請求。連線至 OmniProxy 時，請選擇「OpenAI 相容」（OpenAI Compatible）。

桌面版

1. 點擊左上角按鈕開啟側邊欄。
2. 點擊「設定」（Settings）。
3. 點擊「模型」（Models）。
4. 點擊「設定供應商」（Configure providers）。
5. 點擊視窗底部的「新增自訂供應商」（Add Custom Provider）。
6. 在供應商類型中，選擇「OpenAI 相容」。你可以將顯示名稱設為 OmniProxy。在 API URL 中輸入上一節的位址。如果需要金鑰，請選擇需要 API 金鑰的選項並輸入你的 OmniProxy 金鑰。在可用模型中，輸入模型名稱，多個名稱間以逗號分隔。
7. 點擊「建立供應商」（Create Provider）。

桌面版本目前無法在此視窗中定義自訂請求標頭。如果你需要請求標頭，請在建立供應商後編輯設定檔。

終端機版

執行：

goose configure

選擇「自訂供應商」（Custom Providers），然後選擇「新增自訂供應商」（Add A Custom Provider）。在 API 類型中，選擇「OpenAI 相容」，接著依照提示輸入名稱、API URL、是否需要金鑰、模型名稱以及是否支援串流回應。

在 Windows 上手動設定時，如果鑰匙圈（keychain）回報錯誤，安裝說明建議拒絕將金鑰儲存在金鑰鏈中，改用環境變數。接著再次執行 goose configure。金鑰鏈是作業系統用來儲存機密的小型安全儲存系統。

設定檔

記錄在案的目錄為：

• macOS 與 Linux： ~/.config/goose/custom_providers/
• Windows： %APPDATA%\Block\goose\config\custom_providers\

你可以參考提供的範例來建立檔案。將名稱、位址與模型替換為你自己的數值。將金鑰儲存在 api_key_env 指定的環境變數中；請勿將真實金鑰寫入檔案：

{
  "name": "omniproxy",
  "engine": "openai",
  "display_name": "OmniProxy",
  "api_key_env": "OMNIPROXY_API_KEY",
  "base_url": "https://your-omniproxy-origin.example/v1/chat/completions",
  "models": [
    { "name": "grok-4.7", "context_limit": 128000 },
    { "name": "gpt-6-luna", "context_limit": 128000 }
  ],
  "supports_streaming": true,
  "requires_auth": true
}

請為 context_limit 保留數值，如範例所示。實際的上下文限制取決於模型與 OmniProxy；請勿將範例數值視為模型的官方限制。使用前，請執行：

export OMNIPROXY_API_KEY="<YOUR_OMNIPROXY_API_KEY>"

進入工作目錄後，執行：

goose session --provider omniproxy --model grok-4.7

將 --model 的值替換為清單中的完整 ID。goose session 沒有 start 子指令。你也可以透過 GOOSE_PROVIDER 與 GOOSE_MODEL 環境變數來設定 --provider 與 --model。即使閘道未驗證金鑰，OMNIPROXY_API_KEY 仍必須有值。它可以是僅在本地電腦使用的預留字串。此設定在 2026 年 10 月 9 日的測試中成功讀取了檔案。

視窗

設定

• 側邊欄中的設定
• 模型頁面
• 新增自訂供應商

終端機

goose configure

• 選擇自訂供應商
• 接著選擇新增
• 選擇 OpenAI 相容作為類型

檔案

custom_providers

• 在 macOS 與 Linux 上位於 ~/.config
• 在 Windows 上位於 APPDATA
• 依照官方範例設定 base_url

以實際任務驗證

開啟包含一般檔案的目錄並執行上一節所示的 goose session。要求它讀取你指定檔案的第一行。它應該會回傳檔案內容，而不是只說設定已儲存。

若要讀取檔案或執行指令，工作階段需要 Developer 擴充功能。Developer 擴充功能是一個讓 goose 能處理本地檔案與指令的工具模組。它通常包含在預設設定中。如果 goose 表示沒有檔案工具，請在指令中加入：

--with-builtin developer

請勿同時加入 --no-profile，因為該選項會停用預設擴充功能。

在 2026 年 10 月 9 日的測試中，goose 1.54.0 成功讀取了指定檔案的第一行。第一次回應可能需要約一分鐘。

接著檢查 OmniProxy 請求記錄，確認來源與模型名稱。

啟動

開啟工作階段

• goose session
• 供應商為剛加入的那個
• 模型名稱在清單中

任務

它確實完成了任務

• 例如，列出目前目錄
• 審核其回應
• 不要只依賴成功的儲存訊息

記錄

在閘道中可見

• 使用文件範例中的位址
• 不要將金鑰放入儲存庫
• 模型 ID 與清單相符

常見錯誤

• 找不到 goose 指令：依照安裝頁面說明將安裝目錄加入 PATH，然後重新開啟終端機。
• M3 Mac 桌面版沒有視窗：檢查 ~/.config 的讀寫權限。
• 鑰匙圈失敗：請勿將金鑰儲存在鑰匙圈中；改用環境變數。
• 模型不在清單中：在桌面版中，選擇「使用自訂模型」（Use custom model）並手動輸入模型名稱。goose configure 無法接受自訂模型名稱。若要在終端機使用，請切換至桌面版或直接編輯設定檔中的 GOOSE_MODEL。
• 無法連線至位址：確認 API URL 以 /v1/chat/completions 結尾（如範例所示），且 OmniProxy 正在執行。
• 表示無法讀取檔案：加入 Developer 擴充功能，且不要使用 --no-profile。
• 回傳 unsupported Responses role: system：位址通常是正確的。請切換至模型清單中的另一個完整 ID。

官方參考

關於安裝，請參閱 安裝 goose。關於自訂供應商，請參閱 goose 供應商。關於範例中使用的模型 ID，請參閱 xAI 模型頁面 與 GPT-6 Luna。

將所有佔位符替換為您自己的 OmniProxy 配置值。切勿發布真實金鑰。

保存的結果或 HTTP 200 單獨存在並不證明完整的 Agent 相容性。請在 OmniProxy 的呼叫記錄中檢查來源與模型。

官方來源 · goose ↗