【2026 最新】Unsloth Desktop 教學：選模型、量化、跑本機 AI，再串 Claude Code／Codex

這篇 Unsloth Desktop 教學要解決的，不只是「把模型下載下來」，而是把整條路走通：先確認 Windows、Linux 或 macOS 能否安裝，依 RAM、VRAM、Apple unified memory 選模型與量化，啟動本機 API，最後真的接上 Claude Code 或 Codex。

這正是新手最容易卡住的地方。2026 年 8 月 11–12 日的社群討論，同時出現非技術使用者分不清 Unsloth、LM Studio、Hermes、標稱記憶體很大卻只看到少量可用 VRAM，以及 DGX Spark／ARM 安裝包不相容等問題。它們是需求與踩坑訊號，不是產品規格；本文所有支援邊界都重新以官方文件與當前 release 查核。

先說結論：Unsloth Desktop 適合誰？

• 想用圖形介面一次完成下載、聊天、量化／訓練／匯出與 API：選 Unsloth Desktop；它是安裝與啟動 Unsloth Studio 最省事的入口。
• 只想要成熟的桌面聊天與 local server：LM Studio 更聚焦。
• 喜歡 CLI、背景服務與自動化：Ollama 的 mental model 更簡單。
• 要記憶、skills、terminal、排程與訊息平台：Hermes Agent 是上層 Agent harness，仍要再選 Unsloth、LM Studio、Ollama 或雲端模型當後端。

若尚未盤點硬體，本文採用的最短路徑是：官方 Desktop 安裝包 → 7–9B instruct 模型 → Q4_K_M；若該模型頁明確推薦 Dynamic Q4 才改選 → 8K context → Auto 配置 → localhost API → unsloth start claude／unsloth start codex。確認約有 12–16GB 可用加速器記憶體，且實際 GGUF、KV 與 buffer 裝得下，再試 14B。

Unsloth Desktop 與 Studio 是什麼？兩者不是競品

Unsloth Desktop 是 Beta 階段的開源 Tauri 原生 App，也是安裝與啟動 Studio 最省事的方式；Unsloth Studio 則是本機 browser-based web UI。兩者承接同一套模型、聊天、訓練與 API 工作流，不是互相競爭的兩個推論引擎。

它底下仍要靠推論後端處理 GGUF、MLX 或其他格式。若想先理解 llama.cpp、vLLM、MLX 這類底層分工，可搭配本機 LLM 推理引擎完整解析；本文則把焦點放在成品工具操作。

Unsloth Desktop 教學步驟 1：先確認平台與安裝包

截至 2026 年 8 月 13 日的 v0.1.701-beta release 與 updater manifest，可以確認的 Desktop 組合只有：

• macOS：Apple Silicon（arm64）DMG。當前 release 沒有 Intel Mac Desktop build。
• Windows：Windows 10／11 x86_64 EXE。
• Linux：x86_64 DEB；AppImage 被官方標成 experimental，可能遇到 blank window，Ubuntu 24.04 也可能需要 libfuse2t64。

最簡單是從官方 Download 頁取得對應安裝包。若你只要 Studio，官方也提供手動安裝：

# macOS / Linux / WSL
curl -fsSL https://unsloth.ai/install.sh | sh

# Windows PowerShell
irm https://unsloth.ai/install.ps1 | iex

完成後執行 unsloth studio，預設只開在 http://127.0.0.1:8888。手動腳本是否支援你的 CPU、GPU 與訓練 backend，仍要分別檢查；「能開 Studio」不等於所有訓練功能都可用。

步驟 2：從 Model Hub 選對模型，不要只追最大參數

第一次選模型，先回答三個問題：

1. 用途：一般聊天選 instruct；寫程式選有 coding／tool-use 訓練的 instruct 模型。不要把 base model 當聊天模型。
2. 權重總大小：MoE 顯示的 active parameters 不能代表 GGUF 下載容量；多 shard 要全部加總。實際 RAM／VRAM residency 仍會受 mmap、expert offload 與 placement 影響。
3. 可用記憶體：看當下 free RAM／VRAM，不看機器包裝盒上的總容量。Apple Silicon 的 unified memory 是 CPU、GPU、macOS 與其他 App 共用同一池，不是 RAM 再加一份 VRAM。

步驟 3：依 RAM、VRAM、Unified Memory 選量化

量化可理解成「把權重壓小」。Q4_K_M 不是每個 tensor 都只有 4 bit，而是混合量化配方；因此不能直接用參數量乘 0.5 bytes 當成最終檔案大小。llama.cpp 的量化示例顯示，同一模型的 Q5_K_M 權重約比 Q4_K_M 大 16%，Q8_0 約大 74%；不同架構與 Unsloth Dynamic quant 會偏離這個比例。

