Butterfish

一句話介紹

Butterfish是一種開源的Shell封裝工具，它為bash和zsh增加了AI問答、指令生成、自動補全以及Agent執行等功能，讓使用者無需複製終端輸出，即可獲得與上下文相關的協助。

軟體本身採用MIT許可證且免費，但預設需要使用者自己的OpenAI API金鑰，模型調用產生的Token與服務層費用由使用者承擔。

Butterfish是什麼

Butterfish Shell由Peter Bakkum維護，主要服務那些長期在macOS或Linux終端上工作的開發者及運維人員。它並不會取代系統的Shell，而是以現有的bash或zsh為基礎，再在其外層建立一個會話環境，並截取輸入與輸出內容。

一般的指令仍由 Shell 來執行，而以大寫字母開頭的自然語言輸入則會被傳送給模型。Butterfish 會將最近的指令、輸出結果以及之前的對話記錄納入上下文中，因此可以直接詢問上一條指令為何會失敗。

當前維護狀態

截至2026年8月20日，官方GitHub的最新發布版本為v0.4.3，發布記錄中包含對Agent輸入處理、Shell啟動提示以及低延遲自動補全等功能上的修復。Go模組頁面也列出了v0.4.3版本，並確認其採用MIT許可證。

專案仍處於0.x版本，無法以穩定的1.0介面來假設其相容性。升級前應閱讀變更內容、保留自訂提示設定，並在非關鍵環境中驗證Shell互動及模型參數。

主要功能

上下文終端問答

在Butterfish Shell中，只要以大寫字母開頭輸入，就能向模型提問。近期在Shell中的輸入內容、輸出結果以及AI的回覆都會被記錄下來，這樣便可以用來解釋錯誤、進一步追問，或是根據目前的狀況建議下一步該做什麼。

命令自動補全

當使用者輸入指令時，Butterfish可以根據Shell的歷史記錄以及先前的AI建議，預測出完整的指令，然後讓使用者透過Tab鍵來確認該指令。自動補全功能會不斷向模型發送請求，這可能會增加費用，同時也有可能將使用者正在輸入的敏感資料傳送到模型服務中。

Agent Mode

以單個感嘆號開始任務會進入Agent Mode，模型可以根據目標反複提出並運行命令，再根據結果調整策略。目前的安全模式會保留人工確認環節，而雙感嘆號則會進入無確認執行的危險模式。

Action Mode

以單個@開頭的請求，會要求模型產生一條Shell指令，並將該指令顯示在終端中，讓使用者能夠檢查。而使用雙@的話，則會立即執行所產生的指令，但這種方式應該只在目標、目錄以及可能產生的副作用都十分明確的情況下才考慮使用。

獨立prompt命令

prompt子命令可以直接傳送文字，也能將管道輸入與提示語結合後，以流式方式回傳模型結果。它適用於解釋設定、摘要文本，或是在腳本之外進行一次性的問答。

gencmd命令生成

gencmd會將自然語言轉換為Shell命令，並讓使用者能先檢查結果。強制選項則會跳過確認步驟，直接執行生成的命令，這在進行刪除、覆寫、網路下載或權限操作時，風險相當高。

exec錯誤修復

exec用於執行指定的命令，且在執行失敗時會請求模型進行分析並提出修復建議。它雖可減少複製錯誤日誌的步驟，但建議仍需結合作業系統、工具版本以及專案狀態，由人員進行確認。

• 在終端中直接進行帶Shell歷史上下文的AI問答。
• 根據當前輸入和近期命令提供Tab自動補全。
• 將自然語言轉換為可檢查的Shell命令。
• 運行命令並針對錯誤輸出生成修復建議。
• 使用Agent Mode循環執行與調試多步目標。
• 使用Action Mode來產生一條適合當前任務的命令。
• 查看並編輯發送給模型的系統提示和命令提示。
• 連接OpenAI或實現Responses流式介面的相容模型服務。
• 透過標準輸入將檔案或其他命令輸出交給模型處理。

Shell模式如何工作

1. 使用者啟動Butterfish Shell後，該程式會在封裝層中啟動原有的bash或zsh。
2. 普通鍵盤輸入和命令輸出繼續在終端中顯示，並寫入記憶體歷史。
3. 普通命令會直接傳交給Shell，而大寫提示及特殊模式前綴則由Butterfish來處理。
4. 發起模型請求時，程式從系統資訊、提示模板和近期歷史構造上下文。
5. 請求透過OpenAI Responses介面或相容伺服器發送，並將結果以流式方式寫回終端。
6. 若模型建議命令，安全模式先將命令放入Shell供用戶檢查與編輯。
7. 用戶繼續執行、追問或退出，當前會話歷史隨上下文窗口被截斷和整理。

