讀完本章後、你應該能在 Windows 上：選對 LM Studio 的 GPU backend、在 GUI 內設定卸載層數與 KV cache 量化、啟動 OpenAI 相容 server、接到 VS Code Continue.dev。

本章目標

1. 在 Windows 上安裝 LM Studio、選對 GPU backend。
2. 知道 GUI 設定面板的哪幾個欄位對應 llama.cpp 的核心旗標。
3. 啟動 LM Studio 的本地 server、提供 OpenAI 相容 API。
4. 判斷你的工作流適不適合用 LM Studio 當主力。
5. 處理常見的 Windows + GPU 整合議題（driver 版本、CUDA toolkit）。

安裝

LM Studio 是 Electron 桌面 app、個人使用免費、Windows / Linux / macOS 三平台都支援。從 lmstudio.ai 官網 下載對應系統的安裝檔即可。

Windows 版的安裝步驟：

1. 下載 .exe 安裝程式、執行安裝（不需 admin 權限的情況下會裝在使用者目錄）。
2. 首次啟動時、LM Studio 會偵測 GPU 並提示選擇 backend。

事實查核註：LM Studio 是商業軟體、UI 跟功能會隨版本變化。本章描述以 2026 年 5 月的穩定版為基準、實際 UI 元素位置以當前版本為準。

GPU backend 選擇

LM Studio 在 Windows 上的 GPU compute backend 選項依 GPU 廠商不同：

backend 的切換位置：LM Studio 的設定面板（齒輪圖示）→ Hardware / Runtime 區段、會列出當前可用的 backend 與下載連結。部分 backend 在首次使用時需要下載對應的 runtime（如 CUDA runtime）。

選錯 backend 的常見徵兆：

1. 模型載入時間異常長：可能 fallback 到 CPU、確認 GPU backend 是否正確啟用。
2. 生字速度遠低於同硬體的社群回報：backend 不對、或 driver 版本不對、或 VRAM 不足而啟用了 CPU offload。
3. 載入時錯誤訊息提到 CUDA 版本不符：driver 跟 LM Studio 內建的 CUDA runtime 不對齊、需更新 driver 或選擇對應的 LM Studio build。

事實查核註：各 backend 的可用性跟下載方式依 LM Studio 版本變動、以當前版本的 Hardware / Runtime 設定面板顯示為準。

GUI 設定對應到 llama.cpp 旗標

LM Studio 在背後使用 llama.cpp、GUI 內的設定欄位通常對應到 llama.cpp 的某個旗標。對熟悉 5.3 llama.cpp 在 PC 上 旗標的讀者、這個對應表能加速 GUI 內的設定：

具體欄位名稱跟位置依 LM Studio 版本變化、以實際 UI 為準。新加入 llama.cpp 的旗標通常會在後續 LM Studio 版本被加進 GUI。

啟動 LM Studio Server

LM Studio 內建 OpenAI 相容 server、預設 port 1234。啟用步驟：

1. 載入想用的模型（GUI 左側 Chat / Local Server 切換）。
2. 切到「Local Server」分頁。
3. 設定上面對應的旗標（GPU Offload、Context、KV Quant、MoE Offload 等）。
4. 點「Start Server」、看 log 確認模型載入成功、port 顯示為 1234（或自訂）。

啟動成功後、可以用任何 OpenAI 相容 client 連接：

1curl http://localhost:1234/v1/chat/completions \
2  -H "Content-Type: application/json" \
3  -d '{
4    "model": "loaded-model-name",
5    "messages": [{"role": "user", "content": "Hi"}]
6  }'

接到 VS Code Continue.dev：

 1{
 2  "models": [
 3    {
 4      "title": "LM Studio",
 5      "provider": "openai",
 6      "model": "loaded-model-name",
 7      "apiBase": "http://localhost:1234/v1",
 8      "apiKey": "not-needed"
 9    }
10  ]
11}

model 欄位填 LM Studio 載入的模型名稱、要跟 GUI 顯示一致。

模型瀏覽器與下載

LM Studio 的內建模型瀏覽器直接連到 Hugging Face、可以搜尋 GGUF 格式的模型並一鍵下載。對「想試新模型但不想自己抓 GGUF」的使用者較友善。