• Q4_K_M：第一次下載的實用起點，容量與品質較平衡。
• Q5_K_M：檔案較大，通常屬較保守的量化；是否比 Q4 更準，仍要看該模型的 KLD／PPL 或實際任務測試。
• Q8_0：小模型、品質對照或精度比容量重要時再選。
• FP16／BF16：權重約 2 bytes／parameter，本機聊天通常不划算。
• UD-Q4_K_XL 等 Dynamic quant：是依模型調整 tensor 精度的配方，不等同標準 Q4；直接看該模型頁與實際檔案大小。

Context 是第二個旋鈕；KV cache 通常隨 context 增長，實際容量取決於 layer 數、KV heads、head dimension、cache datatype 與 backend。模型標榜 128K，不代表第一次就該開 128K。Coding agent 先從 8K 或 16K 起跑，穩定後再增加。

步驟 4：下載、載入並跑出第一個本機回答

1. 開啟 Desktop／Studio，按 Select model 或進入 Model Hub。
2. 選 instruct GGUF 與 Q4 量化，先保留 Auto 的 GPU placement／context。
3. 下載完成後載入模型，把 context 設為 8K。
4. 先問一個短問題，再要求它輸出一小段 JSON 或呼叫一個無副作用工具，確認聊天格式與 tool-use 能力。
5. 查看啟動 log 的 weight、KV、compute buffer；若載入失敗，先縮 context 或換小量化，不要第一步就用 swap 硬撐。

若已經有 Hugging Face 或 LM Studio 模型，不要移動唯一副本。官方文件對自動偵測 LM Studio folder 的敘述並不一致；穩健作法是在 UI 指定 custom folder。Hugging Face 預設 cache 是 macOS／Linux／WSL 的 ~/.cache/huggingface/hub/，Windows 則是 %USERPROFILE%\.cache\huggingface\hub\。

Unsloth、LM Studio、Ollama、Hermes 決策樹

選 Unsloth，如果你想在同一套 UI 裡下載、聊天、量化／訓練／匯出，再把模型供給 Agent。選 LM Studio，如果核心需求是桌面模型探索、聊天與 local API。選 Ollama，如果你偏好 CLI、daemon 與 script。選 Hermes Agent，如果你要的是帶記憶、skills、terminal、web 與長駐工作流的 Agent；詳細分層可看Hermes Agent 進階教學與AI Agent Harness 是什麼。

這四者可以組合，而非只能四選一。例如 Hermes 可把 Unsloth 當 inference provider；Codex 也已為 Ollama、LM Studio 提供內建 local provider，而 Unsloth 則走自訂 Responses provider或官方 wrapper。

步驟 5：開本機 API，先取得 token 與精確 model ID

模型載入後，到 Settings → API 建立 token。它以 sk-unsloth- 開頭，只顯示一次；伺服器只保存 hash，也可以撤銷。先把 URL 與 key 放入 shell 變數，再列出模型：

export UNSLOTH_URL="http://127.0.0.1:8888"
export UNSLOTH_KEY="sk-unsloth-REPLACE_ME"

curl "$UNSLOTH_URL/v1/models" \
  -H "Authorization: Bearer $UNSLOTH_KEY"

從回傳 JSON 複製精確的 id，不要憑 Model Hub 顯示名稱猜。Unsloth 同一個 port 目前提供 Anthropic Messages、OpenAI Chat Completions 與 OpenAI Responses；哪個 client 能接，取決於它實際使用哪套 wire API。若還不熟本機／雲端 endpoint，可先看本機與雲端 API 操作觀念。

步驟 6：Unsloth 串 Claude Code

最穩妥的新手路徑是讓 Unsloth 為這次 session 注入隔離設定，不改掉你平常使用 Claude Code 的設定：

# Studio 已載入 GGUF 模型
unsloth start claude

若要指定模型與 context，使用 --model 與 --context-length；模型值以 /v1/models 回傳為準。手動設定時，Claude Code 的 base URL 不要加 /v1：

export ANTHROPIC_BASE_URL="http://127.0.0.1:8888"
export ANTHROPIC_AUTH_TOKEN="sk-unsloth-REPLACE_ME"
export ANTHROPIC_MODEL="REPLACE_WITH_EXACT_MODEL_ID"
unset ANTHROPIC_API_KEY

claude --model "$ANTHROPIC_MODEL"

