【2026 最新】safeagents 教學：Claude Code、模型與 Proxy 怎麼接？四個測例看懂攔截

你替 Claude Code 裝了安全 Proxy，畫面也出現警告，是否就代表危險動作已被攔住？這篇 safeagents 教學先幫你分清三件事：請求有沒有經過代理、規則有沒有發現問題、工具呼叫最後有沒有被送回執行層。三者的答案可能不同。

本文寫給第一次接觸 Agent 安全接線、願意跟著終端機操作的讀者。先用白話圖解認識模型、Proxy 與 harness，再用四個只傳 JSON、不執行工具的測例觀察放行與攔截，最後接回你原本能正常使用的 Claude Code。你需要 Git、Python 3.11 以上及 uv；接真實模型時，另需原本已可用的 Claude Code 登入或 API 憑證。

2026 年 10 月 29 日的 官方 Issue #6，就有人把模型伺服器、safeagents 與 harness 的關係搞混。本文談的是 huggingface/safeagents 這個本機代理專案，所有接線與測例固定在 2026 年 10 月 31 日查核的提交 9caa9e6，避免後續改版讓步驟對不上。

先說結論：警告、判定與阻擋要分開看

• 接線口訣：模型提案 → Proxy 檢查 → harness 執行。請求先由 harness 經 Proxy 送到模型，工具提案再沿原路回來受檢。
• --log-only 是觀察模式，發現問題仍放行；正式模式才會改寫符合阻擋條件的工具呼叫。
• 預設嚴重度門檻是 high。本篇的環境讀取樣式得到 medium 警告，未設 judge 時，預設模式仍放行。

一、safeagents 教學先看懂三個零件

把模型想成提出施工方案的設計師，harness 是拿著工具實作的工班，Proxy 是夾在兩者之間的檢查站。模型說「讀取這個檔案」，實際打開檔案的是工班；檢查站要在工班收到提案之前處理它。若你還不熟這一層，先讀 Agent Harness 是什麼，再回來看接線會容易很多。

模型端點是提供模型回應的 API 位址；Proxy（代理）負責轉送請求並檢查回來的工具呼叫；harness（執行層）在本篇就是 Claude Code。依 專案的 Claude Code 接線文件，把 ANTHROPIC_BASE_URL 指向本機代理，就能讓這條模型 API 路徑經過 safeagents。這個變數與作業系統的全域 HTTP Proxy 設定不是同一件事。

你可以接雲端模型，也可以把相容的本機模型伺服器放在上游，但上游協定要與 harness 相容。safeagents 文件列出 Anthropic Messages 與 OpenAI Chat Completions 兩種格式；不能因此推論把任意模型位址填進 Claude Code 就能運作。下方提供的 Claude Code 接線範例以 Anthropic API 為上游；Anthropic 的 gateway 文件也明確表示，經 gateway 使用非 Claude 模型不在其支援範圍。

二、先固定版本，再準備不碰帳號的測試場

第一個痛點是「昨天可用，今天換了規則」。固定提交與依賴比只記住套件名稱更有用。在一個新的練習資料夾執行下列指令；uv sync --frozen 依專案鎖定檔建立虛擬環境，不需要把套件裝進你的全域 Python。

git clone https://github.com/huggingface/safeagents.git safeagents-lab
cd safeagents-lab
git checkout 9caa9e613dd2684eddf887835b0c170a3a7ecbfb
uv sync --frozen
git rev-parse HEAD

核對最後輸出等於上面的完整提交碼，再繼續。這次 AlphaLab 的離線執行環境是 macOS、Python 3.12.13、safeagents 0.0.1 與 atif-scan 0.8.15。以下結果屬於這組固定版本、假模型的 JSON 回應測試，並非連接 Claude 雲端模型的端到端成績。

專案附的 官方模擬器會啟動本機假模型伺服器，再讓指定的工具提案穿過 Proxy。它只檢查回應裡還有沒有 tool_use 區塊，沒有工具執行器。即使輸出寫 harness runs it，這裡的意思也是「提案仍可供執行」，沒有真的執行其中命令。

為了只看四個情境，在專案根目錄用文字編輯器新增 four_cases.py，貼入下列內容。它沿用官方資料，只選原始清單的第 1、12、4、7 號項目；Python 的編號從 0 開始。固定提交後，這四項的意義才會保持一致。

import sys
sys.path.insert(0, 'scripts')
import simulate

simulate.SESSION = [simulate.SESSION[i] for i in (1, 12, 4, 7)]
simulate.main()

這段程式省略的是結果自動斷言：它會印出結果，仍要由你依下節逐項核對。假模型的請求及回應格式可對照 官方 Proxy 測試；它不是能直接套到正式系統的測試涵蓋率報告。

