本地 Agent 踩坑實錄:Claude Code 接 Ollama 為何要換輕量 Harness

我想在一台只有 Intel 內顯的商務筆電上,打造一個「跟 Claude Code 一樣的開發方式,但腦跑在本地」的 AI agent——離線、隱私、不外送。這篇是完整的踩坑實錄,一條線走到底:① 用 Claude Code 接本地 Ollama,撞到「小模型跑不動重量級 harness」的牆;② 換對輕量 harness(Aider / Pi),本地模型真的開始寫檔;③ 摸清邊界,找到「崩潰」的真兇其實是 context 設定;④ 讓 4b/8b/14b 各寫一遍完整登入系統做實測,最後推到「那到底該買什麼硬體、Mac 值不值」的決策。

目標:在一台裝不了獨顯的筆電上跑本地 Agent

硬體是一台 Intel Core Ultra 7(Lunar Lake)的超薄筆電,內顯 Intel Arc 140V,32GB 記憶體(焊死、跟 GPU 共用),實際可用大約 11GB。它裝不了獨立顯卡(超薄機身 + 封裝記憶體),所以本地模型只能靠內顯或 CPU 硬跑。

一個關鍵觀念要先講清楚:你在 Claude Code 體驗到的「會自己 plan、自己呼叫工具、自己跑多步驟」那種 agentic 感覺,來源是 harness(Claude Code 這個外殼),不是模型本身。模型決定「想得聰不聰明」,harness 決定「做事的方式」。所以只要換掉腦(接本地 Ollama),harness 的「方式」還在——理論上。這篇的核心,就是驗證這句「理論上」到底成不成立。

階段一:接不上——Claude Code 接本地 Ollama

好消息是接本地腦現在非常簡單。Ollama 從 v0.14(2026-01)起原生支援 Anthropic Messages API,免 proxy。Claude Code 本質上只是個「會講 Anthropic API 的 client,它不檢查對面是不是真的 Claude」,所以只要三個環境變數把它指向本地 Ollama 就行:

set ANTHROPIC_BASE_URL=http://localhost:11434
set ANTHROPIC_AUTH_TOKEN=ollama
set ANTHROPIC_API_KEY=
set ANTHROPIC_MODEL=qwen2.5-coder:7b

三個 Windows 上的踩坑

「三行環境變數」聽起來簡單,但在一台受控的公司筆電上,我連續踩了三個坑:

症狀	根因	解法
claude 報 UnauthorizedAccess	PowerShell 執行原則擋 .ps1 腳本(公司資安政策)	改用 cmd 跑(走 claude.cmd)
環境變數設了卻沒生效,還是連雲端	user settings.json 的 env 區塊有把 provider 綁到公司雲端的設定,會壓過 shell 環境變數	移除那段 env,或用獨立 config 目錄
改完 settings 反而要求登入訂閱	手改 JSON 時把 cmd 的 "KEY"="value" 寫進去,整個 env 失效	JSON 是 "key": "value"(冒號不是等號)

怎麼確認它真的打本地、沒偷偷走雲端?

最乾脆的驗證:在模型回答的當下看工作管理員。如果CPU 持續高檔、而 Wi-Fi 傳送/接收都是 0,那就是純本地推論——雲端一定會有網路流量,而且不會吃你的 CPU。想要 100% 鐵證就直接關 Wi-Fi 再問一題,還能答就無疑是本地。

第一道牆:Intel 內顯吃不到 GPU 加速

官方 Ollama v0.17 起加了原生 Intel SYCL,但在這顆 Lunar Lake Arc 140V 上沒有真的生效:問答時 GPU 使用率只有 2~3%、CPU 卻是 70%+、NPU 完全 0%。模型 fallback 到 CPU 硬跑,一次要好幾分鐘。(過去 Intel 官方的 IPEX-LLM 加速最成熟,但那個專案已在 2026-01 被 archive、凍結在舊版 Ollama,而且卡在沒有 Anthropic 相容的版本。)