下載時的選擇：

1. 量化等級：LM Studio 會列出可用的量化版本（Q4_K_M、Q5_K_M、Q8_0 等）、可依 VRAM 預算選擇。
2. 模型大小估計：LM Studio 通常會顯示「在你當前硬體上能不能跑」的提示；提示為估計、實際載入仍以 llama.cpp 啟動結果為準。
3. 下載位置：LM Studio 預設下載到使用者目錄；可在設定面板改路徑（適合把模型放到大容量 SSD）。

事實查核註：LM Studio 對「能否在當前硬體跑」的判讀是基於 VRAM + RAM 容量的估算、不考慮 MoE 卸載、KV cache 量化等進階設定；提示僅供參考、實際以實測為準。

跟 Ollama / llama.cpp 並存

LM Studio、Ollama、llama-server 可以同時跑、用不同 port：

實務上同時跑多個的場景是調參階段比較不同 backend 或設定；常態使用通常一個就夠。

切換主力的判讀：

Windows + GPU 整合常見議題

Windows 上跑本地 LLM 的常見議題：

1. NVIDIA driver 版本：driver 太舊可能不支援 LM Studio 內建的 CUDA runtime；過新 driver 偶爾出現相容性問題。建議用 NVIDIA Studio Driver（相對 Game Ready Driver 更穩）、或 NVIDIA 官方建議的當前長期支援版本。
2. WSL2 vs 原生 Windows：LM Studio 在原生 Windows 跟 WSL2 都能跑；WSL2 可以更接近 Linux 環境（適合熟悉 Linux 工具的使用者）、但 GPU 透傳的配置略多。
3. windows defender / 防毒軟體掃描：模型檔案常為 10+ GB、安全軟體的即時掃描可能拖慢載入速度；建議把模型目錄加入排除清單。
4. 電源計劃：Windows 的「省電」電源計劃可能讓 CPU 在閒置時降頻、影響 prefill 速度；建議使用「高效能」或自訂「卓越效能」計劃。
5. VRAM 被其他應用佔用：Chrome、Discord、遊戲都可能佔用 VRAM；觀察「工作管理員 → 效能 → GPU」確認 VRAM 餘量。

事實查核註：上面的議題以 Windows 10 / 11 為背景、具體現象跟解法依 Windows 版本、driver 版本變化。引用前以自己版本的官方文件為準。

給多數讀者的建議

LM Studio 在 Windows + 獨立 GPU 場景的核心價值是「降低 MoE 卸載與 KV cache 量化的學習成本」。對下面類型的使用者特別合適：

1. 剛接觸本地 LLM、不熟悉 CLI 旗標。
2. 主力工作是探索新模型、不是調穩定 production-like 設定。
3. 想視覺化看「卸載層數 vs VRAM 用量」的關係、再決定要不要轉到 CLI。

對下面類型的使用者、Ollama 或直接 llama-server 通常更適合：

1. 熟悉 CLI、想最完整地控制旗標。
2. 主力是穩定日常寫 code、模型不常換。
3. 想用 llama-bench 做精確校準。
4. 部署到團隊或多人共用的 server 環境（GUI app 不適合 headless 部署）。

下一章

下一章：5.5 PC 場景的模型選型優先順序、用前面四章建好的工程選項回答「具體裝哪個模型」。

讀完本模組後、你應該能對自己這台 PC 直接回答：能跑哪些模型、要不要卸載 MoE 專家層到 RAM、KV cache 該量化到哪一級、context 能開多大、併發數能拉到多少。

為什麼 PC 路線值得獨立模組

Mac 統一記憶體的判讀模型把「能載入多大模型」這個問題收斂到一塊預算。PC 場景被獨立 VRAM 拆成兩個記憶體區域、判讀軸增加：

