KoboldCpp 是一款免费、开源的软件，用于在用户自己的电脑上运行 GGUF 大语言模型（LLM）。它受到 KoboldAI 启发，并基于 llama.cpp 构建，提供单个可执行文件，无需安装，官方为 Windows、Linux 和 macOS 提供可直接运行的下载版本。
用途
KoboldCpp 的核心用途是本地文本生成。用户可以运行任意 GGUF 语言模型，在聊天、冒险、指令或故事写作模式下生成文本。兼容的视觉模型还支持图像理解。此外，它还支持图像生成与编辑、视频生成、语音识别、语音生成、音乐生成，并内置智能体与多种工具能力。
主要能力
- 本地文本生成：运行 GGUF 语言模型，支持聊天、冒险、指令、故事写作等模式；兼容视觉模型可进行图像理解。
- 图像生成与编辑：支持 Stable Diffusion 1.5、SDXL、SD3、Flux、Qwen Image、Ideogram、Z-Image、Klein、Krea2 等。
- 视频生成：支持 WAN 2.2、LTX2.3、MiniMax H3 等。
- 语音识别：使用 Whisper 进行语音转文本，并支持 Gemma4 E2B 和 E4B 的多模态音频。
- 语音生成：使用 Qwen3TTS、Kokoro、OuteTTS、Parler、Dia 进行文本转语音。
- 音乐生成：支持 ACE Step 1.5 和 ACE Step XL。
- 工具与智能体：支持 MCP 服务器、工具调用、网络搜索、通过 TextDB 实现检索增强生成（RAG），以及内置的 KoboldCpp Agent，可用于编写和编辑代码、运行程序、安排任务。启动智能体可在启动器的 Admin 选项卡中选择 Launch KoboldCpp Agent，或在启动命令中添加 --agent。
- 写作与角色扮演工具：内置 KoboldAI Lite WebUI，包含多种界面主题、编辑工具、记忆、世界信息、作者注释、角色、场景和持久故事保存。可从文件或外部站点导入 Tavern 角色卡及其他支持格式。还包含经典的 llama.cpp WebUI。
- 应用集成：兼容 KoboldAI、OpenAI、Ollama、A1111/Forge、ComfyUI、Whisper 转录、XTTS 和 OpenAI 语音客户端等端点。
- 完全便携：Windows、Linux 或 macOS 的单机可执行文件，无需安装，无外部依赖。可在 CPU 或 GPU 上运行，支持完全或部分卸载。也可在 Colab、Docker 上运行，自编译后还支持其他平台（如通过 Termux 在 Android 上运行，以及 Raspberry Pi）。
使用方式
- 从最新 KoboldCpp 发布页面下载对应操作系统的版本。Windows 用户可下载 koboldcpp.exe 并双击打开启动器；若不需要 NVIDIA CUDA 支持，可使用更小的 koboldcpp-nocuda.exe；较旧的 CPU 或 GPU 可尝试 koboldcpp-oldpc.exe。Linux 用户下载 koboldcpp-linux-x64，使用 chmod +x 赋予可执行权限后从终端运行；macOS（Apple Silicon）用户下载 koboldcpp-mac-arm64，同样赋予可执行权限后运行。
- 下载 GGUF 文本模型。模型与软件分开提供，KoboldCpp 不包含模型文件。可在 huggingface.co 获取 GGUF 模型，也可在启动器的 Get Help 中选择 Newbie Templates 进行简易设置。
- 打开 KoboldCpp，在 GGUF Text Model 字段选择模型，选择适合电脑的硬件设置。默认设置通常可用。
- 点击 Launch 并等待模型加载完成，保持 KoboldCpp 运行。
- 在浏览器中访问 http://localhost:5001 连接 Web UI。
命令行使用示例：koboldcpp.exe --model "C:\Models\model.gguf"，更多信息可查看 koboldcpp.exe --help。
若没有本地模型，也可连接外部 AI 提供商，如 AI Horde、OpenAI Compatible、Anthropic、OpenRouter、Gemini、Grok、Mistral 等。使用 --nomodel 启动，或在启动器的 Loaded Files 选项卡中选择 Allow Launch Without Models。也可直接使用在线 KoboldAI Lite WebUI。
其他运行方式包括：Google Colab（官方 KoboldCpp Colab GPU Notebook）、RunPod（KoboldCpp RunPod 镜像或 SimplePod）、HuggingFace Space 公共演示。官方 Docker 镜像主要面向专家和云 GPU 租赁，内部使用 x86-64 Ubuntu 环境，需要 NVIDIA 或 AMD GPU。
适用场景
- 本地聊天、故事创作、角色扮演与写作辅助。
- 需要图像、视频、语音、音乐生成的多模态本地 AI 工作流。
- 通过兼容 API 将本地模型接入其他应用。
- 在无安装权限或需要便携运行的设备上使用。
- 使用内置智能体进行代码编写、程序运行和任务调度。
限制与注意事项
- KoboldCpp 不包含模型文件，需单独获取。
- 图像、语音、嵌入和音乐生成需要加载对应模型。
- 官方 Docker 镜像在部分 Windows 或 macOS 环境可能表现不佳，ARM 系统可能无法运行。
- 系统内存不足时可尝试更小模型或更短上下文；GPU 显存不足时可减少 GPU 层数、使用更小模型或更短上下文。
- 生成速度慢时，需检查是否选择了正确的 GPU 后端并卸载了层。
- 旧电脑启动崩溃可尝试 oldpc 版本或 --noavx2。
- 浏览器无法连接时，等待模型加载完成并检查终端打印的地址，默认是 localhost:5001。
- 模型无法加载时，检查终端错误、可用内存以及 KoboldCpp 版本是否支持该模型。
- 模型输出不连贯时，可能使用了不正确的聊天模板，可尝试使用 --jinja 或启用 GUI 中的 Jinja 开关。
- 官方提醒：koboldcpp.com 是恶意假冒网站，与本项目无关，应只信任官方 GitHub 发布页面 https://github.com/LostRuins/koboldcpp/releases/latest 的下载。