順帶一個有趣的觀察:推論時CPU 先飆、RAM 過一段時間才慢慢爬上去。這是 llama.cpp 用 mmap(記憶體映射)載模型的正常行為——它不是一次把權重灌進 RAM,而是「用到哪一層才把那一頁讀進來」(demand paging),加上 KV cache 隨生成的 token 增長,所以 CPU 一發請求就開始算,RAM 是逐步被填上去的。

第二道牆:tool-calling 失敗——Agent 的三層框架

速度慢還能忍,真正的關卡是tool-calling:agent 要能「自己呼叫工具去寫檔案」,不是把 code 印在對話裡給你看。這裡我歸納出一個框架:一次成功的工具呼叫,要通過三層串聯關卡,任何一層垮掉,整個 agentic 動作就失敗。

層	在做什麼	主要吃什麼能力	垮掉長怎樣
理解層	讀懂使用者的意圖 + system prompt	模型規模(參數量)	聽錯任務、無視規則、被長 prompt 淹沒
決策層	判斷要不要用工具、用哪個、先後順序	專門的 agentic 訓練	該用工具卻只用講的、多步驟迷路
格式層	把意圖序列化成 harness 能解析的精確格式	tool-use 微調 + 對齊 harness	格式吐錯、JSON 不合法、參數填佔位符

有意思的是,我測的三顆模型各自掛在不同層,完美示範了這個框架:

模型	掛在哪一層	症狀
qwen2.5-coder:7b	格式層	吐 OpenAI 風格的 {"name":"Write",...} JSON 當純文字,Claude Code 認不得
llama3.1:8b	決策層	只把 code 印在對話裡、不建檔;逼它用工具就丟 API error
qwen3:8b	理解層	花 7 分鐘 thinking,把 Claude Code 的 system prompt 當成「使用者的複雜設定」,反問我要做什麼

其中 qwen3:8b 那個最有啟發性。它的 thinking 內容顯示:它把 Claude Code 灌進去的工具定義、orchestration 規則、session 資訊當成「使用者提供的一大包複雜設定」,然後完全沒認出我真正的指令「建立 kmeans.py」,最後結論是「你還沒給我具體的任務,請告訴我要處理什麼」。

根因:Claude Code 對 8B 小模型「太重」

這就是關鍵發現。qwen3 的 tool-calling 其實是好的——它掛在理解層,被 Claude Code 那一大牆 system prompt 淹沒了。而 Claude Code 的 system prompt 是核心的一部分,你改不掉(不是 CLAUDE.md 那種使用者規則)。

深入:攤開三個 harness 的 system prompt,就懂為什麼

「太重」到底多重?把三個 harness 實際送給模型的 system prompt 撈出來量一量(Pi 從本機源碼實 dump、Aider 官方源碼、Claude Code 從 2026-03 源碼洩漏),答案一目了然:

Harness	system prompt 大小	內容重點
Pi	幾百 tokens	「你是 coding assistant」+ 4 個工具 + 簡短 guidelines,沒了
Aider	~1,500–1,800 tokens	edit format 規則(SEARCH/REPLACE 字元級匹配)主導
Claude Code	~20,000–30,000 tokens	42 個工具各帶獨立文件 + 指令 + 安全 + orchestration

Pi 到 Claude Code,system prompt 差了 50–100 倍。CC 的源碼洩漏揭示了那 24k 的來源:42 個工具,每一個都帶獨立的使用文件(光一個 BashTool 就 370 行)+ 嵌入安全協議,再用 7 層動態組裝 + cache boundary 拼起來。這是為雲端 prompt caching + 大 context 精心設計的——但本地 Ollama 吃不到快取紅利,只吃到重 prompt 的壞處。

階段二:換對工具——Aider 讓本地模型真的寫檔了

問題定位清楚後,解法就明確了:換一個 system prompt 輕量、專為本地小模型設計的 agent。我先試 Aider。同一顆 qwen3:8b,啟動指令如下:

setx OLLAMA_API_BASE http://127.0.0.1:11434
aider --model ollama_chat/qwen3:8b --edit-format whole

