Claude Code 接本地模型還能上網嗎？2026 完整接線圖（Ollama / claude-code-router / Web Search）

# Claude Code 接本地模型還能上網嗎？2026 完整接線圖（Ollama / claude-code-router / Web Search）

TL;DR

Claude Code 可以把模型 backend 從 Anthropic 雲端換成本地 Ollama / LM Studio / vLLM——三條 env var 搞定。但內建 WebSearch 工具是 Anthropic 伺服器端服務，改接本地模型後內建搜尋直接失效。要救回來：另外接 Ollama Web Search API（免費 tier 夠用）或 SearXNG MCP。本文把兩條官方路徑、四種 backend、一鍵安裝、驗證指令、6 個踩坑、模型選型一次寫完，文章 URL 餵給 Claude Code 它能照著裝。

「Claude Code 是不是可以接本地模型，幫我上網研究並且寫文章？」這個問題最近從幾個朋友那邊聽到——隱私、離線、API 費用，每個都是合理動機。但實際接線比 Anthropic 官方文件講的多一層轉折，特別是「上網」這部分。我把 2026 年現況走過一遍，這篇是接線圖跟踩坑紀錄。

📌 目錄

為什麼想接本地模型

不是每個人都想接。Anthropic 官方雲端 API（Claude Sonnet / Opus）目前就是業界第一名的 coding 模型，在不在意這四件事：

接線圖：四種路徑全景

┌─────────────┐
│ Claude Code │  → 它只會講「Anthropic Messages API」
│   (CLI)     │
└──────┬──────┘
       │ HTTP POST /v1/messages
       │ ANTHROPIC_BASE_URL=???
       ▼
   ┌───┴────────────────────────────────────────────┐
   │                                                 │
   ▼                                                 ▼
┌──────────────┐                          ┌──────────────────────┐
│  Anthropic   │   官方雲端（預設）       │  本地 / 自架 backend │
│   API 雲     │                          │                       │
└──────────────┘                          └──────────┬───────────┘
                                                      │
                  ┌───────────────────────────────────┼────────────────────┐
                  ▼                                   ▼                    ▼
           ┌─────────────┐               ┌────────────────────┐    ┌──────────────┐
           │   Ollama    │               │ claude-code-router │    │   ccproxy    │
           │  v0.14+     │               │  (proxy 翻譯層)    │    │  (proxy)     │
           │  原生支援   │               │                    │    │              │
           │  Anthropic  │               │  Anthropic API ↔   │    │  類似上面    │
           │  Messages   │               │   OpenAI Chat API  │    │              │
           └──────┬──────┘               └─────────┬──────────┘    └──────┬───────┘
                  │                                │                      │
                  ▼                                ▼                      ▼
           ┌──────────────┐              ┌─────────────────┐
           │ qwen3-coder  │              │   LM Studio     │
           │ glm-5        │              │   vLLM          │
           │ kimi-k2      │              │   llama.cpp     │
           │ minimax-m2.7 │              │   OpenRouter    │
           └──────────────┘              └─────────────────┘

重點： Claude Code 本身只會講 Anthropic Messages API。要嘛你的 backend 原生支援這個 API（Ollama），要嘛中間放一個 proxy 翻譯（claude-code-router / ccproxy）。

🛠 路徑 A：Ollama 直連（最簡）

適合： 第一次嘗試、不想多裝 proxy、機器有 32GB+ RAM。

從 Ollama v0.14 開始，Ollama 原生支援 Anthropic Messages API endpoint。意思是 Claude Code 把 Ollama 當成 Anthropic 雲端來打就行。

三條 env var 切換

export ANTHROPIC_AUTH_TOKEN=ollama
export ANTHROPIC_API_KEY=""
export ANTHROPIC_BASE_URL=http://localhost:11434

跑：

claude --model qwen3-coder

完成。Claude Code 啟動後它會把 /v1/messages 打到 localhost:11434（Ollama 預設 port），Ollama 收到後跑你指定的 local model 回應。

Ollama 自己提供更快的方法

ollama launch claude --model kimi-k2.5:cloud

ollama launch claude 自動把 env vars 設好、把 Ollama daemon 確認跑著、開 Claude Code。一條指令搞定。