1. VRAM：高頻寬區。常見消費級 NVIDIA 卡的廠商標稱頻寬大致落在數百 GB/s 到 1 TB/s 級的區間（例如 RTX 5060 Ti 16GB 標稱約 448 GB/s、RTX 5070 Ti 標稱約 896 GB/s、以廠商規格表為準）、生字速度上限主要受 VRAM 頻寬影響。
2. 系統 RAM：高容量區。DDR5 6000 雙通道的標稱頻寬約 96 GB/s（依主機板與時序變化）、相對 VRAM 慢約一個量級、但 64GB / 128GB 在 PC 平台的擴充成本相對低、適合放容量需求大但存取頻率較低的權重。
3. PCIe：兩個區域之間的連線。PCIe 5.0 x16 廠商標稱單向約 64 GB/s（PCIe 4.0 x16 約一半）；實際傳輸吞吐受驅動、檔案系統與工作流影響。

這三層差異產生兩個 Mac 場景上較少出現的工程選項：

1. MoE 模型 + 專家層 CPU 卸載：MoE 模型每個 token 只啟用少數專家、把不活躍的專家權重放在系統 RAM、用到再走 PCIe 拉回 GPU。讓 16GB VRAM 卡能載入 30B / 70B 等級的 MoE 模型。
2. KV cache 量化開大 context：把 K cache 量化到 Q8、V cache 量化到 Q4、KV cache 體積大幅壓縮、騰出的 VRAM 可用於開大 context window 或提高併發數。

這兩個選項在 Mac 統一記憶體場景下較少使用（VRAM 跟 RAM 共用、不需在兩個區域之間搬資料）、在 PC 場景則是常用的調參工具。

章節列表

跟模組一的對應關係

最短路徑：16GB VRAM + 64GB RAM 跑 Qwen3 30B MoE

事實查核註：本模組引用的硬體規格、模型體積、社群實測數量級、廠商工具鏈成熟度、皆以 2026 年 5 月的公開資訊與社群常見回報為基準。GPU 規格、driver 版本、llama.cpp release、模型釋出與量化版本快速演進、引用前請以 llama.cpp release notes、各廠商官方規格表、各模型 Hugging Face model card 為準、並用 llama-bench 或實際工作流校準。

如果你有類似 RTX 5060 Ti 16GB / 5070 Ti 16GB + 64GB DDR5 的配置、想用一小時搞定 PC 本地 LLM 寫 code、下面是最短路徑：

 1# 1. 裝 llama.cpp 的 CUDA build（Windows / Linux 各有預編好的 release）
 2# 從 ggml-org/llama.cpp GitHub release 抓 CUDA 12.x 版
 3
 4# 2. 抓一個 MoE 模型（如 Qwen3-30B-A3B 的 GGUF Q4_K_M 版本）
 5# 從 Hugging Face 下載到 ~/models/
 6
 7# 3. 啟動 server、把 30 層 MoE 專家層卸載到 CPU
 8./llama-server \
 9  -m ~/models/Qwen3-30B-A3B-Q4_K_M.gguf \
10  -ngl 99 \
11  --n-cpu-moe 30 \
12  --cache-type-k q8_0 \
13  --cache-type-v q4_0 \
14  -c 32768 \
15  --port 8080
16
17# 4. 在 VS Code 裝 Continue 擴充套件、config 指向 http://localhost:8080

關鍵參數的意義先濃縮成一句、詳細推導留給 5.3 llama.cpp 在 PC 上：

• -ngl 99：把所有可放的層丟到 GPU。
• --n-cpu-moe 30：把 30 層的 MoE 專家權重留在系統 RAM、不上 VRAM。實際層數視模型結構與 VRAM 餘量微調。
• --cache-type-k q8_0 / --cache-type-v q4_0：KV cache 量化、騰出 VRAM 開大 context。
• -c 32768：context window。配上 KV cache 量化、單卡 16GB 通常能開到 128K ~ 256K（看模型）。

為什麼這個順序

本模組章節順序的設計脈絡：