三、safeagents 教學：四個測例比較三種設定

第二個痛點是把警告當成阻擋。先觀察，再改門檻：開兩個終端機，都切到剛才的專案目錄。終端機 A 啟動觀察模式，18081 是假模型，18787 是本次刻意指定的 Proxy 埠；不要把兩者填反。

uv run --frozen safeagents http://127.0.0.1:18081 18787 --log-only --journal ./four-log.jsonl

終端機 B 執行四個測例。模擬器會在執行期間自行啟動假模型，完成後關閉它：

uv run --frozen python four_cases.py --proxy http://127.0.0.1:18787 --agents 1 --delay 0 --loops 1

接著在終端機 A 按 Ctrl+C 關閉 Proxy，用下面第一行重新啟動，再於 B 重跑同一行測試；記下結果後再停止 A，改用第二行啟動，最後重跑 B。每次只開一個 Proxy，三份 journal 分別保存。

uv run --frozen safeagents http://127.0.0.1:18081 18787 --journal ./four-default.jsonl

uv run --frozen safeagents http://127.0.0.1:18081 18787 --block-severity medium --journal ./four-medium.jsonl

① 正常讀取：先有一個應該通過的對照

第一項是宣告過的 Read 工具，參數是 src/parser.py。三種設定均保留工具提案。你要確認 Proxy 顯示 PASS，模擬器也回報提案仍在；若正常案例都被擋，先排查工具名稱、請求格式及你是否額外修改規則。

② 未宣告工具：模型不能自己新增工具清單

第二項回傳 shell_exec，但請求只宣告了另一組工具。觀察模式顯示 FLAG 並保留提案；兩種正式設定都改成文字通知，理由是 undeclared tool。這是在測 Proxy 的協定防線，並不代表真實 Claude Code 每次都會出現這種異常。

③ 陌生目的地主機：檢查提案的去向

第三項是官方假資料中的上傳提案，目的地主機未出現在請求上下文，也不在內建允許清單。觀察模式仍保留它，正式模式則攔下。這裡測的是參數中的主機名稱，不是實際對外連線；請讓樣本留在模擬器裡，不要把那段上傳字串貼到 Shell。

④ 可疑環境讀取：最能看出 WARN 與 BLOCK 的差別

第四項包含 /proc/1/environ 的讀取樣式，也只存在於假提案裡。在這組固定環境中，它命中 side_channel.harness_secret_read，嚴重度為 medium。預設 high 門檻且無 judge 時顯示 WARN，提案仍在；改成 --block-severity medium 才變成 BLOCK。在 macOS 上也能觀察這個 Linux 路徑樣式，因為測的是字串與規則，沒有打開該檔案。

四個樣本每種設定各跑一次，足以說明這三種設定的差異，不足以估計真實誤擋率或漏擋率。同樣地，將門檻調低會擴大阻擋範圍；正式採用前要補上你自己的正常工作案例。原理可對照 Guard 的嚴重度與放行邏輯，而不是只看終端機的顏色。

四、接回 Claude Code：驗證的是路徑，不只是能聊天

第三個痛點是代理啟動了，Claude Code 卻仍走原本路徑。先在空白專案做正常唯讀操作：確認你原本能正常啟動 Claude Code，再開一個終端機啟動連向 Anthropic 的觀察模式。這一步會使用你原本的帳號或 API 計費方式，不是前面的免費假模型測試。

uv run --frozen safeagents https://api.anthropic.com --log-only

另一個終端機切到一個沒有私人檔案的練習專案，用單次命令設定本機端點。上游和本機位址都不手動加 /v1；Claude Code 的請求本身會帶端點路徑。

ANTHROPIC_BASE_URL=http://127.0.0.1:8787 claude

進入後執行 /status，核對 Anthropic base URL 是本機代理位址，再要求「只列出目前目錄的檔名，不修改檔案」。看 Proxy 是否出現對應請求和 Bash 或 Glob 工具紀錄。Claude Code 官方 gateway 接線指引也用狀態頁確認 base URL。單純收到聊天回覆只能證明某條連線可用，還要對照代理紀錄才完成這次驗收。

這裡只改目的地，沿用既有登入，不把 API key 寫入命令或文章。若組織已鎖定 provider 或 gateway，先使用組織允許的環境；別用修改安全設定來硬接。若收到 401，檢查原本登入、憑證來源與上游是否一致；若是連線拒絕，先核對 Proxy 是否仍在跑及埠號是否相同。

五、誤擋、紀錄、延遲與還原：收尾也要有驗收

