裝好 Agent 工具的頭十分鐘：七項驗證清單（Chinese original）

你剛裝好一個 AI agent 工具——可能是 Cursor、Trae、Claude Code、Codex、OpenClaw、Hermes Agent、DeepSeek Harness、WorkBuddy 或豆包工作——然後呢？多數人的下一步是立刻丟一個大任務過去，然後在「它好像壞了」和「它好像亂做了」之間反覆猜測。

更好的下一步是花十分鐘跑完這張清單。它驗證的不是「這個工具好不好用」,而是你這台機器上的這一套裝好了沒有:工具能不能跑、能不能連到模型、能不能讀到你的檔案、能不能寫、權限邊界在哪、出錯時日誌在哪。這七件事各自對應一個獨立故障層，十分鐘裡逐層確認，之後出問題你就不用猜——你已經知道每一層長什麼樣子。清單是工具無關的:IDE 形態、Terminal（終端機）形態、常駐平台形態都適用，每項檢查都給「怎麼做」與「通過標準」。

1/8使用者請求

任務用自然語言進來。harness 要把它變成模型能處理的東西。

圖：七項檢查驗的就是這個迴圈——模型決定下一步,harness 執行工具呼叫，結果回灌給模型，循環到任務完成。檢查二驗「模型」那一格，檢查三、四驗「工具」那一格，檢查五驗圍欄，檢查六驗整個迴圈。

使用前須知

工具已按官方方式安裝完成。沒裝完就別開始——開發環境設定那篇先走一遍。
手上有模型存取權：雲端供應商的 API Key,或本地模型服務已在跑。概念不熟先看第一次呼叫 LLM API。
建一個 scratch 目錄(例如 ~/agent-test/),清單裡的讀寫實驗都在裡面做，不碰你的真實專案。
每項檢查一分鐘上下；任何一項失敗就停在那裡修,不要帶著壞掉的層往下走。

步驟

步驟一：確認它跑得起來

最低標準：工具能啟動、能出現互動介面，而不是閃退或卡住。

IDE 形態(Cursor、Trae):打開編輯器，叫出 agent 面板，面板能載入。
終端機形態(Claude Code、Codex 這類 CLI（命令列介面）):在 Shell（殼層）裡執行工具指令，加上 --version 或 --help;或直接啟動進入互動模式。
常駐平台形態(Hermes、OpenClaw、DeepSeek Harness、WorkBuddy、豆包工作這類常駐服務或平台式工具):確認主程序能啟動，狀態指令(如 Hermes 的 hermes gateway status)回報正常。

預期輸出:版本號、說明文字，或一個等你輸入的提示符。終端機形態用 echo $? 看退出碼,0 才算過。啟動就失敗的問題幾乎都在環境層:PATH 沒設對、依賴沒裝齊、裝了但沒重開 terminal。這一層壞掉時，跟 AI 一點關係都沒有——先修環境。

步驟二：確認它連得到模型

發一句最小提示，例如「回覆 ok 兩個字就好」。

預期輸出:一句連貫的回覆。這一步驗證的是工具到 LLM（大型語言模型）之間的整條路：憑證、網路、模型名稱。失敗的典型長相:

401/403 或「invalid api key」:API Key 錯，或環境變數與 .env 沒被工具讀到(改了 .env 沒重啟是經典款);
連線逾時：網路或代理問題，公司網路與 VPN 環境尤其常見;
「model not found」:模型名稱打錯，或你的帳號沒有該模型的存取權;
帳單類錯誤：配額用完或付款方式失效。

順帶建立成本感：一次最小提示消耗的 Token（詞元）少到可以忽略，但從這一步開始，你的每次對話都是真實計費的。

步驟三：確認它讀得到檔案

在 scratch 目錄建一個測試檔，內容放一個不會被猜到的標記詞:

mkdir -p ~/agent-test && echo "紫丁香河馬 42" > ~/agent-test/probe.txt

然後要求工具：「讀取 ~/agent-test/probe.txt,把裡面的標記詞原樣告訴我。」

預期輸出:工具發起一次讀檔的 Tool Call（工具呼叫）,並回你「紫丁香河馬 42」。兩個失敗模式要分清:

讀不到:權限或範圍問題——工具可能只被允許讀工作區/專案目錄以內,~/agent-test 在範圍外。把測試檔放進它的工作區再試，並記住這個邊界。
更危險的：沒讀卻答了。標記詞的作用就在這裡：它猜不到。如果工具不呼叫讀檔工具就「回答」出錯誤內容，那是 Hallucination（幻覺）。這一分鐘的教育意義比整個清單其他部分加起來都大：它說它做了，不代表它做了；驗收永遠看證據，不看口供。

路徑細節也在這一步暴露:~ 會不會展開、相對路徑以哪裡為基準(PATH 與路徑)、Windows 與 Unix 分隔符——之後任務裡檔案找不到，多半是這裡沒搞清。

