Jan：本地运行开源大模型、兼容云端模型的隐私优先桌面 AI 聊天客户端｜部署与使用全指南
项目仓库： https://github.com/janhq/jan
开源协议：Apache 2.0（Copyright 2025 Menlo Research） ·
技术底座：Tauri（Rust 外壳）+ Web 前端 + llama.cpp 推理引擎 ·
交付形态：Windows / macOS / Linux 桌面安装包与安装商店分发 · 本地 OpenAI
兼容服务默认端口 1337 · 官方文档：jan.ai/docs
非官方声明：Jan 是 Menlo Research 维护的开源社区项目，与 OpenAI、Anthropic、Google、Meta、Mistral、Groq、MiniMax、Microsoft、Cohere 等模型厂商不存在隶属、授权或合作关系；文中出现的模型与服务名称仅用于说明兼容目标。API Key、订阅账号与模型服务条款由对应厂商约束，本地模型权重的版权与使用许可由各模型发布方规定，使用者须自行确认合规边界。
1 项目简介
Jan 是一款开源桌面 AI 聊天客户端，官方定位为 “Open-source ChatGPT replacement”：把开源大模型与常用云端模型整合到同一个易于使用的桌面产品中，让用户在本机即可下载并运行 Llama、Gemma、Qwen、GPT-oss 等开源大模型，同时可以切换到 OpenAI、Anthropic、Mistral、Groq、MiniMax 等云端服务。项目强调“完全控制权”与“隐私优先”：选择本地模型时，对话内容不出本机；同时内置一个 OpenAI 兼容的本地服务端口，供其他应用以标准接口调用本机模型。
1.1 核心信息一览
| 项目项 | 内容 |
|---|---|
| 项目名称 | Jan（桌面应用包名 jan-app，官方站点 jan.ai） |
| 仓库地址 | github.com/janhq/jan |
| 项目定位 | 隐私优先的开源桌面 AI 客户端：本地运行开源 LLM，也可接入云端模型服务 |
| 开源协议 | Apache 2.0，Copyright 2025 Menlo Research |
| 技术底座 | Tauri（Rust 桌面外壳）、Web 前端、llama.cpp 推理引擎、Scalar API 文档组件 |
| 交付形态 | Windows jan.exe、macOS
jan.dmg（universal）、Linux jan.deb、Linux
AppImage、Microsoft Store、Flathub |
| 部署方式 | 官方安装包下载安装；源码本地构建（make dev / Yarn +
Tauri） |
| 本地兼容服务 | OpenAI 兼容本地服务，默认地址 localhost:1337 |
| 模型来源 | 本地模型取自 HuggingFace；云端接入 OpenAI、Anthropic、Mistral、Groq、MiniMax 等提供者 |
| 官方文档 | jan.ai/docs · API 参考 · 更新日志 |
1.2 适用场景
- 希望在自己电脑上离线跑开源大模型，对话与文档内容不经过第三方云端的个人用户与隐私敏感场景。
- 在同一客户端内混用本地模型与云端模型：简单任务走本机模型，复杂任务切换到 GPT、Claude 等云端服务，按任务选择成本与能力。
- 为写作、编程、个人理财、学习等不同任务创建自定义助手（Custom Assistants），各自携带独立的系统提示词、模型与参数配置。
- 需要把本机 Jan 中的模型当作 OpenAI 兼容后端，供其他应用或脚本通过
localhost:1337调用。 - 通过 MCP（Model Context Protocol）为客户端接入外部工具与数据源，扩展 Agent 化能力。
- 开发者基于 Tauri + Web 前端 + llama.cpp 的仓库结构二次开发桌面 AI 应用。
1.3 能力边界（官方口径）
- 官方 README 自述目标为 “bringing the best of open-source AI in an easy-to-use product”：下载并运行 LLM，享有完全控制权与隐私；本地模型在本机运行，云端模型则按对应提供者的接口与条款发送请求。
- 本地模型可从 HuggingFace 下载 Llama、Gemma、Qwen、GPT-oss 等模型；模型是否支持工具调用、上下文长度与推理速度取决于所选模型本身，项目不提供模型权重，也不保证每个模型都具备同等能力。
- 云端集成覆盖 OpenAI（GPT 模型）、Anthropic（Claude 模型）、Mistral、Groq、MiniMax 等提供者；具体可用模型列表、计费与限流由对应平台决定，以应用内与官方文档最新说明为准。
- Jan 不自带大模型权重，也不提供模型训练、微调与模型托管服务；MCP 扩展连接的外部工具各自承担其数据处理与安全责任。
2 功能特性
2.1 本地大模型下载与运行
- 可在应用内浏览并从 HuggingFace 下载开源大模型（如 Llama、Gemma、Qwen、GPT-oss 等），下载后在本机完成推理，无需持续联网调用云端。
- 内置 llama.cpp 推理引擎，并按平台编译不同引擎变体（CPU、Vulkan、Metal、CUDA 12 / 13、HIP / ROCm），发挥本机 CPU 与 GPU 加速能力。
2.2 云端模型接入
- 在同一界面接入 OpenAI、Anthropic、Mistral、Groq、MiniMax 等云端服务，填入对应提供者的 API Key 后即可在模型列表中切换使用。
- 云端与本地模型在助手配置中可分别指定，切换模型不影响历史会话记录。
2.3 自定义助手
- 可为不同任务创建专门的 AI 助手（Custom Assistants），分别配置模型、系统提示词、推理参数与工具，形成可复用的任务面板。
- 会话按助手归类管理，历史对话在本机持久保存。
2.4 OpenAI 兼容本地服务
- 应用内置 OpenAI 兼容的本地服务，监听
localhost:1337；其他应用、脚本或兼容 OpenAI 接口的客户端可将其作为本地模型后端接入。 - 接口兼容范围与可用端点以应用内 API 参考（jan.ai/api-reference）为准。
2.5 MCP 模型上下文协议
- 支持 MCP 集成，为客户端接入外部工具、文件系统与数据源，实现 Agent 化调用能力；MCP 服务器配置方式与可用扩展以应用内设置及官方文档最新说明为准。
2.6 隐私优先
- 官方口径为 “Everything runs locally when you want it to”：选择本地模型时全部推理在本机完成；模型文件、助手配置与对话历史保存在本机用户目录下，不上传到 Jan 的云端账号体系。
3 官方界面预览
3.1 品牌横幅
下图为仓库 README 顶部的官方品牌横幅，展示 Jan 标识与吉祥物形象；完整界面细节以安装版本为准。
3.2 桌面客户端面板
官方主横幅（图1）右侧展示了桌面客户端的典型面板：左侧为历史会话与助手列表，中间为对话区（含代码块复制、重新生成、删除等操作），右侧为模型与推理设置面板，可切换模型并调节 Max token、Temperature、Frequency Penalty、Presence Penalty、Top P、Stream、Stop Words 等参数，底部状态栏显示实时生成速度与系统监控信息。更多界面截图与操作说明见官方文档 jan.ai/docs/desktop。
4 官方跳转链接汇总
| 类别 | 链接 | 说明 |
|---|---|---|
| 仓库主页 | https://github.com/janhq/jan | 桌面应用、核心包与扩展源码 |
| 官方文档 | https://jan.ai/docs | 桌面端入门、模型管理与故障排除手册 |
| 桌面安装指南 | jan.ai/docs/desktop | 各平台安装与配置说明 |
| macOS 兼容说明 | jan.ai/docs/desktop/mac | macOS 版本与硬件兼容细节 |
| 故障排除文档 | jan.ai/docs/desktop/troubleshooting | 官方排障手册 |
| API 参考 | jan.ai/api-reference | 本地 OpenAI 兼容接口技术说明 |
| 更新日志 | jan.ai/changelog | 每个版本变更与修复记录 |
| Releases 发布页 | github.com/janhq/jan/releases | 官方安装包与版本归档 |
| Microsoft Store | apps.microsoft.com/detail/xpdcnfn5cpzlqb | Windows 商店安装入口 |
| Flathub | flathub.org/apps/ai.jan.Jan | Linux Flathub 安装入口 |
| Issues 反馈 | github.com/janhq/jan/issues | Bug 跟踪与问题反馈 |
| Discord 社区 | discord.gg/FTk2MvZwJH | 使用交流，#🆘|jan-help 求助频道 |
| 商务联系 | hello@jan.ai | 官方商务合作邮箱（见 README） |
5 前置要求与环境配置
5.1 软件前提
- 操作系统：macOS 13.6 及以上；Windows 10 及以上；Linux 主流发行版均可运行，GPU 加速随引擎变体支持。
- 模型来源网络：首次下载本地模型需能访问 HuggingFace；使用云端模型需能访问对应提供者接口并准备好 API Key。
- GPU 驱动（可选）：Windows 下支持 NVIDIA / AMD / Intel Arc GPU 加速；Linux 与 macOS 按对应硬件启用加速，详细兼容矩阵以官方安装指南为准。
- 源码构建额外前提：Node.js ≥ 20.0.0、Yarn ≥
4.5.3、Make ≥ 3.81、Rust（Tauri 构建需要）；macOS Apple Silicon 需通过
xcodebuild -downloadComponent MetalToolchain下载 MetalToolchain。
5.2 硬件与系统建议
| 项目 | 官方口径 |
|---|---|
| macOS | 13.6+；3B 模型建议 8GB 内存，7B 模型建议 16GB 内存，13B 模型建议 32GB 内存 |
| Windows | Windows 10+，支持 NVIDIA / AMD / Intel Arc GPU 加速 |
| Linux | 大多数发行版可用，支持 GPU 加速；ARM64 安装见官方 Issue 指南 |
| 磁盘空间 | 按所选模型权重大小预留磁盘（GGUF 等量化模型每个数 GB 起步，多模型并存时预留更多空间） |
| 网络 | 本地模型下载阶段需要外网；纯本地推理阶段可离线使用 |
5.3 端口与目录
| 项 | 默认值 | 用途 |
|---|---|---|
| 本地兼容服务端口 | 1337 |
OpenAI 兼容本地服务，其他应用通过 http://localhost:1337
调用本机模型 |
| 模型与配置目录 | 本机用户目录下由应用统一管理（模型文件、助手配置、对话历史） | 具体路径与导出入口以应用内设置与官方文档为准 |
| 引擎变体 | 构建期由 JAN_ENGINE_VARIANT 指定 |
取值
cpu、vulkan、metal、cuda12、cuda13、hip
/ rocm，可用 - 连接组合 |
说明：Jan 是桌面端应用，官方未提供服务器端 Docker / Compose 镜像；除本页列出的本地
1337服务外，不要为服务端部署伪造 Compose 文件或额外端口。
6 方式一：官方安装包一键安装（推荐日常使用）
官方不提供 Docker 镜像，日常使用直接下载对应平台安装包即可。所有安装包均可从 jan.ai 或 GitHub Releases 获取，下表链接为 README 中的官方直链。
6.1 下载安装包
| 平台 | 官方下载链接 | 安装包 |
|---|---|---|
| Windows | app.jan.ai/download/latest/win-x64 | jan.exe |
| macOS | app.jan.ai/download/latest/mac-universal | jan.dmg（universal 包） |
| Linux（deb） | app.jan.ai/download/latest/linux-amd64-deb | jan.deb |
| Linux（AppImage） | app.jan.ai/download/latest/linux-amd64-appimage | jan.AppImage |
| Linux ARM64 | GitHub Issue #4543 评论区指南 | 社区/官方整理的构建与安装说明 |
商店渠道：
- Microsoft Store：apps.microsoft.com/detail/xpdcnfn5cpzlqb
- Flathub：flathub.org/apps/ai.jan.Jan
6.2 安装与首次启动
- 按操作系统下载对应安装包并完成安装：Windows 运行
jan.exe；macOS 打开jan.dmg将应用拖入应用程序文件夹；Linux 可通过dpkg安装 deb 包，或直接赋予执行权限运行 AppImage。 - 首次启动后在模型面板浏览本地模型列表，选择需要的模型下载；下载完成后在对话界面选择该模型开始聊天。
- 需要使用云端模型时，在模型 / 提供者设置中选择 OpenAI、Anthropic、Mistral、Groq、MiniMax 等提供者并填入对应 API Key；Key 仅保存在本机配置中。
- 需要供其他应用调用本机模型时，确认本地 OpenAI 兼容服务已在
localhost:1337监听，按应用内 API 参考组织请求。
6.3 系统状态与更新
- 对话面板底部状态栏可查看当前模型与生成速度、系统监控信息；新版本可通过应用内更新提示、商店更新或重新下载最新安装包完成，历史会话与模型文件在升级后保留。
- 详细安装兼容说明见官方 桌面安装文档 与 mac 说明。
7 方式二：源码本地构建（开发者）
7.1 构建前提
| 依赖 | 版本 / 说明 |
|---|---|
| Node.js | ≥ 20.0.0 |
| Yarn | ≥ 4.5.3（仓库通过 corepack 锁定版本） |
| Make | ≥ 3.81 |
| Rust | 用于 Tauri 桌面外壳构建 |
| MetalToolchain | 仅限 macOS Apple Silicon：执行
xcodebuild -downloadComponent MetalToolchain 下载 |
7.2 通过 Make 一键开发
git clone https://github.com/janhq/jan
cd jan
# 完整开发环境准备、依赖安装、核心组件构建并启动应用
make devREADME 提供的 Make 目标：
| 目标 | 作用 |
|---|---|
make dev |
完整开发环境设置、安装依赖、构建核心组件并启动应用 |
make build |
生产版本构建 |
make test |
运行测试与 lint 检查 |
make clean |
清理全部生成产物，从零开始 |
7.3 手动构建命令
yarn install
yarn build:tauri:plugin:api
yarn build:core
yarn build:extensions
yarn dev仓库根目录 package.json
中的常用脚本（供开发者参考，以仓库最新脚本为准）：
# 启动 Tauri 开发模式（含图标构建与资源拷贝）
yarn dev
# 生产构建
yarn build
# 分项目测试：核心包 / Web 前端 / 扩展
yarn test:core
yarn test:web
yarn test:ext
# 仅启动 Web 前端（不启动 Tauri 外壳）
yarn dev:web7.4 Windows 构建注意事项
make dev需在 Git Bash（随 Git for Windows 安装）中执行；Make 通过sh分发配方，普通cmd.exe无法运行。- 不需要“VS 2022 Native Tools 命令提示符”；内置 llama.cpp 引擎使用
Ninja +
clang-cl构建，clang-cl会自行定位 MSVC 工具链与 Windows SDK。必须安装并加入PATH：Visual Studio 2022 Build Tools（MSVC x64 工作负载 + Windows SDK）、LLVM（提供clang-cl）、Ninja、CMake；仅JAN_ENGINE_VARIANT=cuda12/cuda13构建需要 CUDA Toolkit。
7.5 引擎变体选择
# 示例：CUDA 13 变体的开发构建
make dev JAN_ENGINE_VARIANT=cuda13JAN_ENGINE_VARIANT
可选令牌：cpu、vulkan、metal、cuda12、cuda13、hip
/ rocm，需要组合时用 - 连接。
8 配置项说明
8.1 模型推理参数（应用内模型面板）
官方客户端模型面板提供的推理调节项如下（取值范围与默认值随模型与版本变化，以界面标注为准）：
| 参数 | 说明 |
|---|---|
| Model | 选择当前会话使用的本地模型或云端模型 |
| Max token | 单次生成的最大 token 上限 |
| Temperature | 采样温度，值越高输出越发散，值越低越确定 |
| Frequency Penalty | 频率惩罚，抑制模型重复使用相同词句 |
| Presence Penalty | 存在惩罚，鼓励模型引入新话题 |
| Top P | 核采样阈值，限制候选 token 概率累积范围 |
| Stream | 是否开启流式输出（逐字返回） |
| Stop Words | 自定义停止词，命中后停止生成 |
8.2 模型提供者配置
| 类别 | 说明 |
|---|---|
| 本地模型 | 从 HuggingFace 下载 Llama、Gemma、Qwen、GPT-oss 等模型到本机后运行；模型版权与许可由各模型发布方规定 |
| OpenAI | 接入 GPT 系列云端模型，在提供者配置中填写对应 API Key 与模型名 |
| Anthropic | 接入 Claude 系列云端模型 |
| Mistral | 接入 Mistral 提供的云端模型服务 |
| Groq | 接入 Groq 云端推理服务 |
| MiniMax | 接入 MiniMax 云端模型服务 |
| 其他兼容端点 | 如应用内支持任意 OpenAI 兼容接口，按界面提示填写 Base URL、API Key 与模型名；可用列表以官方文档为准 |
8.3 本地 OpenAI 兼容服务
- 本地服务默认监听
localhost:1337，对外提供 OpenAI 风格接口；其他应用可将 Base URL 指向该地址调用本机模型。 - 接口字段、模型名映射与鉴权方式以官方 API 参考 与应用内说明为准；该服务默认只绑定本机回环地址，不要在未做访问控制的情况下通过局域网 / 公网直接暴露。
8.4 MCP 配置
- 在应用 MCP 设置中添加 Model Context Protocol 服务器，为对话提供文件系统、数据库、Web 检索等工具能力；配置格式与传输方式（stdio / HTTP / SSE）以应用内最新支持情况为准。
- 第三方 MCP 服务器可能读取本机文件与网络资源，添加前应确认其来源与权限边界。
8.5 构建期环境变量（源码构建）
| 变量 | 用途 |
|---|---|
JAN_ENGINE_VARIANT |
选择引擎变体：cpu、vulkan、metal、cuda12、cuda13、hip
/ rocm，组合用 - 连接 |
JAN_ENGINE_BUILD_DIR |
Windows 构建时指定短路径的 llama.cpp 构建目录，规避
MAX_PATH 路径长度限制 |
9 常用运维命令
9.1 安装包版本日常操作
桌面安装包版本以应用界面操作为主，常见维护动作如下：
- 查看 / 切换模型：在模型面板选择已下载模型或下载新模型；模型文件占用磁盘较大，可在模型管理中删除不再使用的模型释放空间。
- 更新版本：通过应用内更新提示、Microsoft Store / Flathub 更新，或重新下载最新官方安装包覆盖安装。
- 查看日志：遇到问题时先从应用内帮助 / 设置中导出或复制错误日志，并记录操作系统版本、硬件配置与所用模型，再对照官方排障文档排查。
9.2 源码构建常用命令
# 开发环境启动
make dev
# 生产构建
make build
# 测试与 lint
make test
# 清理构建产物
make clean
# 仅测试核心包 / Web 前端 / 扩展
yarn test:core
yarn test:web
yarn test:ext9.3 本地服务与模型管理核对
- 确认本地兼容服务是否在
1337端口监听：在其他应用中以http://localhost:1337作为 Base URL 发起一次模型列表 / 对话请求，对照应用内模型名。 - 模型下载中断后重新在模型面板触发下载；磁盘空间不足时先清理旧模型与下载缓存。
10 常见故障排查
10.1 应用启动失败或安装被拦截
- 确认操作系统满足最低版本要求（macOS 13.6+、Windows 10+）；Linux 优先使用官方 deb / AppImage，Flathub 渠道依赖 Flatpak 运行环境。
- 安全软件拦截安装包时，从 GitHub Releases 重新核对安装包完整性；macOS 首次打开被 Gatekeeper 拦截时，按系统提示在隐私与安全性设置中确认打开。
10.2 模型下载失败或速度慢
- 检查网络是否能访问 HuggingFace；下载中断后重新触发下载，避免手动复制半截权重文件到模型目录。
- 预留足够磁盘空间；多个大模型并存时按任务保留常用量化版本即可。
10.3 本地模型运行缓慢或内存不足
- 按官方内存口径选择模型规模：3B 约 8GB 内存、7B 约 16GB、13B 约 32GB；内存不足时换用量化级别更高的小模型。
- 有 GPU 时确认引擎变体与驱动匹配（Windows 支持 NVIDIA / AMD / Intel Arc；macOS 使用 Metal；Linux 可选用对应 GPU 变体）；纯 CPU 模式生成速度较慢属于正常现象。
10.4 云端模型连接失败
- 核对 API Key 是否填写正确、是否过期或超出额度；公司网络代理下确认接口域名可达。
- 切换提供者后重新选择模型；如返回模型不存在或无权限错误，以对应平台控制台的模型列表为准。
10.5 本地兼容服务其他应用调不通
- 确认应用已启动且本地服务在
localhost:1337监听；请求 Base URL 与模型名按 API 参考填写。 - 不要把仅回环监听的服务直接暴露到公网；局域网调用前先确认访问控制与鉴权配置。
10.6 Windows 源码构建报
nvcc 路径错误
构建 tauri-plugin-llamacpp 时若出现 “nvcc fatal : Could
not open output file ... .cu.obj.d”，表示构建路径超过 Windows 260 字符
MAX_PATH 限制，而 nvcc
不遵守长路径开关；构建脚本已尝试自动把 llama.cpp 构建目录迁移到
%LOCALAPPDATA%\jan-engine 的短路径。若仍报错，设置
JAN_ENGINE_BUILD_DIR 为短路径（例如
C:\jb），或将仓库克隆到更靠近盘符根目录的位置。
10.7 官方求助流程
按 README 建议的顺序处理：先查阅官方 故障排除文档；仍无法解决时复制错误日志与系统规格信息，到 Discord `#🆘|jan-help` 频道求助；可复现的 Bug 提交到 GitHub Issues，附上操作系统、版本号、模型名与复现步骤，不要在公开 Issue 中贴出 API Key 等凭据。
11 风险与合规说明
以下条款整理自官方 README、Apache 2.0 许可证与官方文档口径；如与官方原文不一致，以仓库
LICENSE、README 与 jan.ai/docs 最新说明为准。
11.1 开源协议
Jan 开源代码采用 Apache 2.0 许可证，Copyright 2025 Menlo Research，允许自由使用、修改与再分发，修改文件需保留版权声明与许可证副本；LICENSE 同时要求在面向用户的文档与材料中酌情标注归属。内置的 llama.cpp、Tauri、Scalar 等第三方组件各自遵循其对应许可证。
11.2 模型权重与云端服务条款
- Jan 项目本身不提供模型权重；从 HuggingFace 下载的 Llama、Gemma、Qwen、GPT-oss 等模型遵循各自发布方的模型许可证，商用前须核对模型许可条款。
- OpenAI、Anthropic、Mistral、Groq、MiniMax 等云端服务归对应厂商所有，受其服务条款、隐私政策与计费规则约束；API Key 由使用者自行保管，泄露后应立即在对应平台轮换。
11.3 数据隐私
- 本地模型推理时对话内容不出本机；切换到云端模型时，提示词、文件内容与上下文会按所选服务发送到对应平台。敏感文档与商业机密优先使用本地模型，不要粘贴到不受信任的第三方会话中。
- 对话历史、模型文件与助手配置保存在本机，卸载应用前可按需备份；重装系统或清理目录前先确认已导出需要保留的内容。
11.4 工具调用与二次开发风险
- MCP 扩展与本地兼容服务可读取本机资源并发起网络请求，添加第三方服务器前应审核其来源与权限；自动或 Agent 化操作前先在非关键目录内测试。
- 项目按现状（AS-IS）提供，不保证模型输出正确、不保证与所有硬件 / 平台持续兼容；使用者自行承担模型选择、数据泄露、服务中断与业务损失风险。如认为仓库内特定文件侵犯合法权益，请通过 GitHub Issues 提交说明。