Aider 贏過 Claude Code 的三個結構理由,正好一一對應三層框架的死因:

Claude Code 死在	Aider 怎麼解
理解層被重 system prompt 淹沒	system prompt 輕量,不淹沒 8B
context 被塞爆(Ollama 預設 context 太小)	Aider 預設自動幫 Ollama 開足夠 context
格式層 diff / tool_use 吐錯	--edit-format whole 讓它輸出整檔,繞過 diff 格式

結果:qwen3 吐出「檔名 + code block」的格式,Aider 認得,於是 Applied edit to kmeans.py——檔案真的寫進磁碟了,還自動 git commit。同一顆模型,只是換了 harness,就從「反問你要幹嘛」變成「真的動手寫檔」。差別不在腦,在外殼。

再換一階:Pi + qwen3 才是最佳解

Aider 的寫檔坑帶出下一步:改用 Pi(Mario Zechner 與 Armin Ronacher 維護的 minimal agent)。差別在寫檔機制——Pi 用的是「真正的 tool use」:模型呼叫 write 工具、Pi 直接執行寫檔,不靠文字格式解析。qwen3 的 tool-calling 對得上就直接、可靠地寫進去,不用跟 edit 格式纏鬥。

Harness	寫檔機制	對本地小模型
Aider	模型吐文字 edit 格式,Aider 解析(無 tool use)	🟡 預設 diff 易錯 → 顯示不寫檔,要 --edit-format whole
Pi	模型呼叫 write 工具,Pi 執行(真 tool use)	🟢 tool-calling 對上就直接寫,免調格式

實測結果 Pi 是三個裡最好的:同一顆 qwen3:8b,在 Claude Code 掛在理解層(反問我要做什麼),在 Pi 就直接認出任務、真的把 kmeans.py 寫進磁碟——而且產出一個完整的 KMeans class(fit / predict / 收斂檢查)+ make_blobs 造資料,還自己主動加上 matplotlib 視覺化。它不只會寫檔,理解得比在 Claude Code 裡完整太多。原因正好對應三層框架:①system prompt 輕量不淹沒理解層;②128k context 充裕(TUI 底部顯示這次只用 2.2%);③核心工具 read/write/edit/bash + TUI + skills,體驗最接近 Claude Code。

三個 Agent Harness 怎麼選?

Harness	輕量(不淹沒 8B)	能寫檔	體驗
Claude Code	✕ 太重,理解層被淹	—	功能最完整,但要強腦撐
Aider	✓ 輕	△ 要 –edit-format whole	偏 diff / pair-programming
Pi	✓ minimal 設計	✓ 真 tool use	最接近 Claude Code(✅ 實測最佳)

心法:Agent = 模型 × Harness

這一階段最大的收穫,不是「哪個模型最好」,而是一個框架:本地 AI agent 的成敗,是「模型」和「harness」的搭配問題。強腦配重 harness(Claude Code + Opus)、弱腦配輕 harness(qwen3:8b + Pi),搭錯了,再好的模型也只會在對話框裡反問你。當本地 agent tool-calling 失敗時,別急著怪模型——先用三層框架看它掛在哪:理解錯任務就換更大的模型,只吐 code 不建檔就換做過 agentic 訓練的,格式爛就換 tool-use 微調好的、或換一個對格式更寬容的 harness。

階段三:摸清邊界——把它當 A2A 協作

找到能寫檔的本地 agent 後,真正實用的玩法不是「讓小模型獨力完成專案」,而是把它當成一個 A2A(Agent-to-Agent)協作裡的 executor:讓雲端強腦(如 Claude Opus)當 orchestrator 負責設計、拆解、驗證,把拆好的單步任務委派給本地小模型執行。這帶出一個 A2A 協作裡最關鍵、卻最少被量化的指標:「一次範圍(single-shot capacity)」——一個 executor 一次請求能成功吞完的最大任務量。它決定 orchestrator 該把任務拆多細,而且不只取決於模型大小,還取決於執行環境(同一顆 8b,在被搶滿 CPU 的機器上,一次範圍會縮到只剩幾行)。