記憶體中的歷史記錄並不代表資料永遠不會離開裝置。一旦發出 AI 請求，所選定的指令、輸出內容、提示以及系統資訊都會被傳送到已設定的模型伺服器上。

安裝教學

透過Homebrew安裝

MacOS用戶可以透過維護者提供的Homebrew Tap來進行安裝，之後再啟動Butterfish Shell。安裝完成後，請先檢查版本號及說明文件，以確認所使用的確是預期的二進位檔案。

1. 確認設備為受支援的macOS，並且已安裝Homebrew。
2. 從維護者的Tap安裝Butterfish，不要使用渠道不明的同名軟體包。
3. 運行版本命令並與官方最新發布核對。
4. 首次啟動Shell模式，根據提示配置模型API密鑰。
5. 在臨時目錄中運行普通命令和簡單問答，驗證Shell輸入輸出沒有異常。
6. 確認安全模式會在執行生成命令前等待人工檢查。

透過Go安裝

macOS和Linux也可以使用Go工具鏈來安裝最新的模組，這適合那些不想使用Homebrew，或是希望從原始碼開始編譯的人士。安裝完成後的二進位檔案通常會存放在Go環境的bin目錄中，因此必須確保該目錄已經被加入PATH環境變數中。

1. 安裝目前可用的Go工具鏈，並確認Go環境目錄。
2. 使用官方模組路徑安裝最新Butterfish命令。
3. 把Go的bin目錄加入PATH，重新打開終端。
4. 檢查Butterfish版本、許可證和幫助輸出。
5. 首次啟動時配置金鑰，並用無副作用問題測試連接。

首次配置與API密鑰

在首次呼叫時，Butterfish會要求使用者提供OpenAI API金鑰，並將其儲存在使用者設定目錄中的環境檔案中。此金鑰與ChatGPT的網頁訂閱服務無關，是否有餘額以及是否具有存取權限，則取決於該獨立的API帳戶。

• 只使用權限與額度受控的項目金鑰，不要重複使用高權限生產金鑰。
• 限制配置目錄和金鑰檔案的系統權限，避免其他本機用戶讀取。
• 不要把配置目錄提交到Git、同步到公共網盤或複製進問題報告。
• 發現密鑰進入日誌、截圖或終端共享後應立即撤銷並輪換。
• 連接相容伺服器時，確認密鑰會隨請求發送給該伺服器。
• 團隊設備應分別分配密鑰和預算，以便審計與停止異常消費。

日常使用教學

1. 進入專案目錄並啟動Butterfish Shell，先使用一般指令來查看目前的狀態。
2. 遇到錯誤時用大寫自然語言詢問原因，並要求模型解釋而不是立即修復。
3. 檢查回答引用的命令、路徑、工具版本和操作系統差異。
4. 需要一條命令時使用安全Action Mode，讓結果先進入終端而不是直接執行。
5. 複雜任務可使用Agent Mode，但每次都審查命令和輸出。
6. 完成後查看是否生成敏感日誌，並退出包裝Shell。

Agent與Action安全用法

自動執行模式可能會刪除檔案、覆寫資料、上傳機密資訊、安裝惡意軟體，或是改變系統權限。即便任務看起來很簡單，也請勿在生產伺服器、管理員Shell或包含未備份資料的目錄中啟用此模式。

• 先運行只讀檢查，再考慮寫入、安裝、移動或刪除操作。
• 使用普通用戶、容器、臨時分支或一次性虛擬環境來限制影響範圍。
• 執行前展開變數、通配符、遞歸目標和當前工作目錄。
• 對下載並執行腳本、提權及磁碟命令保持人工確認。
• 重要修改先提交版本控制或建立可驗證備份。
• 不要把模型回答當作命令安全審計或訪問授權。

模型選擇與本地模型

目前，GitHub的主分支文檔中，將Shell和prompt的預設模型指定為GPT-5.5，並使用高強度的推理方式。在快速模式下，還會請求Responses API的優先服務層。使用者可以透過參數來改變模型、推理強度、最大輸出量以及服務層等設定。

官網上較舊的頁面仍顯示GPT-4 Turbo和GPT-3.5 Turbo的範例，這些屬於歷史文件中的資訊。實際的預設值應以已安裝版本的說明文件以及當前的程式庫為準，因為模型名稱和可用性會隨著API平台的變更而改變。