1. 先 5.0 VRAM + RAM 分層預算：建立 PC 硬體判讀模型、是後面所有章節的前提。
2. 再 5.1 MoE 卸載：MoE + CPU 卸載是 PC 場景相對 Mac 的核心優勢、先把這個工程選項說清楚。
3. 接 5.2 KV cache 量化：跟 5.1 一起決定 VRAM 怎麼切、是 PC 場景的第二個獨有選項。
4. 再 5.3 llama.cpp 在 PC 上：把前三章的理論落地到實際參數。
5. 再 5.4 LM Studio 在 Windows：給「不想直接面對 CLI」的讀者另一條路、補上 GUI 內對應 5.1 / 5.2 設定的位置。
6. 然後 5.5 模型選型：所有工程選項都建立後、回答「具體裝哪個模型」。
7. 最後 5.6 GPU 廠商差異：選好模型跟參數後、再處理 NVIDIA / AMD / Intel 的工具鏈差異。

不在本模組內的主題

本模組不討論：

1. 多卡 NVLink、tensor parallelism：消費級 PC 場景通常單卡、多卡分散式推論屬於資料中心級教材。
2. 資料中心級 GPU（H100 / H200 / B200）部署：本模組聚焦消費級 PC、不涵蓋 vLLM / TGI / Triton 等資料中心 inference server。
3. Linux 系統管理 / CUDA 驅動安裝細節：假設讀者已會基本系統管理；具體驅動安裝步驟交給 NVIDIA / AMD 官方文件。
4. 訓練 / fine-tuning：跟「跑現成模型」是不同工程問題、見 模組三 與其推薦課程。
5. 產圖模型：Diffusion 跟 Transformer 是不同架構、見 ComfyUI / Stable Diffusion 專門教材。

本指南預設讀者已經會用過雲端 LLM（ChatGPT、Claude）、熟悉終端機操作、想以工程視角理解 LLM。寫 code 場景是主要使用例、但模組二 / 三 / 四 / 六多數章節跨場景通用：想懂 reasoning model / RAG / embedding model 內部、即使不裝本地 LLM 也能讀。硬體前提分兩條路線：Apple Silicon Mac（M1 ~ M4、統一記憶體）走模組一；Windows / Linux + 獨立 GPU（NVIDIA / AMD、獨立 VRAM + 系統 RAM）走模組五。文章不販賣 LLM 焦慮、也不誇大本地能取代雲端的程度；它的責任是給每條讀者旅程的最短可行路徑、並標出每個階段的取捨。

模組零（心智模型）是所有讀者旅程的共同前置。模組一跟模組五是「裝本地 LLM」的兩條硬體路線、依平台選一條；想懂底層走模組二跟模組三（跟硬體無關、含 reasoning model / speculative decoding 等推論細節）；想看 LLM 作為系統元件走模組四（12 章涵蓋 RAG、tool use、agent、應用層協議、workflow、production resource、long context、embedding model、benchmarking、vision、靜態 deployment）；本地工作流跑穩想看安全議題走模組六（個人 dev 視角的供應鏈、伺服器綁定、tool use 權限、prompt injection、跨雲端邊界、production routing）。

教材邊界

學習路線

本指南分成七個模組加一組前置卡片（111 張）。讀者依目的選讀、不需要從頭到尾全讀：

• 想用 Apple Silicon Mac 裝本地 LLM 寫 code：讀模組零 + 模組一（最短路徑）
• 想用 Windows / Linux + 獨立 GPU 裝：讀模組零 + 模組五
• 想懂 LLM 內部原理：模組二（數學） + 模組三（理論、含 reasoning models / speculative decoding）— 跟硬體無關
• 想做 LLM 應用開發（含 RAG / agent / VLM / 靜態 deployment）：模組四（12 章、跨工具世代不變的原理）— 跟硬體無關
• 想懂本地工作流的安全議題：模組一 / 五跑穩後接模組六（個人 dev 視角）
• 想選 RAG 的 storage 方案（pickle / vector DB / hosted SaaS）：直接看 4.22 RAG storage 工程
• 想在靜態網站加 RAG / 智能搜尋：直接看 4.16 靜態 / serverless RAG deployment
• 想在本機 fine-tune 模型：模組三 3.4 訓練流程原理 → 本機 QLoRA hands-on
• 想跟最新進展接軌：讀完模組後進推薦的公開課程跟 paper（模組二 2.4 + 模組三 3.10）

前置知識卡片