從實作中歸納出五條「拆分眉角」,每一條其實都是 A2A 協作的通用原則:

拆分眉角	A2A 協作原則
① 粒度配 executor 的「一次範圍」	任務量不能超過對方 agent 一次能吞的上限
② 每個委派要自包含	agent 間無共享記憶,每則訊息要 self-contained
③ 明確契約 + 框死邊界	「只做這件、別越界」,防止 executor 腦補
④ 收到回傳一定驗收	orchestrator 永遠 verify,不盲信 executor
⑤ 失敗要能降級重試	拆更小重投、或換更小模型 fallback

弱腦 executor 的兩種失敗模式(第二種更危險)

失敗模式	危險	說明
誠實超時	⚠️ 中	任務吃不下就超時——至少你知道它失敗了
降級腦補 + 安全降級	🔴 高	面對超出能力的完整設計稿,不說做不到,默默降級成陽春版(密碼明文存、明文 SQL 比對),把設計稿要的 bcrypt / JWT / rate limit 全丟,還講得像完成了

隱藏元兇:本地 agentic 崩潰,先查 Ollama 的 context 設定

這是整個實驗最大的翻盤。本地小模型跑 agentic 時的「崩潰/卡死」,很多時候不是模型爛、也不是硬體不行,而是 Ollama 的預設 context window 只有 4096 太小。Pi / Claude Code 這類 agentic harness,每個請求要塞 system prompt + 工具定義 + 對話歷史 + tool call 來回,很容易撐爆 4096 → model runner 行為異常(半睡卡死、甚至進程崩潰)。一度以為是「這台不穩定、做不到」,差點下錯結論。

兩個診斷訊號:① ollama ps 的 CONTEXT 欄顯示 4096;② llama-server 進程呈 Sl(睡眠)狀態、CPU 佔用低、卻遲遲不產出。看到這兩個,先別怪模型——去把 context 開大。

同一顆 8b,同一個 20 行任務	context 4096(預設)	context 32768
結果	🔴 崩潰卡死	🟢 成功,品質好(用 hash)
llama-server 狀態	Sl 半睡,32% CPU	R 全速,446% CPU

解法一行搞定:OLLAMA_CONTEXT_LENGTH=32768(從預設 4096 開到 8 倍)。設完 model runner 立刻從「半睡卡死」變回「全速運算」。

Ollama 完整參數解析(跑本地 agentic 該懂的)

環境變數	預設	功用
OLLAMA_CONTEXT_LENGTH	4096	預設 context window ← 跑 agentic 一定要調大(32768+),否則撐爆崩潰
OLLAMA_KEEP_ALIVE	5m	model 保持載入多久;負值=永久,0=用完即卸。設長一點避免每次冷啟動
OLLAMA_NUM_PARALLEL	1	單一 model 同時處理的並行請求數
OLLAMA_MAX_LOADED_MODELS	3	同時能載入幾個 model(受記憶體限制)
OLLAMA_FLASH_ATTENTION	off	開 flash attention,注意力記憶體從 O(n²) 降到 O(n),大 context 更省記憶體、更快
OLLAMA_KV_CACHE_TYPE	f16	KV cache 量化:q8_0≈記憶體減半(品質幾乎無損)、q4_0≈減到 1/4(小幅品質代價)。需搭 flash attention
OLLAMA_MAX_QUEUE	512	請求佇列上限,超過回 503
num_ctx (API 參數)	—	單次 API 請求覆蓋 context(不改全域時用)

開大 context 的代價是 KV cache 吃記憶體(實測 8b 從 5.9GB → 10GB)。三個參數搭配,能兼顧「大 context」和「省記憶體」:

OLLAMA_CONTEXT_LENGTH=32768   # 開大 context,治 agentic 崩潰
OLLAMA_FLASH_ATTENTION=1      # flash attention,記憶體 O(n^2) 降到 O(n)
OLLAMA_KV_CACHE_TYPE=q8_0     # KV cache 量化,記憶體約減半

