KoboldCpp · 单文件可执行、内置 Web UI 的 GGUF 本地大模型运行器 · 部署与使用全指南
项目仓库： https://github.com/LostRuins/koboldcpp
开源协议：见仓库 LICENSE · 运行形态：单文件可执行（Windows / Linux /
macOS） · 底层：基于 llama.cpp · 模型格式：GGUF · 内置 Web
UI：http://localhost:5001 · 官方网站：koboldcpp.net
防钓鱼警告（官方 README 顶部）：
koboldcpp.com是恶意仿冒站点，与本项目无关。官方只信任 GitHub Releases 二进制与官网koboldcpp.net两个下载入口。
1 项目简介
KoboldCpp 是一个免费开源的本地大模型运行器，用于在自己的电脑上运行 GGUF 格式的大语言模型：和 AI 助手聊天、写故事、角色扮演，或把它当成本地 API 给其他应用调用。它受 KoboldAI 启发、构建在 llama.cpp 之上，一个可执行文件即可运行，无需安装，提供 Windows、Linux、macOS 现成下载。
除了本地文本生成，它还集成了图像/视频/语音/音乐生成（兼容模型）、MCP 工具调用与 Agent、内置 KoboldAI Lite WebUI，以及经典的 llama.cpp WebUI。可在 CPU 或 GPU 上运行，支持全部或部分层 offload。
1.1 核心信息一览
| 项目项 | 内容 |
|---|---|
| 项目名称 | KoboldCpp |
| 仓库地址 | github.com/LostRuins/koboldcpp |
| 项目定位 | 单文件 GGUF 本地模型运行器 + 内置 Web UI |
| 底层 | 基于 llama.cpp |
| 模型格式 | GGUF（模型权重需单独下载） |
| 运行形态 | 单文件可执行，无安装、无外部依赖 |
| Web UI 地址 | http://localhost:5001 |
| 官方下载 | Releases |
| 官网 | koboldcpp.net（注意 koboldcpp.com 是钓鱼站） |
1.2 适用场景
- 想在 Windows / Linux / macOS 上双击即用、不折腾环境地跑 GGUF 本地模型。
- 需要一个内置 Web UI、角色扮演与角色卡管理的本地前端。
- 想把本地模型作为 API 给 KoboldAI、OpenAI、Ollama 兼容客户端等应用调用。
1.3 能力边界（官方口径）
- 模型权重与软件分离：需自行下载 GGUF 文本模型，软件本身不附带模型。
- 独立 GPU 可选；显存需求由模型大小与上下文长度决定。
- 除 Windows/Linux/macOS 外，可在 Colab、Docker 运行，或自行编译到 Termux（Android）、树莓派等平台。
2 功能特性
- 本地文本生成：运行任意 GGUF 模型，支持 chat / adventure / instruct / story 模式；兼容视觉模型支持图像理解。
- 多模态生成：图像（SD1.5/SDXL/SD3/Flux 等）、视频（WAN 2.2 等）、语音识别（Whisper）、语音合成（Qwen3TTS、Kokoro 等）、音乐生成。
- 工具与 Agent：MCP server、tool calling、Web
搜索、基于 TextDB 的 RAG、内置 KoboldCpp
Agent（
--agent）。 - 写作与角色工具：内置 KoboldAI Lite WebUI，多主题、记忆、世界书、作者注、角色、场景、持久存档；可导入 Tavern 角色卡。
- 应用集成：兼容 KoboldAI、OpenAI、Ollama、A1111/Forge、ComfyUI、Whisper 转写、XTTS 等端点。
- 完全便携：单文件、CPU/GPU、全/部分 offload。
3 官方界面预览
本仓库以功能说明为主，实际界面以启动后浏览器访问
http://localhost:5001 的内置 Web UI 为准。
4 官方跳转链接汇总
| 类别 | 链接 | 说明 |
|---|---|---|
| 仓库主页 | https://github.com/LostRuins/koboldcpp | 源码与文档 |
| 最新发布 | releases/latest | 官方唯一可信二进制下载 |
| 官方网站 | https://koboldcpp.net | 官网（koboldcpp.com 为钓鱼站） |
| 示例模型 | 见 Release 页与启动器 Newbie Templates | 新手模板与示例模型 |
5 前置要求与服务器配置
5.1 软件前提
- 操作系统：Windows / Linux / macOS。
- 一个 GGUF 格式模型权重（从 Hugging Face 等来源单独下载）。
- GPU 可选：NVIDIA CUDA 或 Vulkan 均可；无独立 GPU 可跑 CPU。
5.2 硬件建议
| 项目 | 建议 |
|---|---|
| 内存/显存 | 由模型大小与上下文长度决定，按模型卡片预留 |
| 磁盘 | 可执行文件 + 模型权重（数 GB 起） |
| GPU | 可选，越大模型越推荐 GPU |
6 方式一：下载即用（推荐）
6.1 Windows
:: 一行下载并启动（官方示例）
cmd /c "curl -fLo koboldcpp.exe https://github.com/LostRuins/koboldcpp/releases/latest/download/koboldcpp.exe && koboldcpp.exe"- 不需要 NVIDIA CUDA 时可用更小的
koboldcpp-nocuda.exe；老旧 CPU/GPU 可用koboldcpp-oldpc.exe。 - 命令行直接加载模型：
koboldcpp.exe --model "C:\Models\model.gguf"6.2 Linux
# 1. 下载 x86-64 可执行文件
chmod +x koboldcpp-linux-x64
# 2. 启动
./koboldcpp-linux-x64
# 或直接指定模型
./koboldcpp-linux-x64 --model /path/to/model.gguf- 不需要 CUDA 用
koboldcpp-linux-x64-nocuda；老旧硬件试koboldcpp-linux-x64-oldpc。 - 查看完整参数：
./koboldcpp-linux-x64 --help。
7 方式二：首次图形界面启动
- 从 Releases 下载对应系统的可执行文件。
- 下载一个 GGUF 文本模型（不确定时用示例模型或启动器里的 Newbie Templates）。
- 打开 KoboldCpp，在 GGUF Text Model 字段选择模型。
- 按电脑配置选硬件设置（默认通常可用）。
- 点 Launch，等待模型加载。
- 浏览器打开
http://localhost:5001连接 Web UI。
8 配置项说明
| 配置 | 位置 | 说明 |
|---|---|---|
--model |
命令行 | 指定 GGUF 模型路径 |
| Web UI 端口 | 默认 5001 | 浏览器访问 http://localhost:5001 |
--agent |
命令行 | 启动内置 KoboldCpp Agent（或在启动器 Admin 页勾选） |
| 硬件 offload | 启动器界面 | 选择 GPU 层数与性能设置 |
| nocuda / oldpc 变体 | 发布资产 | 无 CUDA 需求 / 老旧硬件专用 |
9 常用运维命令
# Linux 启动并指定模型
./koboldcpp-linux-x64 --model /path/to/model.gguf
# 查看全部参数
./koboldcpp-linux-x64 --help
# Windows 启动器
koboldcpp.exe10 常见故障排查
- 下载到假站点：只从
github.com/LostRuins/koboldcpp/releases/latest与koboldcpp.net下载；koboldcpp.com是钓鱼站。 - 模型加载失败：确认模型是 GGUF 格式、路径正确；模型需单独下载，软件不附带。
- 内存不足：减小上下文长度或换更小量化的 GGUF 模型。
- 老旧硬件兼容问题：换
oldpc变体。 - 无 CUDA 需求：用
nocuda变体减小体积。
11 风险与合规说明
- 钓鱼站点：官方明确
koboldcpp.com为恶意仿冒，仅信任官方 Releases 与官网。 - 模型许可证：所选 GGUF 模型的版权与许可以模型作者为准，商用前需核对。
- 内容合规：生成内容需自行负责，不得用于违法用途。
- 非官方声明：本文基于官方仓库 README
整理，参数以最新 Release 与
--help为准。