步驟四：確認它寫得了檔案

要求工具：「在 ~/agent-test/ 建立 out.txt,內容寫入今天日期加一句測試成功。」然後你自己去確認:

cat ~/agent-test/out.txt

預期輸出:檔案真實存在、內容正確、時間戳是剛剛。同樣的分野：工具「說寫好了」不算數，磁碟上有才算數。寫入失敗的典型原因：工作區外的目錄唯讀、權限模式設成「只讀」或「每次詢問」而沒人按批准、磁碟滿。改檔比建檔更嚴的工具也不少——順便試一次「把 out.txt 裡的一句話改掉」,確認修改能力。

步驟五：確認權限邊界

前四步驗證能力，這一步驗證圍欄:它能做什麼之前，先搞清它被允許做什麼、什麼時候會停下來問你。

具體做三件事:

找到權限/批准設定：每個工具都有(名稱各異——permission modes、approval policy、YOLO/auto-accept 之類)。看清楚有哪幾檔、現在是哪一檔。
觸發一次需要批准的動作：讓它跑一個 shell 指令(例如把 ~/agent-test/probe.txt 複製一份),觀察它是直接執行、還是先跳出確認。記下這個行為——這就是你的 Sandbox（沙箱）邊界在實際運作的樣子。
把設定調到最嚴格的一檔，用一週再說。第一週就開全自動(auto-accept、跳過所有確認)的人，遲早會見識到 agent 對「刪掉重來」的字面理解。Shell（殼層）指令一旦執行就沒有 undo。

預期輸出:你能用一句話說出「這個工具在我的機器上，不問我就能做 X,做 Y 之前會問我」。說不出來，就還沒通過。

步驟六：跑一個真實的端到端任務

玩具測試通過後，用一個你本來就要做的真實小任務驗收：把一份文件整理成檢查清單、在十個檔案裡統一改一個寫錯的詞、寫一個你明天真的會跑的腳本。規模控制在「你自己做要半小時」以內。

觀察重點不是結果，是過程:Harness（執行環境／框架）驅動的 AI Agent（代理）應該呈現「計畫 → 工具呼叫 → 觀察結果 → 調整」的迴圈，而不是一口氣吐一大段沒驗證過的輸出。任務太長時留意上下文管理——Context Window（上下文視窗）裝不下時，好的工具會壓縮或分段，差的工具會開始遺忘與胡說。

預期輸出(驗收標準):產出物你自己檢查過、願意直接使用；過程中它對檔案的每一次讀寫你都對得上帳。做不到就縮小任務重跑——任務粒度是 agent 時代的核心技能，值得在第十分鐘就開始練。

步驟七：知道失敗時日誌在哪

最後一分鐘，把「出事時去哪裡看」變成肌肉記憶，而不是半夜兩點滿世界找:

終端機形態：錯誤通常直接印在畫面(stderr);把它完整複製下來，不要只記「它紅了」。
IDE 形態：找輸出面板(output panel)或設定裡的日誌入口。
常駐平台形態：找它配置目錄下的日誌檔——以 Hermes 為例,gateway 日誌在 ~/.hermes/logs/gateway.log,hermes gateway status 會報告異常退出與心跳過期;Linux/macOS 上還能對程序發 kill -USR2 拿到執行緒堆疊而不停機。
通用習慣：記下精確的錯誤文字去搜尋；多數「新問題」都是別人踩過一萬次的舊問題。

預期輸出:你能指著螢幕說「日誌在這裡」,並且知道怎麼把最近一次錯誤完整撈出來。

七項檢查，對應七種故障層

卡在哪一步	壞的大概率是哪層	第一個動作
一：跑不起來	環境(PATH、依賴、安裝)	讀啟動錯誤；重開 terminal
二：連不到模型	憑證/網路/配額	核對 API Key 與環境變數與 .env;換網路試
三：讀不到檔案	工具權限/工作區範圍	把檔案放進工作區再試
四：寫不了檔案	權限模式/批准流程	查批准設定；看有沒有人該按確認
五：說不清邊界	配置理解不足	重讀工具的權限文件，這不能跳
六：真實任務失敗	任務粒度/上下文	縮小任務；拆步驟
昨天好今天壞	憑證過期/版本更新/網路變動	先看日誌再重跑步驟二

下一步

七步全綠，是時候理解你剛驗證的東西到底是什麼:AI Agent 是什麼
想親手拆開迴圈看內部:不用框架手寫一個 Hello World Agent
名詞還不夠熟:AI 詞彙起手式
把 agent 接進通訊軟體、隨身可用:從 Telegram 這條最簡單的路開始
針對單一工具的深入教學:Claude Code 指南、安裝 Hermes Agent 與 Hermes 飛書集成進階篇
十分鐘清單背後的教訓都來自真實事故:十天踩坑回顧