階段四:完整實測——4b / 8b / 14b 各寫一遍登入系統

把整套方法用到底——讓 qwen3 三個尺寸(4b / 8b / 14b)各自逐單元寫完一個完整登入系統(7 個檔:Flask + SQLite + JWT,大 context、契約寫死),量速度、驗品質,對照 Opus 全做。這也是拿來決定「本地基底該用多大的模型、該買哪台硬體」的實測依據。

速度:最反直覺的一格

模型	寫完整系統總時間
qwen3:8b	51 分 ⚡ 最快
qwen3:14b	112 分
qwen3:4b	348 分(5.8 小時)
Opus(雲端對照)	66 秒

8b 比 4b 快 6.8 倍。最小的 4b 反而最慢——它在複雜檔(前端 html 花了 149 分)迷路、囉嗦、重試。「越小越快」是錯的:太小的模型在難任務上會又慢又錯。

品質:差異全在整合層

檔	4b	8b	14b
後端 5 檔(hash/JWT 安全)	✅ 全對	✅ 全對	✅ 全對
login / index 路由	route 反斜線 bug	字面 \n + route 換行 bug	✅ 對
前端 index.html	欄位/語法錯	✅ 好	✅ 好
整體可跑?	❌ 前端垮	⚠️ 2 bug 要手修	✅ 7/7 全對可跑

三個模型的後端安全(密碼 hash、參數化 SQL、JWT)全對——再次證明「拆小 + 契約寫死」的威力,連 4b 都能寫出安全的 code。差異全部落在整合層(前端、路由細節):4b 前端整合垮、8b 踩格式 bug、只有 14b 一次到位 7/7 全對可直接拼裝跑。

配 GPU 能快多少?各卡實測 + 推估

速度是唯一治不了的硬傷,結論是「要 GPU」。那配 GPU 能到多快?先看撈到的真實 benchmark(實測),再用公式把空白格補上。核心原理:LLM 生成是「記憶體頻寬 bound」——每吐一個 token 就要把模型權重從記憶體讀一遍,所以 tok/s ≈ 記憶體頻寬 ÷ 模型權重大小 × 效率因子(~0.6)。

GPU	記憶體頻寬	8B Q4 實測	14B Q4
RTX 3060 12GB	360 GB/s	42 tok/s	23–29 tok/s
RTX 4090 24GB	1008 GB/s	~104 tok/s	☆~60
RTX 5090 32GB	1792 GB/s	145–185 tok/s	☆~100
Mac M4 base	~120 GB/s	20–25 tok/s	~10 tok/s
Mac M4 Pro	273 GB/s	25–30 tok/s	18–22 tok/s

公式驗證吻合:RTX 3060 8B = 360÷5×0.6 ≈ 43,實測 42 ✅;3060 14B = 360÷9×0.6 ≈ 24,實測 23–29 ✅。拿它填完整推估表(☆ = 推估,其餘實測):

模型(Q4)	本機 CPU	M4 base	M4 Pro	3060	4090	5090
4b	☆2–5	☆~40	☆~55	☆~75	☆~185	☆~280
8b	☆2–4	20–25	25–30	42	104	145–185
14b	☆<2	~10	18–22	23–29	☆~60	☆~100
32b	✗	✗塞不下	12–18	✗	☆~35	52+

實感:本機 CPU 寫 login 14 行花了 25 分鐘(約 2–4 tok/s),同一段在 RTX 4090(104 tok/s)大約 2 秒——快約 700 倍。連最便宜的二手 RTX 3060 都快 15–20 倍。你實驗裡「8b 龜速」的痛,在任何一張 GPU 上都直接消失。

DIY 顯卡機 vs Mac mini:同預算誰划算?

既然要上 GPU,自然的問題是:同一筆錢,自組一台顯卡機 vs 買一台 Mac mini,誰划算?先看台灣 2026 現在的行情。關鍵門檻:跑 32B 要 20–24GB VRAM,等於「一張 24GB 的卡」——而 RTX 3090 是這波公認的 CP 值之王。