用原子化卡片整理 token、自回歸、KV cache、量化、speculative decoding、MTP、MLX、推論伺服器、OpenAI 相容 API、memory bandwidth、統一記憶體、TTFT、prefill、context window、Transformer、Diffusion 等核心概念。章節文章專注情境推導、術語背景交由卡片維持一致。

模組零：基礎知識與心智模型

整理本地 vs 雲端 LLM 的差異、自回歸架構與記憶體頻寬瓶頸、介面 / 伺服器 / 模型三層心智模型、OpenAI 相容 API 為何重要、MLX / MTP / oMLX 三個容易搞混的術語、Apple Silicon Mac 記憶體與模型大小的對應關係、判讀本地 LLM 資訊的五個框架。

模組一：本地 LLM 服務的安裝與應用

整理 Ollama、LM Studio、llama.cpp 三個主流推論伺服器的現況差異與安裝路徑、用 Continue.dev 把本地 LLM 接到 VS Code 的完整步驟、寫 code 場景下模型選型的優先順序、本地模型的期望管理、想進一步玩 coding agent、Web UI、產圖時的延伸方向。

模組二：LLM 的數學基礎

整理 LLM 推論背後的數學工具：線性代數（向量、矩陣、空間）、機率與資訊論（softmax、cross-entropy、KL、perplexity）、微積分與最佳化（gradient、SGD / Adam）、數值精度（fp32 / bf16 / Q4 / Q8 的取捨）。每章末尾接到公開課推薦。

模組三：LLM 的理論基礎

整理 LLM 內部運作機制、共 11 章：神經網路基礎、embedding 空間、attention 機制、Transformer 架構、訓練流程（pre-train → SFT → RLHF / DPO）、sampling 策略、tokenization 算法、跨語言場景原理、Reasoning models（o1 / R1 / QwQ 等 test-time compute paradigm）、Speculative decoding 內部（drafter / MTP / EAGLE）。每章末尾接到公開課推薦（Karpathy、Stanford CS224N / CS25 / CS336、DeepLearning.AI）。

模組四：LLM 應用層原理

整理 LLM 作為系統元件的設計原理、共 12 章：RAG、tool use、agent 架構、應用層協議、workflow 編排模式、Production resource planning、衍生產物管理、Long context engineering、Embedding model 內部、Benchmarking 方法論、Vision in coding workflow（本地 VLM 接 IDE）、靜態 / serverless RAG deployment（沒 backend 場景）。本模組刻意只寫跨工具世代不變的原理、避開 LangChain / LlamaIndex 等具體 framework 教學。

模組五：Windows / Linux + 獨立 GPU

整理消費級 PC（Windows / Linux + NVIDIA / AMD 獨立 GPU）跑本地 LLM 的硬體判讀模型與工程選項：VRAM + RAM 分層預算、MoE 模型的 CPU 卸載策略（--n-cpu-moe）、KV cache 量化（K=Q8 / V=Q4）跟 context 長度的權衡、llama.cpp 在 PC 上的調參空間。本模組跟模組一是平行的硬體路線、共用模組零的心智模型跟卡片。

模組六：本地 LLM 的安全與權限

整理個人 dev 在自己機器上跑本地 LLM 的安全議題：模型供應鏈與信任邊界、推論伺服器的綁定與暴露範圍、tool use 與 MCP server 的權限模型、IDE 場景的 prompt injection、跨雲端 / 本地的資料邊界、跨進 production 的 routing 中樞。framing 是個人 dev 視角、不是 enterprise 資安管理；production / 多租戶 LLM 服務的特殊資安議題見 Backend 模組七 資安與資料保護 的 LLM 相關章節。

模組之間怎麼配合

模組二跟模組三可並讀。閱讀模組三遇到陌生數學詞時跳回模組二補完、再回模組三繼續。模組四在前面模組之上、但讀者熟悉 LLM 應用詞彙也可直接從這裡讀起。模組一跟模組五依硬體選一條主路線、共用模組零的心智模型與 knowledge-cards。模組六在模組一 / 五跑穩後接、處理「跑起來後該注意什麼」。

適合的讀者

用語約定