但是要注意 kimi-k2.5:cloud 後綴的 :cloud 是 Ollama 的「雲端執行」（Ollama 自家雲，不是你本機）—— 不是你想要的「本地」。本地模型要選不帶 :cloud 後綴的，例如 qwen3-coder、glm-4.7-flash。

🌐 路徑 B：claude-code-router 代理（最彈性）

適合： 想接 LM Studio / vLLM / llama.cpp / OpenRouter，或想做模型路由（不同任務派給不同模型）。

musistudio/claude-code-router 是社群開源的代理層。它做兩件事：

安裝

npm install -g @musistudio/claude-code-router
ccr install

ccr install 互動式問你要接哪些 backend、設定 API key。設定檔會生在 ~/.claude-code-router/config.json。

啟動

ccr start    # 啟動 proxy（背景跑在 localhost:3456）
ccr code     # 用 proxy 開 Claude Code

ccr code 內部就是把 ANTHROPIC_BASE_URL 指到 localhost:3456 然後 spawn Claude Code。

為什麼要用這條（vs Ollama 直連）

🔍 上網研究的關鍵：Ollama Web Search API

這是接本地模型最容易踩的雷。

Claude Code 預設的 WebSearch tool 是伺服器端能力——Anthropic 雲端模型才能呼叫。當你把 backend 換成本地 Ollama，那顆模型沒辦法觸發那個 tool 因為它根本不存在於本地 backend 裡。

但「上網研究 + 寫文章」這個工作流真的需要搜尋能力。三個解法：

解法 1：Ollama Web Search API（推薦）

Ollama 2026 年推出官方 Web Search API，免費 tier 可用，需要 Ollama 帳號。

# 申請 API key（一次性）
# 1. https://ollama.com 註冊
# 2. Settings → API Keys → 新增
export OLLAMA_API_KEY="你的-key"
# 試打一次驗證
curl https://ollama.com/api/web_search \
  -H "Authorization: Bearer $OLLAMA_API_KEY" \
  -d '{ "query": "Spring Boot 4 release notes" }'

接到 Claude Code 的方式有兩種：

方式 A：當成 MCP server——把 ollama-web-search 包成 MCP server 加到 ~/.claude.json 的 mcpServers。社群有現成 wrapper（apidog 文章 有指引）。

方式 B：自己寫 skill——在 ~/.claude/skills/ 下寫一個 web-search.md，裡面教 Claude 用 Bash 呼叫上面那條 curl 並解析 JSON 結果。比較土砲但完全自控。

解法 2：SearXNG（自架 metasearch）

SearXNG 是 self-hosted metasearch engine，把 Google / Bing / DuckDuckGo 結果聚合。完全免費、無 API key、隱私性最高（搜尋內容不出你的網路）。

docker run -d -p 8080:8080 searxng/searxng

接到 Claude Code 一樣是 MCP server 形式。社群已經有 searxng-mcp 包好。

解法 3：Brave Search MCP

Anthropic 官方 cookbook 有列 brave-search MCP server，要 Brave Search API key（免費 tier 每月 2000 query）。最 Anthropic 官方支援的方式。

對照表

📊 本地模型怎麼選：四顆主流比較

2026 年 Q1-Q2 的社群實測，coding agent 任務（Claude Code 用途）四顆主流：

• 第一次玩 → qwen3-coder：tool calling 穩，Claude Code 不會卡關。M3 Pro 16GB 也勉強跑（用 q4 量化）
• 寫長文（這篇文章那種）→ kimi-k2：128K context 寫長文不會被截斷
• 要逼近 Sonnet 品質 → minimax-m2.7：但要 M3 Max 64GB 起跳，且每秒 token 數可能掉到 5-10

64K context 是地板

Claude Code 官方文件明說：要 64K context window 才能正常運作。

原因：Claude Code 的 system prompt 加上 conversation history 加上 tool definitions，輕鬆吃掉 16K+。再加上多輪對話跟 file edits，常規一個 session 跑到 30-50K。如果模型 context 只有 8K / 16K，每兩三輪對話就會被截斷，agent 行為會詭異。

低於 32K context 的模型不要用——chat demo 而已，不是 Claude Code。

