goose 安裝與自訂 Provider 設定

goose 是在你電腦上執行的通用 AI 助理。除了程式碼，它也能進行搜尋、寫作、自動化和資料整理。你可以透過桌面版、終端機或介面使用，桌面版與終端機版共用同一套模型設定。它適合處理重複的程式開發工作，也能連接 GitHub、資料庫和檔案。

安裝前準備

goose 提供 Desktop 和 CLI 兩種安裝方式。Desktop 是有視窗介面的桌面版，CLI 則是在終端機中輸入指令使用的版本。兩者共用核心設定，包括 Provider 和模型。Provider 可以理解為「告訴 goose 要使用哪一個模型服務」的連線設定。

想要視窗

goose Desktop

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

只需要終端機

goose CLI

download_cli.sh
或使用 Homebrew CLI
然後執行 goose session

Windows

先選擇環境

Git Bash 或 MSYS2
也可以使用 PowerShell
找不到命令時就加入 PATH

macOS 可以透過下載或 Homebrew 安裝。Linux 桌面版使用發行版安裝套件。Windows 請先確認官方列出的終端機環境。

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

安裝並首次啟動

想使用視窗介面

macOS 提供兩種安裝方式：

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

brew install --cask block-goose

這會下載同一個應用程式，並可一併處理更新。

如果使用 Apple Mac M3，開啟後卻沒有出現視窗，請檢查 ~/.config 是否可讀寫。goose 需要使用這個目錄寫入記錄。

Linux 桌面版請從安裝頁面下載。官方列出 DEB（Ubuntu/Debian）、RPM（RHEL/Fedora）和 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

如果不想在安裝過程中進行互動式設定，請在前面加上 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 不在 PATH 中，請依照安裝頁面的說明，將 ~/.local/bin 或 %USERPROFILE%\.local\bin 加入目前 shell 的設定，然後重新開啟終端機。PATH 是終端機用來尋找程式位置的一組目錄；如果沒有加入，即使程式已經安裝，也可能無法直接輸入名稱執行。

2026-10-09 的 CLI 版本為 1.54.0。安裝指令碼預設會將程式放在 ~/.local/bin。你可以透過環境變數 GOOSE_BIN_DIR 更改這個目錄。變更後，指令碼不會自動寫入 shell 設定，終端機會提示該目錄不在 PATH 中。請將該目錄加入 PATH，或使用完整路徑執行。

首次使用時，goose 會要求你設定 Provider。你可以先略過內建 Provider，並依照下一節新增自訂 Provider。在終端機中進入你要工作的目錄，然後執行：

goose session

從 OmniProxy 取得連線參數

從你自己的 OmniProxy 準備位址、金鑰和模型名稱。自訂 Provider 的範例會將 base_url 設為 /v1/chat/completions，因此這裡也採用相同格式：

API URL:  https://your-omniproxy-origin.example/v1/chat/completions
API Key:  <YOUR_OMNIPROXY_API_KEY>
Models:   從 OmniProxy 目前的模型清單複製，多個模型以半形逗號分隔

請從 OmniProxy 目前的清單完整複製模型名稱，並保留其中的斜線。2026-10-09 的 Provider 文件中有兩個可供比對的 ID：Grok 的 grok-4.7，以及 OpenAI 文件中的 gpt-6-luna。gpt-6-luna 支援 Chat Completions；在 Chat Completions 中，只有當 reasoning_effort 設為 none 時才支援函式呼叫。請勿直接使用清單中不存在的名稱。

填寫工具設定

自訂 Provider 使用 OpenAI、Anthropic 或 Ollama 相容格式。相容格式可以理解為：工具會依照某種通用介面傳送請求。連接 OmniProxy 時，請選擇 OpenAI Compatible。

桌面版

點選左上角按鈕以開啟側邊欄。
點選 Settings。
點選 Models。
點選 Configure providers。
點選視窗底部的 Add Custom Provider。
Provider Type 選擇 OpenAI Compatible。Display Name 可以填寫 OmniProxy。API URL 請填入上一節的位址。需要金鑰時，勾選要求 API Key，並填入 OmniProxy 的金鑰。Available Models 請填寫模型名稱，多個模型以半形逗號分隔。
點選 Create Provider。

目前無法在桌面版的這個視窗中定義自訂請求標頭。如需請求標頭，請在建立後修改設定檔。

終端機

執行：

goose configure

選擇 Custom Providers，再選擇 Add A Custom Provider。API Type 選擇 OpenAI Compatible，然後依提示填寫名稱、API URL、是否需要金鑰、模型名稱，以及是否支援串流回應。

在 Windows 上手動設定時，如果鑰匙圈發生錯誤，安裝頁面的處理方式是：系統詢問是否儲存至 keyring 時選擇不儲存，改用環境變數。接著重新執行 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 子指令。--provider 和 --model 也可以分別設為環境變數 GOOSE_PROVIDER、GOOSE_MODEL。如果閘道不驗證金鑰，OMNIPROXY_API_KEY 仍然必須有值，可以使用一串只在本機使用的預留字元。2026-10-09 透過這種方式成功讀取了檔案。

視窗

Settings

側邊欄中的 Settings
Models 頁面
Add Custom Provider

終端機

goose configure

選擇 Custom Providers
再選擇新增
類型選擇 OpenAI Compatible

檔案

custom_providers

macOS 與 Linux 位於 ~/.config
Windows 位於 APPDATA
base_url 依照官方範例

這三種方式寫入的是同一類設定。Provider 類型請選擇 OpenAI Compatible。

驗證實際任務

進入一個包含一般檔案的目錄，執行上一節的 goose session。要求它讀出你指定檔案的第一行。它必須回傳檔案內容，而不只是顯示設定已儲存。

若要讀取檔案或執行指令，工作階段中必須啟用 Developer 擴充功能。Developer 擴充功能可以理解為讓 goose 處理本機檔案和指令的工具模組。預設設定通常會包含此功能。如果它回覆自己沒有檔案工具，請在指令中加上：

--with-builtin developer

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

2026-10-09 使用 goose 1.54.0 成功讀取了指定檔案的第一行。第一次回覆可能需要約一分鐘。

接著，在 OmniProxy 的呼叫記錄中確認來源和模型名稱。

啟動

能進入工作階段

goose session
Provider 是剛新增的
模型名稱在清單中

任務

它確實執行了

例如列出目前目錄
查看它的回覆
不要只確認儲存成功

記錄

閘道看得到

位址以文件範例為準
金鑰不要寫入儲存庫
模型 ID 與清單一致

儲存 Provider 後，仍需透過一次實際工作階段進行確認。

常見錯誤

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

官方參考資料

安裝方式請參閱 Install goose。自訂 Provider 請參閱 goose providers。範例中使用的模型 ID 請參閱 xAI 模型頁面和 GPT-6 Luna。

用你自己的 OmniProxy 設定取代每個佔位符。不要發布真實金鑰。

儲存成功或 HTTP 200 不單獨代表完整 Agent 相容性。請在 OmniProxy 呼叫記錄中確認來源和模型。

官方來源 · goose ↗