本指南使用的關鍵術語在第一次出現時都附原文。為避免歧義，下列詞彙在本指南內固定指涉：

1. 本地 LLM：跑在使用者自己機器（Mac 或 PC）上的大型語言模型推論、prompt 留在本機。
2. 推論伺服器（inference server）：負責載入模型權重、處理 prompt、產生 token 的常駐程式、例如 Ollama、LM Studio 內建 server、llama.cpp server。
3. 介面層：使用者實際打字互動的工具、例如 VS Code + Continue.dev、CLI、Web UI。介面層透過 API 跟推論伺服器溝通。
4. 模型（model）：權重檔本身、例如 gemma4:31b、qwen3-coder:30b。模型可以在不同推論伺服器之間共用、前提是格式相容。
5. 量化（quantization）：把模型權重從高精度（如 bf16）壓成低精度（如 Q4）以減少記憶體佔用、代價是少許品質下降。

不在本指南內的主題

本指南不討論：

• Speech / audio LLM：跟核心文字 LLM 是不同方向、本指南不涵蓋。Vision（VLM）原本不放、但因 coding 工作流的 vision use case 進入主流、補上 4.15 Vision in coding workflow；video LLM 仍不放。
• 資料中心訓練的工程細節：data parallelism、ZeRO、tensor parallelism 等屬於專門課程的範圍。
• 向量資料庫的 vendor 比較（Pinecone vs Weaviate vs Chroma 等）：vendor 格局半年一變、不適合寫入教材。RAG 的 storage 工程原理（升級判讀、index 生命週期、dependency 約束）見 4.22 RAG storage 工程。
• Kubernetes / 資料中心級分散式推論：跟個人機器本地 LLM 方向不同、需另尋專門教材。
• 多卡 NVLink、tensor parallelism：消費級 PC 場景通常單卡、本指南不涵蓋多卡分散式推論。

若讀完本指南後想往這些方向走：

1. 想做 RAG 應用：先把 Ollama + Continue.dev 跑穩、再讀 模組四 4.1 RAG 原理 建立設計取捨判讀、或 模組三 3.8 推薦 的 DeepLearning.AI short courses。
2. 想跑 coding agent：先讀 4.4 Agent 架構原理 建立判讀、再看 1.6 延伸方向 了解 aider、Cline 等工具的定位差異。
3. 想跑產圖模型：Diffusion 跟 Transformer 是不同架構、請另尋 ComfyUI / Draw Things / Diffusers 教材。
4. 想自己訓練 / fine-tune：讀完模組三、進入 Karpathy zero-to-hero、Stanford CS336、Hugging Face NLP Course 等推薦資源。

文件版本：v0.7.0 最後更新：2026-05-12 系列狀態：七個模組 + 125 張知識卡片。模組零（9 章）/ 一（10 章 + hands-on、含 QLoRA + judge harness）/ 二（5 章）/ 三（12 章、含 reasoning / speculative / constrained decoding）/ 四（17 章、含 long context / embedding / benchmarking / VLM / 靜態 deployment / coding agent harness / prompt caching / agent memory / tracing / LLM-as-judge）/ 五（7 章）/ 六（7 章、含 OWASP 對照）。

目前推薦使用 Ed25519 演算法，相比 RSA 更安全、金鑰更短、驗證速度更快：

1ssh-keygen -t ed25519 -C "your_email@example.com"

若需相容較舊的系統（不支援 Ed25519），可退而使用 RSA-4096：

1ssh-keygen -t rsa -b 4096 -C "your_email@example.com"

產生時會提示設定 passphrase（密碼短語），強烈建議設定。即使私鑰外洩，攻擊者仍需要密碼才能使用。

1. 寫入金鑰檔案

macOS / Linux

1cat > ~/.ssh/<key_name> << 'EOF'
2（貼上金鑰內容）
3EOF