步驟 7：Unsloth 串 Codex CLI

最短路徑同樣是 wrapper：

# Studio 已載入 GGUF 模型
unsloth start codex

截至查核日，Unsloth 的 Codex 整合要求由 llama-server 提供 GGUF。若要固定成自己的 profile，在 ~/.codex/config.toml 加入 custom provider：

[model_providers.unsloth_api]
name = "Unsloth Studio"
base_url = "http://127.0.0.1:8888/v1"
env_key = "UNSLOTH_STUDIO_AUTH_TOKEN"
wire_api = "responses"
requires_openai_auth = false

再建立 ~/.codex/unsloth_api.config.toml：

model_provider = "unsloth_api"
model = "REPLACE_WITH_EXACT_MODEL_ID"

export UNSLOTH_STUDIO_AUTH_TOKEN="sk-unsloth-REPLACE_ME"
codex --profile unsloth_api

OpenAI Codex config reference目前只接受 wire_api = "responses"；只有 /v1/chat/completions 的「OpenAI-compatible」server 不夠。ollama 與 lmstudio 是 Codex 保留的內建 provider ID，Unsloth 要另取像 unsloth_api 的名稱。想先比較兩個 coding agent 的工作方式，可看Claude Code vs Codex。

先做 API smoke test，再讓 Agent 改檔

不要一開始就讓 Agent 掃整個專案。先用一個 32-token、無工具的 request 檢查兩條 wire：

export MODEL_ID="REPLACE_WITH_EXACT_MODEL_ID"