第四個痛點是「擋太多，就整個關掉」。先查具體理由：依 該版本的 host policy，主機可由請求上下文或允許清單取得；模型先前自己寫出的訊息不算授權來源。這是字串與上下文規則，並非網路防火牆或使用者意圖證明。被誘導寫入上下文的網址仍需要其他防線處理。

確定某個文件網站是工作必需後，才用 --allow-host docs.example.org 加入你核准的主機；此選項也涵蓋其子網域。不要為了讓測例變綠，就把所有未知主機放行。內建清單包含 GitHub 等開發站點，因此「對話沒提到的每個網站都會擋」也是錯的。詳細選項見 官方命令文件。

預設可用 uv run --frozen safeagents inspect 查看 journal 裡的可疑、標記與阻擋項目。前面的實驗用了自訂 --journal 路徑，請直接用編輯器打開 four-default.jsonl 等檔案，核對 verdict、reason 與 signals，不要誤看預設檔。journal 會保存完整參數；分享前先移除其中的私人路徑、憑證或內容。

要評估誤擋，先蒐集一批你已確認應放行的正常任務，再算「其中被阻擋的數量 ÷ 正常任務總數」。延遲則把相同假回應分別直連與經 Proxy 各跑多次，分開記錄首段文字、完整工具參數及總完成時間，再比較中位數與較慢尾端。本文沒有做這組成對延遲量測，因此不提供零延遲或速度提升數字。

還原時先退出 Claude Code，再於 Proxy 終端機按 Ctrl+C。本文使用的單次 ANTHROPIC_BASE_URL=… claude 不會把變數永久寫進你的 Shell；重新用原本方式啟動即可。若你曾自行放進設定檔或用 export 持續設定，則要刪除那項設定或恢復原值，再以 /status 確認回到原路徑。

有兩個邊界要放進驗收清單：這個固定版本的 掃描器原始碼會在掃描例外時記錄錯誤並回傳空訊號，請求層規則仍照常檢查；所以還要監看掃描錯誤，不能把它視為整條鏈必然 fail-closed。若另外啟用 judge，使用者任務、工具參數與發現訊號會送往你指定的 judge 端點；先確定該端點可處理這些資料，再接正式任務。本文未啟用 judge。

最後，把防線放對位置：safeagents 檢查的是經過它的模型工具提案，權限、檔案隔離與對外網路仍由執行環境限制。可搭配 Agent 執行期控制、Agent 憑證安全與 AI Coding Agent 對外連線稽核，建立彼此補位的限制；Claude Code 安全文件也說明了權限與安全機制的角色。

FAQ：新手最常混淆的八件事

1. 裝了 safeagents，就等於換了模型嗎？

不是。Proxy 是中繼檢查站，上游模型端點仍需另外存在。先保留原本可用的模型與登入，比同時換模型、換代理更容易排查。

2. FLAG 就代表已擋住嗎？

不是。這個專案的 FLAG 指觀察模式下「原本會擋，但目前放行」；正式改寫回應的是 BLOCK。

3. WARN 可以當成安全通過嗎？

不可以把它當成零風險證明。它表示有發現訊號；在本文無 judge、high 門檻的環境讀取案例中，提案仍被保留。

4. 四個測例通過，就能證明模型可信嗎？

不能作此推論。測例只驗證四個固定輸入與這組規則的處理方式；模型在其他任務或上下文的表現仍未涵蓋。

5. 可否直接拿真實金鑰測讀取與外傳？

先用本篇的假模型流程。這裡沒有工具執行器，也不需要放入金鑰；測試識別規則不必先讓機密暴露。

6. 一定要再付費接 judge 嗎？

不必。本文三種設定都未使用 judge。選配 judge 會接收任務、工具參數與訊號。此版本遇到 judge 錯誤時預設放行並記錄；加上 --judge-fail-closed 才在 judge 失敗時阻擋可疑提案，這個選項不會改變前述掃描器例外的處理。

7. 本機模型的 OpenAI API 能直接接這條 Claude Code 示範嗎？

先核對協定。Proxy 支援的格式、harness 需要的格式與模型本身能否完成工具回合，是三個獨立條件；本文不把它們視為可任意互換。

8. 為何少了一則紀錄，不一定是沒有發生呼叫？

因為 journal 著重保存非單純通過的呼叫；正常 PASS 要同時查看 Proxy 終端機與請求路徑。還要排除看錯自訂 journal、連到另一個埠或另開了一個未經代理的工作階段。

給新手的三個重點

• 先畫出請求與工具提案的雙向路徑，再填 base URL。
• 同一個假提案換設定重跑，才能看懂 FLAG、WARN 與 BLOCK 的差異。
• 把正常任務當作對照組，保留每次版本、門檻與紀錄，才有辦法討論誤擋。