Phantom Secrets：讓 AI 編碼代理看不見真實密鑰的本機代理與 MCP 服務

適合誰

如果你把 AI 編碼代理接進了日常開發，而專案裡的 .env 存著真實密鑰，那麼記錄檔、錯誤回顯、上下文片段都可能成為密鑰外洩的路徑。Phantom 適合這樣一類人：需要在「應用照常拿到真值」和「代理永遠看不到密鑰值」之間劃一條硬邊界的開發者，以及需要統一發放、輪替密鑰又不想把密鑰下發到每個人工具鏈上的團隊。

它的形態是「本機代理 + MCP 伺服器」：專案密鑰被替換成帶作用域的 phm_ 佔位符，應用透過一台經過認證的本機代理去取真實值，代理端只接觸看不到值的 MCP 工具，用來盤點、診斷和發起受控請求。適用前提是你願意在本機常駐一個代理行程，並把 .env 的改寫納入自己的版本控制流程——這一步不是可以隨手跳過的動作。

3 分鐘完成第一次嘗試

推薦的官方路徑是 Homebrew。儲存庫給出的 macOS 安裝是一條三步鏈路，先 tap、再 trust、最後 install；裝出來是 phantom 與 phantom-mcp 兩個執行檔，對應儲存庫標註的 v0.7.9 版本。

brew tap ashlrai/phantom
brew trust --formula ashlrai/phantom/phantom
brew install ashlrai/phantom/phantom

前置條件：macOS 上已裝好 Homebrew；若不走 Homebrew 而選擇自行建置原始碼，儲存庫把編譯工具鏈版本釘死，建置環境需要符合對應版本的 Rust 工具鏈。

接下來是按順序的兩段設定。先進入專案目錄執行 phantom init；請注意這是寫入操作——它會改寫該專案的 .env，把真實鍵值換成 phm_ 佔位符，檢核點是在執行前確認 .env 已備份或已提交，並在命令輸出裡核對替換筆數是否與預期一致。第二段按客戶端寫入設定：

phantom init
phantom setup --client claude

之後用唯讀的一步做低風險驗證：phantom list 列出你的密鑰清單但不顯示任何值。可觀察的成功訊號是終端列出了項目名稱、每條後面沒有任何真實密鑰字元；再讓代理讀一次儲存庫，它拿到的是 phm_ 開頭的東西而不是真值。

完整命令與參數說明請對照官方儲存庫 https://github.com/ashlrai/phantom-secrets

使用案例

案例一：給代理一條「能看清單、看不見值」的通道。代理端拿到的 MCP 工具是 value-blind 的，涵蓋盤點、診斷和受控請求三類用途；儲存庫對這些工具的定位是能力、狀態與儲存庫狀態檢查，不觸發任何 provider 端動作。於是你可以放心讓代理回答「這個專案設定了哪些密鑰、目前鏈路通不通、儲存庫裡哪些檔案引用了佔位符」——代理既不會回傳密鑰值，也不會在檢查過程中順手改動雲端資源。

案例二：讓業務程式碼繼續用真值跑通，同時把真值擋在代理視線之外。替換發生在初始化階段：.env 裡的真實鍵值變成帶作用域的 phm_ 佔位符，應用照常讀取環境變數，發出的請求被本機代理接手、由代理在認證之後取回真值。代理端的受控請求入口與清單、診斷入口共用同一套「不見值」約束，所以應用跑得通，代理依然拿不到密鑰本身。需要注意，儲存庫素材只說明代理是「經過認證的」本機代理，認證方式的具體形式並未展開，這一層請以儲存庫描述為準。

使用邊界

第一，phantom init 會改寫 .env，是貨真價實的寫入操作。執行前先備份或提交，並且不要把替換前後的差異直接貼進公開管道。

第二，代理端工具的值盲性質只保證「看不見值」，不等於「什麼都能做」。儲存庫把它定位為能力、狀態與儲存庫狀態檢查，不代你發起 provider 動作；真正的雲端呼叫發生在應用經本機代理發起的請求鏈路上，排查時要分清這兩段。

第三，它不是零風險的工具：它要讀取本機的 .env 和客戶端設定檔，本機代理還會把請求送到第三方 provider，密鑰依然在你的機器與該 provider 之間流動。是否接受這條鏈路，取決於你的組織是否允許代理端存在它。

第四，儲存庫中的安裝方式與命令說明會隨版本變動，升級前請回到官方儲存庫核對。