Butterfish也能連接並使用能夠支援OpenAI相容的流式回應介面的本地或遠端伺服器。此種相容性不僅需要路徑類似，還必須能正確地產生流式結果；提示模板主要是為了適應OpenAI而設計的，因此本地模型的表現可能會有明顯差異。

價格與使用成本

Butterfish程式本身是免費的，沒有官方會員套餐、月費或按席位計算的費用。MIT許可證允許根據相關條款來使用、修改和散布該程式，因此使用者的實際成本主要來自於模型API、優先服務層、本地運算能力以及維護成本。

開啟自動補全後，停頓期間可能會頻繁請求模型，這是日常用量的主要來源之一。可以關閉自動補全功能，或是增加觸發前的等待時間，同時取消不必要的優先級服務層。

提示透明與自訂

Butterfish將系統提示、命令生成以及自動補全的相關資訊儲存在YAML設定檔中，使用者可以查看並編輯這些資料。在進行修改之後，應取消自動替換的選項，否則當程式更新提示庫時，可能會覆蓋掉自訂的版本。

• 檢查Shell系統提示是否符合團隊安全與命令風格。
• 要求命令生成預設解釋參數、路徑和副作用。
• 為生產、資料庫和雲端資源設定禁止自動執行的明確規則。
• 升級後比較預設提示變化，不要盲目保留過時模板。
• 使用版本控制保存脫敏的提示文件，但排除金鑰和本機路徑。
• 提示規則只能降低誤操作機率，不能替代作業系統權限和人工審批。

隱私與資料安全

Butterfish是一種本地的開源CLI工具，它沒有集中的Butterfish帳戶，也沒有用於儲存聊天歷史記錄的服務。當有模型請求時，它仍會將所選定的Shell歷史記錄、命令輸出結果、系統資訊、使用者提示以及AI對話內容，傳送到所設定的API端點上。

在使用詳細模式時，完整的請求與回應內容可能會被列印到終端機上，或是被寫入系統的臨時目錄中作為日誌。終端機的輸出內容通常包含存取令牌、環境變數、資料庫內容以及用戶資料，而調試日誌則應被視為敏感文件。

• 不要在顯示密鑰、生產資料庫記錄或客戶資料後直接發起上下文問答。
• 共享終端、錄影與問題報告前清理Butterfish日誌與Shell輸出。
• 連接第三方或本地相容端點時核查其日誌、訓練和保留政策。
• 限制歷史窗口無法保證秘密一定被排除，應主動避免在會話中輸出。
• 遠端伺服器應使用加密傳輸，不要把認證Token發送給不可信地址。
• 公司環境應先確認代碼、數據和模型供應商使用政策。

支援系統與依賴

適合哪些用戶

• 命令行初學者：可了解命令的含義及錯誤原因，但仍需學習Shell基礎。
• 軟體開發者：根據目前目錄、建構輸出和測試失敗繼續追問。
• DevOps工程師：產生只讀診斷指令並分析日誌，生產變更仍需經過審批。
• 開源愛好者：審查源代碼、提示模板和數據發送邏輯。
• 本地模型用戶：將終端助手連接到相容Responses介面的本地服務。
• 需要可訂製提示的團隊：把命令風格與安全要求寫入透明提示庫。

典型使用場景

• 解釋剛才失敗的建構、測試、套件管理或Git命令。
• 產生用於搜尋檔案、查看連接埠、統計目錄以及過濾日誌的只讀指令。
• 把配置檔案或命令輸出透過管道交給模型摘要。
• 根據工具版本差異調整參數，並解釋每個標誌的作用。
• 在臨時分支中讓Agent運行測試並嘗試修復簡單問題。
• 用本地模型處理不適合發送到公共雲的低風險內部終端任務。

產品優勢

• 直接利用Shell歷史，減少複製命令、錯誤和上下文的往返。
• 包裝中已包含bash或zsh，一般指令的使用方式幾乎不會有變化。
• 問答、單命令和多步Agent有明確的不同輸入前綴。
• 提示模板和原始模型請求可以查看與修改。
• 支援OpenAI預設服務，也能連接相容的本機或遠端模型。
• MIT開源且沒有Butterfish訂閱費，源代碼和行為可審查。
• prompt、gencmd和exec子命令可以脫離完整Shell模式單獨使用。

使用限制與注意事項