零件	台灣價
RTX 3090 24GB(二手)	$22,000–30,000 ⭐
RTX 4090 24GB(二手)	$64,000+
RTX 5090 32GB(全新)	$121,600+
整機(CPU/板/32G/SSD/PSU/殼,不含卡)	~$24,000–28,000

對應兩個預算點(剛好對標 Mac mini M4 base 的 $33,900 與 M4 Pro 48GB 的 $75,900):

預算 / 路線	配置	能跑 32B?
$34k · 好整機 + 3060 12GB	$24k + $9k	❌ VRAM 不足(8b/14b 飛快)
$51k · 整機 + 單 3090 24GB	$26k + $25k	✅ ~28–35 tok/s(比 M4 Pro 快 2 倍,省 $25k)
$76k · 整機 + 雙 3090 48GB	$28k + $48k	✅ 甚至能跑 70B(~15 tok/s)

但有兩個帳,規格表上看不到:電費與統一記憶體

① 電費(長期持有成本)。DIY 單 3090 整機跑 LLM 約 400W、閒置 90W;Mac M4 Pro 跑 LLM 只 ~75W、閒置 ~15W——差 16 倍。若你家用電已破千度、落在最高級距(邊際電價 ~8 元/度),DIY 多耗的每一度都是最貴的 8 元:

使用強度	年電費差(×8元)	吃掉省的 $25k
24/7 常開待命	~$6,700	3.7 年
每天重度 8h	~$7,600	3.3 年
每天輕度 1–2h(用完關)	~$1,000–1,900	13–24 年

換句話說:重度/常開的話,DIY 省的 2 萬多,3–4 年就被電費吃回去,之後每年倒虧近 $7,000(還沒算夏天發熱要多吹的冷氣、二手卡壽命、風扇噪音);但如果是輕度用完就關,電費差很小,DIY 還是划算。

② 統一記憶體 ≠ 雙卡拼容量。單張 3090 只有 24GB,跑 32B 塞得下但 context 只剩 ~4GB(很緊);Mac M4 Pro 的 48GB 是一整塊連續的統一記憶體,跑 32B 還剩 ~20GB 給長 context——這正好解掉你實驗裡踩到的 context 生死線。想用 NVIDIA 追上 48GB,得上雙 3090,但那是「兩塊 24GB 拼接 + 分層跨卡」,不是一塊到底,而且要連主機板(雙 PCIe)、電源(1000W+)、機殼散熱一起升級,還吃到 800W 耗電。

	單 3090($51k)	雙 3090($76k)	Mac M4 Pro($75.9k)
最大模型	32B(context 緊)	70B	32B 舒服 / 70B 勉強
32B 速度	~28–35(快)	~28–35	12–18
耗電	~450W	~800W	~50–75W
體積 / 噪音 / 維護	大 / 中 / 要自組	大 / 吵 / 雙卡調校	掌心 / 靜音 / 開箱即用

總結:本地 agentic 的完整決策鏈

從「一台裝不了獨顯的筆電」一路走到「該買哪台硬體」,這條線可以壓成一串因果:

1. 接不上 → 不是模型爛,是 Claude Code 的 24k system prompt 淹沒了 8B 的理解層。
2. 換對工具 → 輕量 harness(Pi 真 tool use / Aider 加 --edit-format whole),同一顆 8b 就開始寫檔。Agent = 模型 × harness。
3. 摸清邊界 → 崩潰的真兇是 Ollama context 預設 4096,開到 32768 就治好;弱腦委派要「拆小 + 契約寫死」防安全降級。
4. 完整實測 → 4/8/14 各寫登入系統:崩潰可解、品質可解、只有速度是純硬體極限;而且「越小越快」是錯的。
5. 硬體決策 → 速度要 GPU;DIY 單 3090 論 CP 值最強,但在高電價 + 長時間跑下,Mac 的省電與統一記憶體會翻盤成物超所值。