【2026 最新】KoboldCpp Agent 教學：本機模型怎麼安全呼叫工具？（權限設定＋唯讀驗收）

你已經在電腦上跑本機模型，聊天也順了；現在想讓它幫你找一份檔案、讀出重點，甚至整理資料夾。KoboldCpp Agent 教學最重要的一課，是先弄清楚「模型會要求什麼」和「電腦真的准它做什麼」是兩件事。

這篇寫給第一次接觸工具呼叫的人。我們從安裝、開啟 Agent、辨認內建工具與 MCP 開始，走完一個只讀檔案的小任務，再用空白練習資料夾理解批准、拒絕與停手。你不需要先會寫程式；每一步都有能親眼檢查的結果。

先說結論：Agent 的安全性是三道閘門

一句話記住：本機 Agent＝模型提出工具請求＋執行程式握有權限＋你決定放行範圍。模型像提出工作單的助理；工具才是鑰匙。把助理放進一個資料夾，卻仍交給它能開整台電腦的鑰匙，就稱不上隔離。

• 先縮工具：第一次只留 read、glob、grep 這類讀取工具。
• 再逐次批准：先選 /confirm on；看清每次工具名稱與參數，才回答 y。
• 最後驗收：回到檔案系統，自己確認讀到的來源、檔案清單與任何寫入結果。

KoboldCpp Agent 是什麼？先分清三個角色

KoboldCpp 原本負責載入 GGUF 模型，提供本機介面與 API。2026 年 9 月推出的 Agent，另外加入一個會循環問模型、接收工具請求、執行工具並把結果送回模型的命令列程式。v1.122.1 官方發行紀錄列出九種內建工具；實際名稱可在該版本的 Agent 原始碼核對。

三個角色別混在一起：模型產生下一步建議；Agent 客戶端在你啟動它的電腦上執行 read、write、edit、shell、glob、grep、web_fetch、view_image、ask_user；MCP 工具則透過 KoboldCpp 的 MCP 代理與伺服器執行。官方特別指出：內建 Agent 工具跑在 Agent 客戶端，MCP 工具跑在 KoboldCpp 伺服器。兩者若在不同機器，能碰到的檔案也不同。

這和Agent Harness 的白話原理相連：Harness 是把「思考、工具、回傳、再思考」串起來的執行層。MCP 是另一種把外部工具接進來的協定；它不是「安全模式」的同義詞。想看自行設計這個循環時要管哪些元件，可接著讀30 行偽程式碼的 Agent Harness 教學。

KoboldCpp Agent 教學：安裝與開啟的四步

① 從官方 GitHub 選對執行檔

截至 2026 年 9 月 28 日，GitHub 最新穩定發行版是 v1.122.1。到官方 Releases按系統下載：Windows 有 koboldcpp.exe 等版本，Linux 有 koboldcpp-linux-x64，Apple Silicon Mac 有 koboldcpp-mac-arm64。下載頁同時說明 CUDA、nocuda、oldpc 的適用情境。不要只看搜尋結果的站名；官方 README 特別提醒有冒名下載站。

② 載入模型，先估算上下文

已有 GGUF 模型的人，可以沿用原來的模型設定。官方發行紀錄建議 Agent 至少給 28k context（可一次放進模型的對話與工具紀錄）和 8k generation（單次輸出額度），並建議約 12GB VRAM 以取得較佳體驗。這是作者的有效運作建議，不是所有電腦都必須達到的安裝門檻；模型、量化、CPU/GPU 分配及任務長度會影響速度與成功率。第一次先做短任務，觀察是否截斷或反覆轉圈。

③ 開啟 Agent，讓批准維持逐次確認

在啟動器 GUI 的 Admin 分頁啟用 Agent，或在原本的啟動命令加上 --agent。進入 Agent 後輸入 /help 看目前版本的指令，輸入 /confirm on 要求每次工具呼叫都先詢問。原始碼的預設值也是 on；仍請在畫面確認狀態。這個批准畫面會顯示工具名稱與參數預覽，預覽可能截斷，因此遇到長命令或看不懂的參數就先拒絕，不要猜。

④ 用 /tools 確認真正開放的工具

輸入 /tools 查看內建與 MCP 工具。唯讀練習前，先用 /tools write off、/tools edit off、/tools shell off、/tools web_fetch off、/tools view_image off；若畫面列出 MCP 工具，也逐一關閉這次不需要的名稱。每次切換工具會清空對話，因此把設定做好，再開始任務。只留下 read、glob、grep 和必要的 ask_user，用 /tools 複查。這是在 Agent 提供的工具清單上收窄能力；檔案存取範圍仍由執行環境的權限決定。

第一次工具呼叫：只讀一份練習筆記

在沒有私人檔案的空白練習資料夾，自己建立 note.txt，內容寫「週五寄出海報；週六檢查回覆」。先在終端機記下檔案清單與 shasum -a 256 note.txt 的結果；Windows 可用檔案總管或系統內建雜湊工具做同樣檢查。然後以 /workdir <你的練習資料夾完整路徑> 切換工作目錄，並再次確認 /confirm on 與 /tools。

給 Agent 的任務可以直接貼：「只使用 read 讀取目前資料夾的 note.txt，列出兩件待辦並附原句；不要呼叫其他工具，不要修改檔案。若讀不到，直接說明。」接下來看它提出的工具呼叫：若是 read 且路徑就是練習檔，才按 y。若它要求別的路徑、shell 或其他工具，按 Enter 或 n 拒絕。完成後自己重算雜湊與檔案清單，再對照兩句原文。

