Jan 0.8.7 配置参数详解

目标：系统梳理 Jan 0.8.7 的全部配置入口与参数——应用级设置、llama.cpp 本地引擎的 42 项参数、助手与模型对话参数、MCP 服务器配置，以及终端代理 Jan Agent 的全局/项目两级配置。文中所有默认值均在 Ubuntu 22.04 全新安装后直接读取配置文件取得，未做任何人工改动，可直接作为基线对照。

一、环境信息

• 操作系统：Ubuntu 22.04（x86_64，jammy）
• 软件版本：Jan Desktop 0.8.7（deb 安装）、Jan Agent 0.8.7-66（agent-nightly 通道，官方脚本安装）
• 配置基线采集时间：2026-10-22（全新安装、首次启动初始化完成后读取，未修改任何参数）
• 测试机硬件（应用自动检测并记录）：Intel Core i7-14700KF（12 核）、32050MB 内存、无独立显卡——因此下文引擎参数均为 CPU 形态下的默认值
• 数据目录：~/.local/share/Jan/（桌面应用）；~/.jan/（终端代理）

二、前置条件

• 已按本专栏《Ubuntu 22.04 安装 Jan 0.8.7 指南》完成 Jan Desktop 安装，并至少启动过一次应用（首次启动会生成全部默认配置文件）；
• 若需阅读终端代理部分，需已通过官方脚本安装 Jan Agent（见本专栏《Jan 0.8.7 常用 CLI 命令与工具详解》一篇的安装章节）；
• 熟悉 JSON 与 TOML 的基本语法即可，全部配置文件均为纯文本。

确认配置文件已生成：

find ~/.local/share/Jan -maxdepth 3 -type f | sort

实测输出（全新安装、初始化完成后）：

/root/.local/share/Jan/data/assistants/jan/assistant.json
/root/.local/share/Jan/data/db/...（会话与消息数据库文件，随使用增长）
/root/.local/share/Jan/data/logs/app.log
/root/.local/share/Jan/data/mcp_config.json
/root/.local/share/Jan/data/settings.json
/root/.local/share/Jan/data/store.json
/root/.local/share/Jan/settings.json

⚠️ 注意：直接编辑配置文件前先完全退出应用（托盘图标右键 Quit）。Jan 在退出时会把界面上的设置写回文件，应用运行期间手工编辑会被覆盖。

三、配置体系总览与查看修改方式

Jan 0.8.7 的配置分两条产品线、共四个层次：

查看与修改的三种方式：

1. 图形界面：Settings 面板（General/Hardware/Local AI Engine 等分区）与模型齿轮图标（Model Settings）。界面修改实时写回对应文件；
2. 直接读文件：所有配置均为 JSON/TOML 纯文本，例如：

cat ~/.local/share/Jan/settings.json

实测输出：

{"data_folder":"/root/.local/share/Jan/data"}

3. 终端代理专用命令：jan config path（显示配置路径）、jan config list（JSON 形式列出已配置 Provider）、jan config set（写入凭据，详见第八章）。

四、应用级配置参数

4.1 数据目录指针：~/.local/share/Jan/settings.json

顶层 settings.json 只有一个键：

4.2 数据区版本标记：data/store.json

{"version":"0.8.7","mcp_version":5}

• version：数据区最后一次被哪个桌面版本写入，升级后由应用自动迁移；
• mcp_version：MCP 配置的 schema 版本（当前为 5，首次启动日志会出现 Migrating MCP schema version 1..5）。

4.3 应用设置键值表：data/settings.json

该文件是所有界面设置的持久化键值表。实测全新安装后包含以下 11 个顶层键：

日常调整建议走界面（Settings > Appearance 改主题、General 改语言），避免手工改键值表造成 JSON 结构损坏。

4.4 Provider 注册表：model-provider 键

model-provider 是一个较大的 JSON 状态块，包含三部分：

• state.providers[]：每个可用 Provider 一个条目（实测含 llamacpp、openai、azure、anthropic、openrouter、mistral、groq、xai、gemini、minimax、huggingface、nvidia 共 12 个），每个条目带 base_url（实测例如 openai 为 https://api.openai.com/v1、anthropic 为 https://api.anthropic.com/v1）、settings[]（该 Provider 的界面设置项及当前值）、models[]（内置模型清单）；
• state.selectedProvider：实测默认 "llamacpp"（本地引擎）；
• state.selectedModel：实测默认 null（未选择模型）。