• 官方目前主要支援macOS與Linux中的bash和zsh，並未承諾對Windows的原生支援。
• Agent和Action的雙前綴模式會跳過確認，錯誤命令可能造成不可逆損失。
• 模型可能根據錯誤的工具版本、操作系統或路徑生成無效命令。
• Shell的歷史與輸出會成為模型上下文，存在秘密和業務數據洩露風險。
• 自動補全頻繁呼叫API，可能產生超出預期的Token和priority費用。
• 本地相容伺服器必須實現Responses流式介面，普通Chat Completions相容不一定夠。
• 0.x專案仍可能更改參數、預設模型、互動及提示格式。
• Butterfish不是權限隔離、備份、審計、惡意軟體防護或正式運維審批系統。

API、GitHub與開源情況

Butterfish的完整原始碼都儲存在公開的GitHub倉庫中，採用MIT授權條款，且是以Go語言編寫的。該倉庫包含命令入口、Shell包裝程式、使用說明、測試程式、發布相關設定以及依賴項目資訊，開發者可以根據授權條款來審查、修改及散布這些原始碼。

它並非提供遠端服務API的SaaS，而是OpenAI Responses API的用戶端。此外，該專案本身也不是模型，MIT許可證僅適用於Butterfish的代碼，而不包括OpenAI、第三方模型、使用者資料，或是其他相關的許可證。

基本資訊

推薦指數

推薦指數為4.3分，滿分5分。Butterfish將Shell的歷史記錄、透明式提示、單指令與多步驟的Agent功能整合到熟悉的終端介面中，它屬於開源軟體且體積輕巧，同時還能連接本地模型，因此很受那些經常使用命令列的使用者所青睞。

扣分的主要原因在於自動執行時所伴隨的高風險、終端環境的隱私問題、API使用所產生的成本，以及平台支援範圍的限制。它更適合用於有經驗的使用者作為輔助工具，而非讓不熟悉Shell的人隨意執行各種指令。

常見問題

Butterfish免費嗎？

軟體本身免費，且採用MIT許可證，沒有官方的訂閱方案。若要使用OpenAI或其他雲端模型，則需自行支付相關的API費用。

Butterfish和魚殼有關係嗎？

沒有直接關係，Butterfish只是產品名稱。官方目前明確測試的是bash和zsh，不應因為名稱中有fish就假設相容fish shell。

支援Windows嗎？

官方目前的安裝說明僅列出了 macOS 和 Linux，並未承諾支援原生 Windows。WSL 是否適合使用，需根據具體的 Shell、終端及模型設定自行測試。

需要ChatGPT訂閱嗎？

不需要ChatGPT網頁訂閱，但預設需要獨立的OpenAI API金鑰及可用餘額。網頁會員與API計費是不同產品。

預設使用什麼模型？

目前，GitHub的主分支預設會使用GPT-5.5以及高強度的推理模式，而快速模式則會請求優先處理服務。舊版網站上仍有GPT-4 Turbo的示範，實際使用時應參考所安裝版本的說明文件。

可以使用本地模型嗎？

可以連接並使用能夠支援 OpenAI 相容的 Responses 流式介面的本地伺服器。只有支援傳統聊天介面的服務可能無法正常運作，且其模型品質也可能低於預設提示所對應的模型。

Shell歷史會發送到雲端嗎？

在發起 AI 請求時，Butterfish 會將所選擇的近期指令、輸出內容以及對話記錄作為上下文，傳送到已設定的模型端點。敏感的輸出內容不應出現在即將被傳送的會話中。

Agent Mode安全嗎？

單個感嘆號模式仍需仔細檢查模型命令，雙感嘆號會跳過確認，風險極高。建議僅在隔離環境及有備份的臨時任務中使用安全模式。

Action Mode和Agent Mode有什麼區別？

Action Mode只試圖產生一條Shell命令並結束，而Agent Mode則可以分多步執行、觀察結果並調整策略。單一前綴時會預先進行檢查，而雙重前綴則會自動執行。

為什麼自動補全可能很貴？

它會在用戶輸入停止時發起模型預測，高頻請求會累積Token和服務層費用。可關閉自動補全、增加等待時間或選擇更便宜的模型。

可以查看完整提示嗎？

可以編輯本地的YAML提示庫，也能以詳細模式查看原始請求和回應。詳細日誌可能包含機密資訊，使用後要妥善清理。

Butterfish完全離線嗎？

預設情況下並非如此，它會連接到 OpenAI API。唯有在配置了本機相容的模型，且確認所有請求皆指向本機端點時，模型互動才能保持在本機或內網上。