這條路徑會是「你給任務 → 模型提議 read → 你核對路徑並批准 → 客戶端讀檔 → 模型依回傳內容回答」。如果模型直接編出答案、選錯工具、讀錯檔案或回答與原句不符，就算這次練習失敗；先看工具紀錄與檔案內容，不要把一段流暢文字當成完成證明。

要試寫入？先建立可丟棄的第二輪

熟悉唯讀流程後，再在同一個只放假資料的練習資料夾內建立 output.txt 的需求。開啟 /tools write on 會清空對話；用 /tools 再檢查，仍保持 /confirm on。請 Agent「把 note.txt 的兩件待辦整理成 output.txt」，先看提議的完整路徑與內容；你可先按 n，確認沒有新檔，再重新提出任務、只批准符合預期的寫入。最後從檔案系統開啟 output.txt 驗收。

關鍵限制：在 v1.122.1 的 Agent 原始碼裡，write 接受指定路徑，shell 可執行系統命令，/workdir 只是變更目前目錄；因此本文把工作目錄與自然語言「只改這裡」當成操作提示；檔案存取邊界仍須由作業系統權限決定。若你要讓 Agent 處理真實資料，先用作業系統帳號、容器或其他真正限制檔案與網路權限的環境，再決定能開哪些工具。

/confirm auto 會讓模型再做一次安全分類，某些呼叫可能自動批准；/confirm off 會自動批准全部工具呼叫。官方程式碼把 auto 的判斷交給模型，而不是獨立的權限系統。第一次練習維持 on，等你能理解每個工具的副作用，再評估是否改變。需要停下整個 Agent 時用 /exit；若正有工具在執行，先觀察它的結果與檔案狀態，別只憑「已停止」推定寫入已撤銷。

MCP、成本與常見失敗：三個容易看錯的地方

• 把 MCP 當成額外讀取權限：MCP server 可能接到另一台機器或別的資料來源。加載 mcp.json 後，先用 /tools 看新增了哪些工具，再逐一決定是否啟用。MCP 的工具呼叫與回覆機制可讀MCP Tools 規格；若工具逾時，不要把模型說「完成」當作外部系統已寫入，可用MCP 逾時收據驗收教學的回查方法。
• 把本機當成零成本：若使用純本機模型，仍會用到電力、記憶體與等待時間；若改接第三方模型端點，則另看該服務的用量計費。每輪還會重送部分對話和工具結果，長檔案可能擠掉上下文。記錄模型名稱、量化、硬體、context、generation、輪數與總耗時，比搬用別人的「每秒幾 token」更能幫你調整。
• 把讀到的文字當指令：網頁或檔案內容可能夾帶「請忽略先前規則」之類句子。它是任務資料，不是你給 Agent 的授權。先縮工具，再檢查每次提議的參數；若跨到真實帳號或資料庫，請另設權限與獨立驗收。

KoboldCpp Agent 教學 FAQ：新手最常問的八題

1. Agent 和普通聊天差在哪？

多了工具執行循環。普通聊天主要回文字；Agent 可把模型的工具請求送到執行程式，再把結果送回模型。能做多少，仍取決於開放的工具和實際權限。

2. 有九個工具，就要全部開著嗎？

不用。先用 /tools 看清單，為這次任務只留必要的工具；讀一份文字檔時，shell 和 write 都不是必要條件。

3. /confirm on 能保證安全嗎？

只能讓每次呼叫先經過你。批准畫面顯示的是參數預覽，長內容可能截斷；人按下同意後，工具仍以執行環境的權限工作。敏感資料另用作業系統隔離。

4. /workdir 是沙盒嗎？

它做的是切換目錄。該指令切換目前目錄並清空會話；從 v1.122.1 的程式碼可見，檔案工具接受絕對路徑，shell 執行系統命令。要限制可碰到哪些檔案，須在程式外另設權限邊界。

5. auto 比 on 聰明嗎？

用途不同。auto 是讓模型替每次呼叫判斷是否自動放行；on 是每次都交給人確認。第一次接觸檔案寫入時，選 on 比較容易追蹤。

6. MCP 和內建工具差在哪？

執行位置不同。官方 v1.122.1 發行說明指出，內建 Agent 工具在客戶端跑，MCP 工具在 KoboldCpp server 跑；同機安裝時感覺接近，跨機部署時要按真正執行的那台機器檢查檔案與網路權限。

7. 12GB VRAM 是硬性規定嗎？

這是作者的體驗建議。官方把它和 28k context、8k generation 一起列為有效使用的建議條件；實際需求還受模型與任務影響。先用短任務驗證你現有設備，再記錄延遲、截斷和錯誤。

8. 失敗時先看什麼？

先看工具紀錄與檔案狀態。確認工具是否真的呼叫、路徑是否正確、結果是否被截斷，再看 context 與模型設定。若剛拒絕寫入，先檢查目標檔；若使用 MCP，回到目標系統讀取實際狀態。

給新手的下一步：把批准當成工作流程的一部分

先用假資料跑通「提出、看參數、批准、讀回、核對」五步。當你能指出哪個工具在什麼電腦、以什麼權限碰了哪個檔案，才把任務擴到寫入、MCP 或更長的 Agent 專案。想比較現成 Agent 的角色與使用情境，可讀Hermes Agent 教學與Claude Code vs Codex 比較；若準備系統學習，可看AlphaLab 課程。