Kun 是一个本地优先的 AI Agent 工作台

Kun 是一个本地优先的 AI Agent 工作台，支持桌面 GUI 和终端 TUI 两种使用方式，并且两者共享同一个本地运行时。

这份教程涵盖了从零开始的图形化安装和面向开发者的源码编译两种主要部署路径。

📥 路径一：下载预构建安装包（推荐）

这是最快捷、最推荐的部署方式，适合大多数用户。Kun 提供了跨平台的开箱即用安装包。

1. 下载安装包

从项目的 GitHub Releases 页面下载对应你操作系统的版本：

macOS：下载 .dmg 或 .zip 文件（根据芯片选择 Apple Silicon 或 Intel 版本）。
Windows：下载 .exe 安装程序。
Linux：下载 .AppImage 或 .deb 包（项目同时提供 x64 和 ARM64 架构的安装包）。

2. 安装与首次启动

运行下载的安装包，按照提示完成安装，过程与安装其他桌面软件无异。
首次启动 Kun 时，会进入一个引导设置界面：
- 选择语言：根据偏好选择界面语言。
- 配置模型提供商 (Provider)：这是最关键的一步。Kun 本身不提供模型，你需要配置至少一个模型服务的 API 密钥。
  - 它预设支持 DeepSeek、OpenAI、Claude、Gemini、Ollama 等众多生态。
  - 你需要提前在对应模型平台（如 DeepSeek、OpenAI）注册账号并获取 API Key，然后在设置界面填入。
  - 如果你使用本地模型（如通过 Ollama），也需要在此处配置本地服务的地址。
- 选择默认工作目录：建议专门创建一个文件夹（如 ~/kun-workspace）作为 Kun 的工作区。

3. 开始你的第一个任务

配置完成后，你就可以开始使用了：

在主界面创建一个新的工作区或打开一个本地项目文件夹。
在聊天框中清晰地描述你的目标（例如：“帮我创建一个简单的 React 组件”或“总结这篇文档”）。
Kun 的 Agent 会开始工作，你可以实时观察它的计划、工具调用和文件修改过程。

💻 路径二：从源码运行（开发者专用）

如果你是开发者，希望进行二次开发、贡献代码或体验最新特性，可以通过源码部署。

1. 环境准备

Node.js：版本要求 22.19 或更高。
npm：随 Node.js 安装。
Git：用于克隆仓库。
模型服务凭据：同路径一，至少准备一个可用的模型 API Key。

2. 克隆并安装依赖

打开终端，执行以下命令：

# 克隆仓库
git clone https://github.com/KunAgent/Kun.git
cd Kun

# 安装项目依赖。在中国大陆访问速度慢时，可使用 npm 镜像源[citation:2][citation:3]
npm ci --registry=https://registry.npmmirror.com

npm ci 命令会依据 package-lock.json 安装精确版本的依赖，确保构建的一致性。

3. 启动开发模式

启动桌面 GUI 开发环境：
1
npm run dev
这个命令会构建 Kun 运行时并启动 Electron 桌面应用，支持热加载 (HMR)。
启动终端 TUI 模式：
1
npm run dev:tui
这会在终端中启动 Kun 的命令行界面，适合习惯键盘操作的开发者。

4. 生产构建与打包

如果你想自行构建生产版本的应用安装包，可以使用以下命令：

npm run build：执行生产环境的构建。
npm run dist:mac：构建 macOS 的 .dmg 和 .zip 包。
npm run dist:win：构建 Windows 的 NSIS 安装程序。
npm run dist:linux：构建 Linux 的 AppImage 包。

⚙️ 高级配置与要点

配置文件位置：Kun 的运行时高级配置文件默认在 ~/.kun/data/config.json。桌面应用的设置文件（kun-settings.json）则位于各系统的标准用户数据目录：
- macOS: ~/Library/Application Support/Kun/
- Windows: %APPDATA%/Kun/
- Linux: ~/.config/Kun/
  你可以通过编辑这些 JSON 文件来精细控制模型参数、压缩策略、MCP 服务器等高级功能。
MCP 服务器集成：Kun 支持配置 MCP (Model Context Protocol) 服务器。你可以在配置文件中启用 capabilities.mcp，并设置 trustedWorkspaceRoots 和工作区级的 MCP 服务器，以扩展 Agent 的能力。
数据与隐私：Kun 是“本地优先”的。会话、日志、偏好设置等数据默认保存在你的本地机器上。选择云端模型时，提示和上下文会发送给对应的模型提供商，请在使用前确认该服务的数据政策。