curl -N "$UNSLOTH_URL/v1/messages?beta=true" \
  -H "Authorization: Bearer $UNSLOTH_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d "{\"model\":\"$MODEL_ID\",\"max_tokens\":32,\"stream\":true,\"messages\":[{\"role\":\"user\",\"content\":\"Reply with OK\"}]}"

curl -N "$UNSLOTH_URL/v1/responses" \
  -H "Authorization: Bearer $UNSLOTH_KEY" \
  -H "content-type: application/json" \
  -d "{\"model\":\"$MODEL_ID\",\"input\":\"Reply with OK\",\"stream\":true}"

這兩個 curl 只驗 endpoint、auth 與 streaming framing，不代表 Agent tool loop 已通過。回應正常後，再進一個測試資料夾，要求 Agent 讀一個小檔、建立新檔，最後由你檢查 diff。小模型的 tool use、長指令遵循與程式推理通常弱於前沿雲端模型；本機執行的價值是隱私、成本控制與離線能力，不是自動取得同等品質。建立完整權限與測試護欄，可延伸從零打造 AI Agent Harness。

LAN、Tunnel、API endpoint 怎麼設才安全？

• 只在本機用：維持 127.0.0.1:8888，不要為了方便改成 0.0.0.0。
• 可信任 LAN：使用 -H 0.0.0.0 -p 8888 前，先設定強管理員密碼、API key、防火牆與網段限制，並加 --disable-tools。
• 臨時 tunnel：unsloth studio --secure 只綁 loopback，再建立隨機 Cloudflare Quick Tunnel；URL、登入密碼與 API key 都當 secret。
• 不要混用：-H 0.0.0.0 --cloudflare 會同時留下 raw LAN port 與 public URL，是最不私密的組合。

Quick Tunnel 目前不支援 SSE；能控制 request 的遠端 API client 應設 stream: false。Claude Code 目前有 streaming 失敗後的 non-streaming fallback，但 Anthropic 與 Unsloth 都未保證 Quick Tunnel 上的 Claude Code 完整相容；把它列為每版實測項目，不承諾穩定。更重要的是，Unsloth 的 web、Python、terminal 等 server-side tools 會在執行 Unsloth 的主機上執行 Python／Bash；只要 endpoint 會被別人連到，就應以 process-level --disable-tools 關閉，讓 Claude Code／Codex 自己的權限層接手。

最常見的 8 個問題與排除順序

1. 載不進 GPU：確認全部 GGUF shard 總大小、當下 free VRAM、KV 與 compute buffer；先縮 context，再換 Q4 或讓部分 layer 留在 RAM。
2. Apple 32GB 卻跑不動 30GB 權重：30GB 只算權重，macOS、KV、buffer 與其他 App 都用同一池 unified memory。
3. AMD／Strix Halo 只顯示少量可用記憶體：若 OEM／BIOS 提供 Variable Graphics Memory 或 UMA frame-buffer 設定，再檢查其分配值；另查 Windows／WSL 上限、當下使用量與 backend 偵測，不要把其中一個數字當總實體容量。
4. WSL 只用到一半 RAM：Microsoft 的 WSL 2 預設 memory 上限是 Windows 總記憶體的 50%；調整 .wslconfig 後要重啟 WSL，但這不代表所有 AMD 問題都由它造成。
5. 模型有 128K context 卻 OOM：先退回 8K。一般 full-attention Transformer 在固定 cache type 與 sequence 數下，context 增加時 KV 通常近似線性增加；SWA、hybrid 或 recurrent 模型要看實際架構與載入 log。
6. Codex 回 404：確認 base URL 含 /v1、server 有 /v1/responses，且 wire_api 是 responses。
7. Claude Code 回 400／401：base URL 不加 /v1；檢查 ANTHROPIC_AUTH_TOKEN、精確 model ID 與 Messages 相容層。
8. Agent 有回覆但不呼叫工具：確認模型真的有 tool-use 訓練，並關閉 Unsloth server-side tools，避免工具呼叫被 server 自己消化。

版本快速變動：安裝前檢查這 4 件事

• Release artifact 是否真的有你的 OS＋CPU architecture，而不是只看下載頁標籤。
• 欲用的模型頁是否列出該量化的實際檔案大小、格式與 backend。
• /v1/messages、/v1/responses 是否在當前 build 通過 smoke test。
• Claude Code／Codex 更新後，wrapper 與自訂 provider 是否仍能完成一次檔案讀寫測試。

本文版本錨點是 2026 年 8 月 13 日、Unsloth Desktop v0.1.701-beta。特別是 AMD、Linux ARM、Intel Mac、Responses tool loop 與 tunnel streaming，都屬於應在每次升級後重驗的邊界。

Unsloth Desktop 教學 FAQ

1. Unsloth Desktop 免費嗎？

是，官方目前把 Desktop 標示為免費、開源、Beta。 本機推論本身沒有雲端 token 費，但電力、硬體、儲存與你另接的雲端服務仍有成本。

2. 8GB VRAM 可以跑什麼？

先從 7–9B Q4、8K context 試。 實際仍要看 GGUF 大小、KV cache、桌面占用與 offload；這是起點，不是保證。

3. Apple unified memory 要算 RAM 還是 VRAM？

算同一池共享記憶體。 32GB Mac 不是 32GB RAM 加 32GB VRAM；模型、KV、Metal、macOS 與其他 App 一起使用這 32GB。

4. Q4、Q5、Q8 哪個最好？

沒有通用最好；Q4 是新手最實用起點。 有餘裕選 Q5，小模型或品質對照選 Q8；Dynamic quant 則看模型頁與實際檔案。

5. Unsloth 可以取代 LM Studio 或 Ollama 嗎？

功能有重疊，但工作流不同。 Unsloth 把訓練／量化／匯出也放進工作台；LM Studio 更偏桌面 runner，Ollama 更偏 CLI server。選最符合日常操作的即可。

6. Unsloth 能讓 Claude Code 完全離線嗎？

模型推理與 API 可以留在本機，但 Claude Code 預設仍可能產生非必要背景流量。 網路必須完全封閉時，另設 CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1，停用模型下載、web search、Cloudflare tunnel、雲端 MCP；若仍啟用 WebFetch，domain safety check 還要以 skipWebFetchPreflight: true 另行處理。即使如此，非 Claude 模型路由仍不是 Anthropic 支援的配置。

7. 為什麼 Codex 不能接只有 Chat Completions 的 server？

因為目前 Codex custom provider 要求 OpenAI Responses wire。 URL 必須能處理 /v1/responses；「OpenAI-compatible」四個字沒有說清楚 endpoint，不能當驗收結果。

8. DGX Spark 可以裝 Unsloth Desktop 嗎？

當前 release 不能據此宣稱支援。 DGX Spark 是 Linux ARM，現有 Desktop artifact matrix 沒有 linux-aarch64；特定模型可用 vLLM／NVFP4 跑，不代表 Desktop App 已可安裝。

給新手的 8 個重點

1. Desktop 是 Studio 的原生入口，不是另一套競品。
2. 先核對 OS＋CPU artifact，尤其 Linux ARM 與 Intel Mac。
3. 模型容量以全部 GGUF 檔案為底線，不以參數名稱猜。
4. Q4、8K context、Auto 是第一次成功的合理起點。
5. Unified memory 不是 RAM 加 VRAM。
6. Claude Code 用 Messages；Codex 用 Responses。
7. 先過 API smoke test，再給 Agent 專案權限。
8. 只在 localhost 用最安全；外露 endpoint 時關閉 server-side tools。