'EOF' 加單引號 → 防止 shell 解析內容中的特殊字元（如 $、`）

Windows（PowerShell）

1New-Item -Path "$env:USERPROFILE\.ssh" -ItemType Directory -Force
2Set-Content -Path "$env:USERPROFILE\.ssh\<key_name>" -Value @"
3（貼上金鑰內容）
4"@

Windows 的 SSH 金鑰預設路徑為 C:\Users\<使用者>\.ssh\

2. 設定權限

macOS / Linux

1chmod 600 ~/.ssh/<key_name>

chmod 600 → 僅擁有者可讀寫，SSH 要求私鑰權限不可過於開放，否則會拒絕使用。

Windows（PowerShell，以系統管理員執行）

1icacls "$env:USERPROFILE\.ssh\<key_name>" /inheritance:r /grant:r "$($env:USERNAME):(R)"

Windows 需透過 icacls 移除繼承權限，並限制為只有當前使用者可讀取。 若權限過於開放，OpenSSH 同樣會拒絕載入金鑰。

3. 加入 SSH Agent

macOS

1# 啟動 agent（通常 macOS 已自動啟動）
2eval "$(ssh-agent -s)"
3
4# 加入金鑰，並存入 Keychain 避免重開機後失效
5ssh-add --apple-use-keychain ~/.ssh/<key_name>

若要讓金鑰在每次登入時自動載入，可在 ~/.ssh/config 中加入：

1Host *
2  AddKeysToAgent yes
3  UseKeychain yes
4  IdentityFile ~/.ssh/<key_name>

Linux

1# 啟動 agent
2eval "$(ssh-agent -s)"
3
4# 加入金鑰
5ssh-add ~/.ssh/<key_name>

Linux 重開機後 agent 會重置。可將 eval "$(ssh-agent -s)" 加入 ~/.bashrc 或 ~/.zshrc 讓它自動啟動。

Windows（PowerShell，以系統管理員執行）

1# 啟用 ssh-agent 服務（預設為停用）
2Get-Service ssh-agent | Set-Service -StartupType Automatic -PassThru | Start-Service
3
4# 加入金鑰
5ssh-add "$env:USERPROFILE\.ssh\<key_name>"

Windows 的 ssh-agent 是系統服務，啟用後重開機也會自動執行，不需額外設定。

4. 測試連線

三個平台指令相同：

1ssh -i ~/.ssh/<key_name> -T git@<host>

Windows 請在 PowerShell 或 Git Bash 中執行，路徑會自動對應到 $env:USERPROFILE\.ssh\。

備註

安全性建議

優先使用 Ed25519

為私鑰設定 Passphrase

1# 為已存在的金鑰補設或更換 passphrase
2ssh-keygen -p -f ~/.ssh/<key_name>

即使私鑰檔案被他人取得，沒有 passphrase 就無法使用。搭配 SSH Agent 後只需輸入一次，不影響日常使用體驗。

定期輪換金鑰

建議每 1-2 年輪換一次 SSH 金鑰。可在金鑰名稱中加入年份作為提醒，例如 id_ed25519_2026。

其他注意事項

• 不要將私鑰上傳到雲端同步服務（如 iCloud、Google Drive、OneDrive），除非經過加密
• 不要在多台機器之間複製同一把私鑰，應為每台機器各自產生獨立金鑰
• 避免使用已棄用的 DSA 金鑰，部分新版 OpenSSH 已預設拒絕 DSA
• ~/.ssh/ 目錄本身權限應為 700，authorized_keys 應為 600

常見問題排查

Permission denied (publickey)

1. 確認私鑰權限：chmod 600 ~/.ssh/<key_name>
2. 確認 ~/.ssh/ 目錄權限：chmod 700 ~/.ssh
3. 確認上傳的是 公鑰（.pub）而非私鑰
4. 使用 verbose 模式查看詳細錯誤：ssh -vvv user@host

Agent 中沒有金鑰

1# 確認 agent 是否正在運行
2ssh-add -l
3
4# 如果顯示 "Could not open a connection to your authentication agent"
5eval "$(ssh-agent -s)"
6ssh-add ~/.ssh/<key_name>

金鑰類型被伺服器拒絕

部分較新的伺服器已停用 DSA 和較短的 RSA 金鑰。檢查方式：

1ssh -vvv user@host 2>&1 | grep "Offering"

如果你的金鑰類型不在伺服器接受的清單中，需要重新產生 Ed25519 金鑰。