API Key 在界面中填写后保存进系统钥匙串（keyring）；无桌面钥匙串环境（如纯文本会话）应用自动降级为加密文件存储，并在日志中提示 Keyring unavailable ... using encrypted file fallback。

五、llama.cpp 本地引擎参数详解

引擎参数的修改入口：Settings > Local AI Engine（llamacpp Provider 的设置页），持久化在 data/llamacpp/settings.json（数组结构，每项含 key/title/description/controllerType/controllerProps）。下表为实测默认值全集（42 项，按文件顺序）：

5.1 路由预设：data/llamacpp/router.preset.ini

引擎路由器的启动预设，实测内容：

[*]
fit = off
ctx-size = 8192
slot-save-path = /root/.local/share/Jan/data/llamacpp/thread-cache

• fit = off：与引擎参数 fit=false 对应；
• ctx-size = 8192：路由器默认上下文 8192 token；
• slot-save-path：会话 KV cache 的落盘目录（配合 persist_thread_cache）。

六、助手与模型对话参数

6.1 默认助手：data/assistants/jan/assistant.json

首次启动生成唯一内置助手 jan，实测关键字段：

修改入口：界面左侧助手面板编辑，或直接编辑该 JSON（修改前退出应用）。

6.2 模型级参数（Model Settings）

对话界面点击模型旁的齿轮图标打开，作用于当前模型。官方文档给出的参数全集（查询日期 2026-10-22）：

Reasoning Mode（仅 llama.cpp 本地模型）：对支持扩展思考的模型（如 DeepSeek-R1、QwQ），输入框工具栏出现大脑图标，可设 Auto（模型自行决定）/On（总是先推理）/Off（直接回答），设置按模型持久化。

Mirostat 采样（仅本地模型）：Mirostat Mode（Off/V1/V2，V2 更稳）、Mirostat Learning Rate（0.05 稳定 ~ 0.2 激进）、Mirostat Target Entropy（越高越多变）。

输出约束（仅本地模型）：Grammar File（GBNF 语法文件路径，强制输出匹配语法）与 JSON Schema File（JSON Schema 文件路径，强制输出合法 JSON），可用于结构化抽取场景。

七、MCP 配置参数：data/mcp_config.json

MCP（Model Context Protocol）服务器配置持久化在 data/mcp_config.json，界面入口 Settings > MCP Servers；桌面端与终端代理共用此文件。实测全新安装后内置 6 个服务器（全部默认 active: false，即未启用）：

mcpSettings 全局键（实测默认值）：

八、Jan Agent（终端代理）配置参数

8.1 全局配置：~/.jan/config.toml

查看路径与当前内容：

jan config path
jan config list

实测输出（未配置任何凭据时）：

/root/.jan/config.toml

{
  "config_path": "/root/.jan/config.toml",
  "providers": []
}

写入凭据（--provider 必填；演示密钥仅用于展示格式）：

jan config set --provider openai --api-key sk-demo-q1w2e3r4

实测输出：

Updated provider 'openai' in /root/.jan/config.toml

写入后的文件内容：

[providers.openai]
api_key = "sk-demo-q1w2e3r4"

jan config set 支持的完整参数（官方文档，查询日期 2026-10-22）：

删除凭据用 jan config unset --provider openai。凭据删除后 jan config list 中该 Provider 的 has_api_key 变回 false。

8.2 项目配置：~/.jan/projects/<slug>/agent.toml

在项目目录内首次运行 jan（或 jan cli agent run）时自动生成项目配置，目录名为 项目名-8位哈希（实测 demo 项目生成 demo-2d64be35）：

find ~/.jan -type f | sort

实测输出：

/root/.jan/cli_telemetry.json
/root/.jan/config.toml
/root/.jan/projects/demo-2d64be35/agent.toml
/root/.jan/projects/demo-2d64be35/project.json

项目解析结果（含全部生效默认值）可一键导出：

jan cli agent status --project /root/demo

实测输出（节选，关键字段）：

{
  "project": "/root/demo",
  "data_folder": "/root/.local/share/Jan/data",
  "model": null,
  "max_session_tokens": 128000,
  "max_session_tokens_source": "default",
  "max_budget_usd": null,
  "tools": {
    "default": "read-only",
    "allow": [],
    "deny": [],
    "allow_write": [],
    "allow_network": null,
    "allow_home_read": null,
    "sandbox": null
  },
  "sandbox": { "enabled": false, "backend": "none" },
  "hooks": [],
  "plugin_tools": []
}

