你剛裝好一個 AI agent 工具——可能是 Cursor、Trae、Claude Code、Codex、OpenClaw、Hermes Agent、DeepSeek Harness、WorkBuddy 或 豆包工作——然後呢？多數人的下一步是立刻丟一個大任務過去，然後在「它好像壞了」和「它好像亂做了」之間反覆猜測。
更好的下一步是花十分鐘跑完這張清單。它驗證的不是「這個工具好不好用」,而是你這台機器上的這一套裝好了沒有:工具能不能跑、能不能連到模型、能不能讀到你的檔案、能不能寫、權限邊界在哪、出錯時日誌在哪。這七件事各自對應一個獨立故障層，十分鐘裡逐層確認，之後出問題你就不用猜——你已經知道每一層長什麼樣子。清單是工具無關的:IDE 形態、Terminal（終端機） 形態、常駐平台形態都適用，每項檢查都給「怎麼做」與「通過標準」。
使用前須知
- 工具已按官方方式安裝完成。沒裝完就別開始——開發環境設定 那篇先走一遍。
- 手上有模型存取權：雲端供應商的 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 飛書集成進階篇
- 十分鐘清單背後的教訓都來自真實事故:十天踩坑回顧