⚠️ 6 個真實踩坑

踩坑 1：Claude Code attribution header 讓 KV cache 失效

Claude Code 每次 request 會塞一個 attribution hash 到 system prompt。這個 hash 每次都不同 → prefix cache miss → 本地模型推理速度掉 90%。

修法（Claude Code settings）：

// ~/.claude.json 加上
{
  "disableAttribution": true
}

vLLM > 0.17.1 已內建處理。Ollama 要靠這個 setting fix。

踩坑 2：Ollama 第一次載 model 會 timeout

Ollama 是 lazy load，第一次 request 來才把 model 從 disk 載進 RAM。30B 模型載入要 15-30 秒，Claude Code 等不了會 timeout。

對策：用 Claude Code 之前先 pre-warm：

# 隨便跑一次讓 model 進記憶體
ollama run qwen3-coder "hi" --verbose

之後 Claude Code 接上去就快。

踩坑 3：tool calling 失敗率比雲端高

本地 30B 模型 tool calling 不像 Sonnet 4.6 那麼穩。常見症狀：

• 該呼叫 Read 卻自己腦補檔案內容
• 多步驟 task 中途忘記用 tool
• JSON format 偶爾爛掉

• 選 tool calling 強的模型（qwen3-coder > kimi-k2 > glm-5）
• system prompt 加強提示「請務必使用提供的 tools」
• 失敗率高就升級到 70B 級別

踩坑 4：WebSearch 內建工具直接消失

如前述，本地 backend 接不到 Anthropic 伺服器端 WebSearch。如果你 prompt 說「搜尋 XX」，模型會：

• 道歉「我不能聯網」（最常見）
• 編造答案（最危險）
• 嘗試呼叫不存在的 tool 然後 error

踩坑 5：context 64K 不等於「64K 都能用」

Ollama 預設 num_ctx=2048（沒看錯，2K），就算你的模型支援 128K，沒設定也只用 2K。

修法：

# 啟動時指定
OLLAMA_NUM_CTX=65536 ollama serve
# 或在 modelfile 裡：
echo "FROM qwen3-coder
PARAMETER num_ctx 65536" > Modelfile
ollama create qwen3-coder-64k -f Modelfile

踩坑 6：M 系列 Mac unified memory 撐不住

M3 Max 64GB「看起來」能跑 70B q4 模型。實際上 macOS 系統 + 開的 app 已經吃 20GB+，剩下 40GB 跑 70B q4（檔案 ~40GB），swap 開始撞硬碟，每秒 token 從 30 掉到 3。

對策：

• 32GB Mac 跑 30B q4，剛好
• 64GB Mac 跑 70B q4 要關掉 Chrome / Slack / Docker
• 真的要 70B+ 流暢 → M3 Ultra 128GB 起跳

✅ Prerequisites + 一鍵安裝 + 驗證指令

Prerequisites

一鍵安裝（路徑 A：Ollama 直連 + Web Search）

# 1. 啟動 Ollama daemon
ollama serve &
# 2. 拉模型（30B q4 約 18GB，網速看你）
ollama pull qwen3-coder
# 3. pre-warm 避免第一次 timeout
ollama run qwen3-coder "ready" >/dev/null
# 4. 設定 Claude Code 環境變數（加進 ~/.zshrc）
cat >> ~/.zshrc <<'EOF'
export ANTHROPIC_AUTH_TOKEN=ollama
export ANTHROPIC_API_KEY=""
export ANTHROPIC_BASE_URL=http://localhost:11434
export OLLAMA_API_KEY="從 ollama.com 申請的 key"
EOF
source ~/.zshrc
# 5. 修 attribution header bug
mkdir -p ~/.claude
python3 -c "import json,os; p=os.path.expanduser('~/.claude.json'); \
  d=json.load(open(p)) if os.path.exists(p) else {}; \
  d['disableAttribution']=True; json.dump(d, open(p,'w'), indent=2)"
# 6. 啟動 Claude Code（指定本地模型）
claude --model qwen3-coder

驗證指令