由此得到的默认行为基线：会话 token 上限 128000（默认来源）、工具权限默认 read-only（只读，写文件与执行命令需放行）、沙箱未启用、预算上限未设置、无 hooks。这些值都可通过编辑 agent.toml 的 [agent]、[tools]、[sandbox] 等小节调整。

8.3 模型解析顺序（重要）

未指定模型时执行 jan cli agent run 的实测报错：

Error: no model specified: run `jan login` to sign in to Tokamak, or pass --model, set [agent].model in agent.toml, set default_model in ~/.jan/config.toml, or select a model in the desktop app

即模型按以下优先级解析：命令行 --model > 项目 agent.toml 的 [agent].model > 全局 ~/.jan/config.toml 的 default_model > 桌面应用中选择的模型 > jan login 登录 Tokamak 后的默认。排障时用 jan cli agent status 看 "model" 字段是否为 null。

8.4 相关环境变量

九、推荐配置模板

9.1 纯 CPU 服务器（无独立显卡）

Settings > Local AI Engine 中调整：threads 保持 -1（用满逻辑核）、flash_attn 设为 off（无 GPU 时 auto 无收益）、cont_batching 保持 true、ctx_shift 设为 true（长对话不中断）、cache_type_k/cache_type_v 改 q8_0（KV cache 减半，质量损失很小）、models_max 保持 1。

9.2 大显存跑 MoE 模型

models_max 按显存设 1–2、n_cpu_moe 适当调大把专家权重留在内存、device 指定 CUDA0、split_mode 保持 layer、flash_attn 设 on、cache_ram 视并发调大。

9.3 长对话多会话场景

persist_thread_cache 保持 true、thread_cache_size 按磁盘余量调大（长会话单个可达数百 MiB）、ctx_checkpoints 保持 32、checkpoint_min_step 保持 8192。

9.4 Jan Agent 只读助手（安全优先）

项目 agent.toml 保持 tools.default = "read-only" 默认不动，[sandbox] 段按官方文档启用系统沙箱；需要写权限时只在 [tools] 的 allow_write 里列具体路径，避免全量放开。

十、常见问题

Q1：改了配置文件为什么不生效？

应用运行期间会以内存中的设置为准并在退出时写回文件，手工修改会被覆盖。正确顺序：完全退出应用 → 编辑文件 → 再启动。

Q2：data/settings.json 里出现大量 _v1/_v2 结尾的键是什么？

版本迁移标记位（如 llamacpp_fit_off_v1），应用用来记录"旧版设置已迁移到新结构"，正常升级会自动写入，无需手工管理。

Q3：API Key 填在哪里，为什么配置文件里搜不到明文？

桌面端 API Key 存系统钥匙串（keyring），不写入 JSON；无钥匙串环境降级为加密文件并在日志提示 Keyring unavailable ... using encrypted file fallback。终端代理的凭据则明文存于 ~/.jan/config.toml（该文件权限应保持仅当前用户可读）。

Q4：jan cli agent run 报 no model specified？

模型解析链全空所致。按 8.3 节顺序任选一处配置：临时用 --model，或长期在 agent.toml/config.toml 设置默认模型，并先用 jan config set 配好 Provider 凭据、用 jan cli models list 确认目标模型在列。

Q5：MCP 服务器加了却不连接？

检查 mcp_config.json 中该服务器 active 是否为 true（终端代理可用 jan cli mcp enable <名称> 置位）；filesystem 这类服务器还要确认 args 里的目录已改成实际存在的路径。

十一、参考链接

1. 官方 Desktop 文档 - Jan Data Folder（数据目录结构）：https://docs.jan.ai/desktop/data-folder （查询日期 2026-10-22）
2. 官方 Desktop 文档 - App Settings（应用设置）：https://docs.jan.ai/desktop/settings （查询日期 2026-10-22）
3. 官方 Desktop 文档 - Model Parameters（模型参数）：https://docs.jan.ai/desktop/model-parameters （查询日期 2026-10-22）
4. 官方 Desktop 文档 - Local API Server：https://docs.jan.ai/desktop/api-server （查询日期 2026-10-22）
5. 官方 Agent 文档 - Configuration（config.toml/agent.toml）：https://docs.jan.ai/agent/project-config （查询日期 2026-10-22）
6. 官方 Agent 文档 - CLI 参考：https://docs.jan.ai/agent/cli （查询日期 2026-10-22）

站内相关：《Jan 介绍与选型指南》、《Jan 0.8.7 配置参数详解》