Rabbit Chat Studio 的配置分两层:
- 应用级:操作系统应用数据目录里的
config.json、mcp_servers.json、sub_agents.json、profiles.json。 - 工作区级:
<工作区>/.data/,含聊天数据库、技能、记忆、待办、定时器、技能状态、run_cmd脚本库与工作区 MCP 清单。
应用数据目录
| 平台 | 路径 |
|---|---|
| Windows | %APPDATA%\com.leonard.aichat\(Roaming) |
| macOS | ~/Library/Application Support/com.leonard.aichat/ |
| Linux | ~/.local/share/com.leonard.aichat/ |
商店(MSIX)安装会被 Windows 重定向到
%LOCALAPPDATA%\Packages\XLBBB.RabbitChatStudio\LocalCache\Roaming\com.leonard.aichat\。
| 文件 | 内容 |
|---|---|
config.json |
模型、API、工具、工作区、外观、日志保留、更新开关 |
mcp_servers.json |
MCP 服务器定义 |
sub_agents.json |
子智能体 + 编排 |
profiles.json |
应用内 配置档 |
agents/ |
llm 智能体定义(Markdown)与 index.yaml 发现清单 |
model_metadata.json |
合并后的模型目录(约 2900 条、约 1.2 MB),最多每周刷新一次 |
shadow/ |
单实例锁 + 每个额外窗口一份 config-<时间戳>-<id>/(见多窗口) |
app-<日期>.log |
调试版日志,一天一个文件(发布版默认不写) |
workspace/ |
默认工作区 |
config.json 字段
模型与 API
| 字段 | 类型 | 默认 | 说明 |
|---|---|---|---|
api_base_url |
string | https://api.openai.com/v1 |
OpenAI 兼容根地址 |
api_key |
string | 空 | Bearer 密钥,明文存储 |
model |
string | gpt-4o-mini |
默认模型 |
model_catalog |
string[] | ["gpt-4o-mini"] |
模型选择器条目 |
model_context_lengths |
object | {} |
按模型的上下文窗口,如 {"gpt-4o-mini": 128000} |
model_metadata |
object | {} |
从合并目录匹配到的能力;仅本地 |
model_reasoning_effort |
object | {} |
按模型的思考深度:minimal / low / medium / high |
model_settings |
object | {} |
温度、Top P、补全上限等 |
ds_format |
boolean | false |
为 DeepSeek 思考模型补 reasoning_content(模型 id 命中 DeepSeek 时自动开启) |
system_message |
string | 空 | 你的基础系统提示 |
conversation_id_header |
string? | 空 | 携带会话 id 的额外请求头,如 X-Conversation-Id |
custom_headers |
{name, value}[] |
[] |
加到每个聊天请求上的额外头 |
模型目录
"获取模型"不只拉一个源。应用下载三个源,按规范化后的名字合并成一条:
| 顺序 | 来源 | 为什么 |
|---|---|---|
| 1 | models.dev |
覆盖最广,且是唯一提供精确 token 上限的源 |
| 2 | OpenRouter | 补充 id 与上下文提示 |
| 3 | llm-metadata |
唯一提供 tags(Audio / Files / Open Weights / Deprecated)的源 |
值得知道的规则:
- 低优先级源只填空字段,并补充其他源缺失的模型;
- 某个源失败或不再能解析就跳过,其余照常合并;只有全部无响应且本地无文件时才报错;
- 名字统一小写并扁平化,所以拉到的 id 走直接比对即可匹配目录;相似度打分只用于目录不认识的 id(设置行会显示
Matched <名称> · N% 相似); - 合并结果缓存在
<应用数据>/model_metadata.json,最多每周刷新一次,因此重启、断网重启、镜像慢都还能用; - 拉取期间选择器显示转圈。
model_settings 字段:
| 字段 | 说明 |
|---|---|
temperature |
0–2 |
top_p |
0–1 |
reasoning_effort |
全局兜底;model_reasoning_effort[模型] 优先 |
max_complete_tokens |
单条回复补全上限(推荐) |
max_tokens |
旧字段;同时作为上下文窗口的兜底 |
工具与工作区
| 字段 | 类型 | 默认 | 说明 |
|---|---|---|---|
selected_tools |
string[] | [] |
启用的工具 id |
self_evolution_mode |
boolean | false |
允许助手演进自己的技能;强制开启 file_actions + memory |
background_tools |
boolean | false |
为 run_cmd / run_shell / file_actions 搜索 / MCP 工具 / call_subagent 下发 run_in_background(设置 → 运行时与调试 → 后台执行) |
parallel_tools |
boolean | true |
同一轮回复里的独立工具调用同时执行(工具侧边栏底部的“并行工具调用”);false = 严格逐个执行 |
max_parallel_tools |
number | 4 |
单轮最多同时跑几个调用,限制在 1–8;1 等同关闭 parallel_tools |
workspace_dir |
string? | 空 | 工作区绝对路径;空 = 默认 |
workspace_history |
string[] | [] |
最近用过的工作区(新的在前,最多 10 个),在 设置 → 工作区 里作为选择器 |
main_agent_max_rounds |
number | 40 |
主智能体每轮可用请求数(设置 → 高级);0 不限,上限 1000 |
main_agent_max_tool_calls |
number | 120 |
每轮工具调用数;0 不限,上限 5000 |
tool_failure_limit |
number | 3 |
连续失败多少次后该工具在本次会话余下时间被禁用;0 关闭 |
auto_accept_confirm_kinds |
string[] | [] |
自动接受的确认类型;"*" 全部 |
selected_tools 取值:
file_actions, run_cmd, run_shell, memory, todo_list, timer
别名 todo。todo_list 以 todos 名义暴露给模型。已废弃 id(例如 knowledge_graph)在加载与保存时会被剔除。
self_evolution_mode: true会强制把file_actions与memory写进selected_tools。每次保存与启动都会重写选择,因此工具面板、配置档、备份恢复或手改config.json都无法在模式开启时关掉它们。它同时解锁evolution记忆作用域,并允许助手在<工作区>/.data/skills下安装、编辑、删除技能。
auto_accept_confirm_kinds 取值:
dangerous, system_config, user_software, user_data, external_agent, *
内置命令按风险等级 L0–L3 在运行前询问;自动接受对应类型(或 *)可在本次会话余下时间跳过询问。external_agent 不在工具面板的快捷项里,需要在这里设置。
外观、日志与更新
| 字段 | 类型 | 默认 | 说明 |
|---|---|---|---|
theme |
string? | auto |
auto / light / dark |
palette |
string? | default |
配色:default / cream / macaron(马卡龙,粉白马卡龙色系,玫瑰粉强调色);各有浅色与深色两套 token。旧配置中的 sakura 会在加载时迁移为 default |
chat_background |
string? | 无 | 可选的聊天区背景照片,保存为应用数据目录下的相对路径,例如 backgrounds/chat-background-<id>.png。在「设置 → 外观 → 聊天区背景」选择后立即把文件复制到 <应用数据目录>/backgrounds/ |
single_instance |
boolean | false |
仅发布版。开:第二次启动只聚焦已有窗口。关:每次启动都是一个窗口(见多窗口)。下次启动生效 |
language |
string? | 自动 | en / zh-CN / zh-TW |
logger_output |
string | file |
file / println;仅调试版 |
log_retention_days |
number | 90 |
请求/交互日志保留天数;0 永久 |
check_updates_on_startup |
boolean | true |
启动时检查更新 |
include_prerelease_updates |
boolean | false |
包含预发布 |
完整示例
{
"api_base_url": "https://api.openai.com/v1",
"api_key": "sk-...",
"model": "gpt-4o-mini",
"model_catalog": ["gpt-4o-mini", "gpt-4.1-mini"],
"model_context_lengths": {
"gpt-4o-mini": 128000
},
"model_settings": {
"temperature": 0.7,
"top_p": 0.95,
"max_complete_tokens": 4096
},
"system_message": "你是一个乐于助人的助手。",
"selected_tools": ["file_actions", "memory", "todo_list", "timer"],
"background_tools": true,
"parallel_tools": true,
"max_parallel_tools": 4,
"workspace_dir": "D:/projects/my-repo",
"main_agent_max_rounds": 40,
"main_agent_max_tool_calls": 120,
"tool_failure_limit": 3,
"theme": "auto",
"language": "zh-CN",
"log_retention_days": 90,
"check_updates_on_startup": true,
"include_prerelease_updates": false
}
改
config.json前请完全退出应用,否则设置面板可能用内存里的值把它覆盖掉。
配置档(Profiles)
设置 → 工作区与配置档 → 配置档 保存的是一套能力集:
| 包含 | 不包含 |
|---|---|
selected_tools |
API 地址/密钥 |
| 子智能体列表 | 默认模型 |
| 编排设置 | 系统提示 |
| MCP 服务器 | 工作区目录 |
| — | 技能启用状态 |
适合:
- 在"只读分析""全量编码""启用 MCP 的工作流"之间切换;
- 为不同项目准备不同的智能体/MCP 组合;
- 备份 MCP 与子智能体配置。
操作:
- 输入名字 → 保存当前;
- 应用 → 覆盖当前的工具/智能体/MCP/编排;
- 删除 → 从
profiles.json移除。
技能启用状态属于工作区(.data/skills.status),配置档不碰它。这是有意为之。
完整导出与恢复
入口:
- 标题栏
⋯→ 导出配置… / 恢复配置…; - macOS 原生文件菜单;
- 命令
app_export_profile/app_import_profile。
导出期间会锁住发送按钮并显示进度,保证快照期间数据库不被写入。
压缩包内容
config.json AppConfig
profiles.json 命名配置档
mcp_servers.json MCP 服务器
sub_agents.json 子智能体 + 编排
agents/... `llm` 智能体定义(应用级,Markdown)
backgrounds/... 聊天区背景照片(应用级)
workspace/memory/... 当前工作区记忆
workspace/todos/... 当前工作区待办
workspace/skills/... 当前工作区技能
workspace/scripts/... run_cmd 脚本库
workspace/mcp/... 自建 MCP 服务器脚本(自我进化模式)
workspace/mcp.conf 这些服务器的清单
workspace/deliver/... 子智能体交付物,每个会话一个目录
workspace/skills.status 技能启用状态
chat.db SQLite 快照(VACUUM INTO)
子智能体的交付物交换区(<工作区>/.data/deliver/<会话 id>/)会导出;删除会话时一并清理。
chat.db 是一致性的 VACUUM INTO 快照;生成期间应用会短暂禁止发送。
导入行为
导入会:
- 读取并应用
config.json(可能切换工作区); - 写入
sub_agents.json; - 写入
profiles.json(仅当它确实是配置档文件); - 合并
agents/**/*.md到应用级agents/库(完全相同的文件不动); - 恢复
backgrounds/(替换整个目录),让config.json里的背景路径继续有效; - 把
workspace/memory、workspace/todos、workspace/skills、workspace/scripts、workspace/mcp、workspace/mcp.conf恢复到当前工作区的.data; - 恢复
workspace/skills.status。
目前不会恢复:
chat.db
压缩包里虽然有它,但导入路径不写回。需要历史记录时:退出应用,把 chat.db 复制到 <工作区>/.data/chat.db。
导入也会写入应用数据目录的 mcp_servers.json。
这是当前行为,后续版本可能变化。升级后请核对导入结果。
手动完整备份
最可靠的做法是退出应用后把两处一起复制:
<应用数据>/ → config.json、mcp_servers.json、sub_agents.json、
profiles.json、agents/、backgrounds/、
model_metadata.json、shadow/
<工作区>/.data/ → chat.db、memory/、todos/、skills/、skills.status、
timers.json、scripts/、mcp/、mcp.conf
先退出,避免 SQLite 还有未落盘的 WAL。
多窗口
single_instance 决定第二次启动能否存活:
-
开:第二次启动把参数交给运行中的实例,已有窗口被显示并聚焦。
-
关:每次启动都是一个窗口。第一个进程是主窗口,继续共用
config.json;之后每个窗口都是影子窗口:- 启动时把当前配置复制到
<应用数据>/shadow/config-<时间戳>-<id>/config.json; - 副本里的
workspace_dir被改写到它自己的workspace/分叉——两个窗口绝不共享工作区,因此不会争用同一个 SQLite 数据库; - 影子窗口只写自己的分叉;退出时副本被删除,只有
workspace_history合并回共享配置(影子的临时工作区被过滤掉); - 在影子里清空
workspace_dir会回到它自己的分叉,而不是共享默认工作区; - 分叉窗口会在 设置 → 工作区 里说明;崩溃遗留的副本在下次启动时清理。
- 启动时把当前配置复制到
设置 → 工作区 列出最近用过的目录(workspace_history,新的在前,最多 10 个)。选中只是暂存,保存更改才真正切换。标题栏的工作区名带一条细红下划线,分叉窗口一眼可辨。
换到新机器
- 旧机器:完全退出应用。
- 旧机器:复制应用数据目录与当前工作区的
.data。 - 新机器:安装同版本或更新版本。
- 新机器:启动一次以创建默认目录。
- 新机器:退出应用。
- 新机器:覆盖应用数据文件;把
.data放到新工作区。 - 启动并确认 设置 → 工作区 指向正确目录。
- 检查模型/API 密钥、MCP 服务器、子智能体、技能开关。
- 打开历史记录,确认
chat.db已读到。
工作区路径变了就在设置里重新选,或改 config.workspace_dir。
安全
config.json里的 API 密钥是明文。mcp_servers.json里的auth_token与env也是明文。- 不要把应用数据目录提交到 Git。
- 共享机器上启用全盘加密;妥善保管导出的压缩包。
- 定期轮换密钥;泄露立即吊销。
- 不要把生产密钥放进工作区文件——模型能读到。
常见问题
| 现象 | 排查 |
|---|---|
| 改了配置不生效 | 完全退出再启动;设置面板是否覆盖了? |
| 导入后 MCP 服务器没了 | 手动复制 mcp_servers.json,或用当前版本重新导出 |
| 导入后历史没了 | chat.db 不会自动恢复;手动复制 |
| 导入后技能开关不对 | 压缩包里有 skills.status 吗?恢复到了正确的工作区吗? |
| 应用配置档后模型没变 | 配置档不含模型/API,只切换工具、智能体、MCP 与编排 |
| 导出的包很大 | chat.db 含请求体与日志;先压缩或调低保留天数 |
| 配置档里没有技能 | 设计如此;技能是工作区状态 |
| 模型能力信息缺失 | model_metadata.json 可能早于该模型;缓存每周刷新——再"获取模型"一次强制合并 |