# 驗證 1：Ollama 通了
curl -s http://localhost:11434/api/tags | jq '.models[].name'
# 預期：列出已下載的模型，含 qwen3-coder
# 驗證 2：Anthropic 相容 endpoint 通了
curl -s http://localhost:11434/v1/messages \
  -H "Content-Type: application/json" \
  -d '{"model":"qwen3-coder","max_tokens":50,"messages":[{"role":"user","content":"say hi in 5 words"}]}' \
  | jq '.content[0].text'
# 預期：回傳一句 5 字以內招呼
# 驗證 3：Web Search API 通了
curl -s https://ollama.com/api/web_search \
  -H "Authorization: Bearer $OLLAMA_API_KEY" \
  -d '{"query":"hello"}' | jq '.results[0].title'
# 預期：回傳一個搜尋結果標題
# 驗證 4：Claude Code 真的接到本地模型
claude --model qwen3-coder -p "say 'local model alive' in english"
# 預期：回 "local model alive"，且過程中沒有打網路（可用 nettop 監看）

四個 check 全綠才算裝完。任何一個 fail 回去看對應的踩坑段。

❓ FAQ

Q1：本地模型寫 code 真的能取代 Sonnet 4.6 嗎？
2026 年中誠實答案：不能取代，但能當輔助。 30B qwen3-coder 寫簡單功能、改 typo、寫 unit test 沒問題。但跨檔案重構、debug 複雜 race condition、設計新架構 → 還是 Sonnet 強。建議混用：日常吃 local，硬骨頭切 Sonnet。

Q2：Ollama 的 :cloud 後綴模型算不算本地？
不算。 :cloud 是 Ollama 自家雲端執行（你的資料還是傳到 Ollama 伺服器），優點是可以跑你機器跑不動的模型（300B+）。如果你要的是「資料不出機」，不要用 :cloud 後綴。

Q3：claude-code-router 跟 Ollama 直連，普通用戶選哪個？
先 Ollama 直連。 理由：少裝一個 proxy、少一層延遲、少一層 debug 表面。你只有「需要接 LM Studio / vLLM」或「想做多模型路由」才升級到 router。

Q4：本地模型沒網路怎麼讓 Claude Code 上網？
你說的「沒網路」如果是「不想被監控」→ 用 SearXNG 自架。如果是「物理上沒網路」→ 那 Web Search 就是不可能，這是物理限制不是工具限制。可以靠預先 cache 一些常用 docs 在本機（用 Context7 MCP 之類）替代部分搜尋需求。

Q5：M2 Mac 16GB 能玩嗎？
勉強能。 跑 7B 模型（如 qwen2.5-coder:7b）流暢，但 Claude Code 對模型品質要求高，7B 級別 tool calling 不夠穩，常常卡關。個人不建議——體驗差到會讓你誤以為本地模型不行。要玩請至少 32GB。

Q6：本地模型響應速度比較快？
看情境。 第一個 token 通常比雲端快（沒網路 RTT）。但每秒 token 數雲端通常勝（A100 / H100 vs M3 Max）。長 context 場景雲端優勢更大。短對話、簡單任務 → 本地有感快；長 reasoning → 雲端勝。

Q7：上網研究功能掛掉的話，部落格怎麼寫？
這個問題實作上的解法：寫文章先用雲端 Claude 把 Step 0 查證做完，把官方 URL / 截圖 / 引用都抄到本機 markdown，之後切本地模型寫長文。查證階段需要搜尋能力，寫長文階段不太需要 → 這樣分階段最省事。

🔗 延伸資源

• 🔗 Ollama 官方 Claude Code 整合 — 三條 env var、ollama launch claude 指令、cloud 模型清單
• 🔗 Ollama Web Search API 文件 — REST API 用法、rate limit、Python/JS SDK
• 🔗 claude-code-router GitHub — proxy 設定、多模型路由、所有支援 backend 清單
• 🔗 LM Studio 官方接 Claude Code 指南 — 如果你已經在用 LM Studio
• 🔗 vLLM 接 Claude Code 文件 — 高吞吐生產級部署
• 🔗 Unsloth 量化模型 + Claude Code 教學 — q4 / q5 / q8 怎麼選

• Claude Code - Ollama 官方整合文件
• Ollama Web Search API 文件
• claude-code-router GitHub repo
• LM Studio 官方接 Claude Code 指南