数据路径
Kiki 默认把运行时数据——配置文件、会话历史、登录凭据、诊断日志——存放在 ~/.kiki/ 下。本页帮你搞清楚每类数据在哪里、用来做什么，以及需要时怎么清理或搬迁。
桌面 OAuth 凭据的默认位置不同
未设置 KIKI_HOME 时，桌面应用的运行时数据（配置、会话、server.token）在 ~/.kiki/，但它的 OAuth 凭据默认在兼容家目录 ~/.kimi-code/（~/.kimi-code/credentials/）。如果本机已有 Moonshot 的 ~/.kimi-code/credentials/kimi-code.json，桌面会直接使用这份令牌，而不是处于未登录状态——并且删除 ~/.kiki/ 不会清掉它。先跑 kiki login 则令牌写在 ~/.kiki/credentials/，之后不带桌面环境变量启动的 daemon 找不到桌面那边的令牌。
设置 KIKI_HOME 会把运行时数据和桌面 OAuth 凭据一起挪到该路径。桌面设置里也可以自行选择兼容家目录。kimi-cli 时代的 ~/.kimi 目录从不被读取，也不会被导入。
数据根目录
默认数据根是 ~/.kiki/，在不同平台的实际路径：
- macOS：
/Users/<name>/.kiki - Linux：
/home/<name>/.kiki - Windows：
C:\Users\<name>\.kiki
如果你需要把数据目录挪到别处（比如用多个独立环境隔离不同项目的配置），设置 KIKI_HOME 即可：
export KIKI_HOME="$HOME/.config/kiki"设置后，配置、供应商凭证、会话、日志、OAuth 凭据、Kiki 专属用户级 Skills、全局 AGENTS.md 等 Kiki 数据都会落到新路径下。KIKI_HOME 的完整说明见环境变量。
提示
通用 .agents 资源仍放在真实 OS home 下，以便跨工具共享。例如，用户级通用 Skills 仍位于 ~/.agents/skills/，而 Kiki 专属用户级 Skills 会随 KIKI_HOME 移动到 $KIKI_HOME/skills/。
目录结构
$KIKI_HOME （默认 ~/.kiki）
├── config.toml # 用户配置
├── tui.toml # 终端界面偏好
├── AGENTS.md # 全局 Kiki 专属 Agent 指令（可选）
├── mcp.json # 用户级 MCP server 声明（可选）
├── skills/ # Kiki 专属用户级 Skills（可选）
├── cognition/ # `[models."<alias>".cognition]` 引用的提示词文件（可选；见配置文件页）
├── hooks/ # `[[hooks]]` command 路径引用的脚本文件（可选；见 Hooks）
├── plugins/
│ ├── installed.json # 已安装 plugin 记录与启用状态
│ └── managed/ # zip/本地路径安装的 plugin 副本
├── session_index.jsonl # 会话索引
├── workspaces.json # 已注册工作区的名称与根目录
├── workspaces/ # 自动创建的工作区目录
│ └── <date>-<id>/
├── credentials/ # 凭据目录（目录 0700，文件 0600）
│ ├── credentials.toml # 供应商 API 密钥
│ ├── <name>.json
│ └── mcp/
│ └── <key>-<suffix>.json
├── sessions/ # 会话数据（详见下文）
│ └── <workDirKey>/<sessionId>/
├── store/
│ └── thread-mailbox-sqlite-v1/ # 持久消息邮箱与升级恢复副本
├── server/
│ └── events/ # 有界的客户端事件重放日志
├── bin/
│ ├── rg # Grep 使用的托管 ripgrep 二进制（Windows 为 rg.exe）
│ └── fd # 文件引用使用的托管 fd 二进制（Windows 为 fd.exe）
├── logs/
│ └── kimi-code.log # 全局诊断日志
└── user-history/
└── <md5(workDir)>.jsonl各类文件说明
数据根下的文件各有用途，大部分由 CLI 自动管理：
config.toml：主运行时配置，存放供应商、模型、循环控制等用户级设置。供应商 API 密钥放在credentials/credentials.toml。详见配置文件。credentials/credentials.toml：存放供应商凭证，例如各供应商的api_key。同一条 TOML 路径上这里的值覆盖config.toml；旧版config.toml里遗留的凭证会在首次加载时迁入该文件，原文件保留为config.toml.bak-<date>——该备份仍是明文密钥，核对完迁移结果就删掉它。在平台支持的前提下，Kiki 以仅属主可读写的权限（0o600）写入该文件。详见供应商凭证。tui.toml：终端界面客户端偏好，例如主题、编辑器、通知和状态栏。AGENTS.md：用户级 Agent 指令。该文件会随KIKI_HOME移动，并与工作区根目录指令合并；工作区的.kiki/AGENTS.md可以覆盖它。mcp.json：用户级 MCP server 声明，启动时与项目内的.kiki/mcp.json合并加载。详见 MCP。skills/：Kiki 专属用户级 Skills。该目录会随KIKI_HOME移动；跨工具通用 Skills 仍可放在~/.agents/skills/。详见 Agent Skills。cognition/：[models."<alias>".cognition]引用的提示词文件，路径相对于数据根目录。详见模型认知。hooks/：[[hooks]]command 路径引用的脚本文件（如node ~/.kiki/hooks/check-bash.mjs）。详见 Hooks。plugins/installed.json：记录已安装的 plugin、每个 plugin 的启用状态，以及通过/plugins或/plugins mcp disable|enable修改的 MCP server 能力状态。本地路径和 zip URL 安装的文件会复制到plugins/managed/<id>/。详见 Plugins。credentials/：权限受限的凭据目录，请求权限为目录0o700、文件0o600。托管供应商的 OAuth 登录态存为credentials/<name>.json，MCP server 凭据存在credentials/mcp/子目录下。在 Windows 上，要靠这个目录挡住其他本机用户，请自行核查文件及其父目录的 ACL。workspaces.json与workspaces/：分别记录已注册工作区，以及新会话未指定工作区时 Kiki 创建的项目目录。每个自动创建的会话使用独立目录；这里是工作文件，与sessions/下的会话历史不同。
会话数据
每个会话的数据存在 sessions/<workDirKey>/<sessionId>/ 下，同时在顶层 session_index.jsonl 里维护一份索引（每行一条记录，含 sessionId、sessionDir、workDir 三个字段）。workDirKey 是从工作目录路径生成的桶名，格式为 wd_<slug>_<sha256前12位>。
会话目录内部包含：
state.json：会话标题、lastPrompt、创建/更新时间、forkedFrom等元数据。upcoming-goals.json：由/goal next <objective>创建的 TUI 专属队列。它不属于 Agent 对话；只有当前目标完成并提升后续目标后，才会进入 Agent 对话。agents/main/wire.jsonl：main agent 的完整通信记录，用于会话恢复和回放。kiki session seal会把这个文件留在原地，因此它的大小不会下降；kiki session unseal去掉封存，不修改该文件。agents/main/plans/：Plan 模式下写入的计划文件，按计划 id 命名（<id>.md）。agents/agent-0/等：subagent 实例目录，各自含wire.jsonl。logs/kimi-code.log：该会话的诊断日志，只有发生诊断事件时才存在。tasks/：后台任务持久化——tasks/<task_id>.json保存状态/pid/退出码，tasks/<task_id>/output.log保存输出。cron/：定时任务持久化，用kiki --session恢复会话时重新加载到调度器。详见定时任务。
服务端事件重放
server/events/<sessionId>.jsonl 保存客户端重连时使用的持久事件，不是完整会话历史。Kiki 自动保留会话的重放窗口（默认 1000 条）。活跃 writer 的日志超过两个窗口时会收缩为一个窗口，关闭时也收缩为一个窗口；这里限制的是事件条数，不是字节数，超大事件仍会完整保存。
旧日志在新 writer 首次追加事件时收缩。浏览未激活的会话只读取水位，不会改写日志；因此，未再次写入的旧日志和已删除会话的遗留日志仍需显式清理。替换失败时会保留原持久日志并记录警告，后续写入或 writer 关闭时重试空间回收。
这项保留策略不会删除 sessions/、Agent 的 wire.jsonl 或媒体原件。游标超出保留窗口的客户端会通过快照/reset 恢复，而不是补播旧事件序列，见 断线恢复。如需手动清理旧日志，先停止所有使用该数据根目录的 Kiki 服务，再仅清理 server/events/ 并重启。不要在 writer 运行时删除或截断这些日志。
持久消息邮箱
store/thread-mailbox-sqlite-v1/ 保存线程间消息、投递状态、幂等回执、活动游标和工作区覆盖设置。这些记录是持久原件，不像搜索和查询缓存，不能靠删除后重建来恢复。authority.json 指定当前使用的 mailbox-<migrationId>.sqlite；数据库打开时，旁边的 -wal 和 -shm 文件也要保留。请用 kiki storage backup 创建一致的 SQLite 副本，不要只复制正在使用的 .sqlite 文件。
0.5.x 升级将检查点保存在 migration.json，源数据冻结副本放在 recovery/<migrationId>/sources/，移走的原目录放在 recovery/<migrationId>/originals/。原来的 store/thread-mailbox-v3、store/thread-mailbox-v1 和 store/agent-collaboration-mailbox-v2 目录名会变成阻止旧版本写入的占位文件。请保留原目录及阻写文件：它们既阻止旧版重新写入，也保存旧活动记录。不要让旧二进制程序使用恢复副本作为可写邮箱。用 kiki storage status 查看恢复状态，用 kiki storage migrate 续接。回滚窗口关闭后，kiki storage cleanup-recovery 可以预览，并在独立 SQLite 备份验证通过、显式确认后，仅移除与原件相同的 sources/ 副本。不要手动删除这些目录；需要回退时，遵循 storage 命令的回退规则，不要手动移回原目录。
会话与用量查询缓存
cache/query-store-sqlite-v1/index.sqlite 保存会话列表和线程轮次查询使用的 SQLite 缓存。用量事实与来源覆盖水位使用独立数据库 cache/usage-read-model-v2/index.sqlite。Kiki 会按需从会话元数据、用量事实日志、保留用量账本和对话历史重建这些视图。每个数据库打开时，旁边可能还有 -wal 和 -shm 文件。
如果某个缓存损坏，先停止所有使用该数据根目录的 Kiki 进程，备份后仅移除对应缓存目录，再重新启动。历史较多时，Usage 重建可能需要多次请求；已提交的导入进度可在重启后接续。请保留 cache/usage-facts-v1/、sessions/ 和 store/，恢复所需的日志与记录存放在这些目录中。旧通用用量集合和 cache/query-store-v*/ 目录会保留供回滚使用；不要为了重置 Usage 而删除共享查询数据库。
全文搜索索引
全文搜索使用 search-index-v2/index.sqlite 中的 SQLite 索引。Kiki 会复用兼容的索引，或从会话元数据与对话历史重建已识别的旧版搜索索引；重建期间，结果可能不完整。缓存重建不会改动历史原件。旧 MiniDb search-index/ 目录保持原样，既不导入，也不作为故障回退。请保留 sessions/ 和 store/：搜索缓存重建与 mailbox 消息存储升级各有自己的流程。
在 0.5 迁移系列中，config.toml 里显式设置的 search_backend = "minidb" 或 KIKI_SEARCH_BACKEND=minidb 是 SQLite 的已弃用别名，并会产生迁移警告。请在升级到退役该值的 0.6 前删除旧设置，或改为 sqlite。环境变量优先于 search_backend；Kiki 不会改写这两处设置。旧 search_worker 实验开关已移除，SQLite 始终通过写入子进程与查询工作线程隔离数据库工作。
搜索默认可用。[search] enabled = false、KIKI_SEARCH_DISABLED=1 或桌面端显式设置的 desktop_search = false 会保持关闭；搜索关闭时，迁移别名不会启动工作线程或重建缓存。[search] index_subagents = true 可将 subagent 内容纳入索引，默认关闭。这些设置在重启 Kiki 后生效。搜索默认匹配用户、助手正文与会话标题；只有显式请求时才包含工具结果输出。思考内容、工具名和工具调用参数不参与搜索。
内置工具缓存
Grep 工具第一次需要 ripgrep 时，CLI 可自动下载 rg 并缓存到 bin/rg（Windows 为 bin/rg.exe）。终端界面的文件引用补全使用 fd；需要时 CLI 会在后台自动下载并缓存到 bin/fd（Windows 为 bin/fd.exe）。之后的运行会直接复用缓存的二进制。rg 优先使用系统 PATH，再使用缓存；fd 优先检查托管缓存，再回退到系统 fd / fdfind。删除 bin/ 目录会在下次需要时触发重新下载。
日志
logs/kimi-code.log（全局）：记录启动、登录、导出等跨会话事件。<sessionDir>/logs/kimi-code.log（会话级）：记录单个会话内的诊断事件。
报 bug 时，优先用 kiki export 导出相关会话（详见 kiki 命令）；会话日志默认包含在导出包里。不想分享全局日志时加 --no-include-global-log。
输入历史
终端输入历史按工作目录分开保存，路径为 user-history/<md5(workDir)>.jsonl。用于在终端界面里用方向键浏览历史提示词。
清理数据
删除数据根目录（~/.kiki/ 或 KIKI_HOME 指定路径）会清除所有运行时数据，包括自动创建的工作区中的文件。删除前请备份这些工作文件。归档会话或注销工作区不会删除工作目录；只清理 sessions/ 也不会删除 workspaces/。未设置 KIKI_HOME 且桌面兼容家目录保持默认时，桌面 OAuth 凭据在 ~/.kimi-code/credentials/（见本页开头的说明），删除 ~/.kiki/ 不会清掉它。只需清理部分内容时：
| 需求 | 操作 |
|---|---|
| 重置配置 | 删除 ~/.kiki/config.toml |
| 重置供应商凭证 | 删除 ~/.kiki/credentials/credentials.toml（若旧文件仍存在，也删除 ~/.kiki/credentials.toml，以免下次启动重新迁入） |
| 重置终端界面偏好 | 删除 ~/.kiki/tui.toml |
| 清理所有会话 | 删除 ~/.kiki/sessions/ 和 session_index.jsonl |
| 清理诊断日志 | 删除 ~/.kiki/logs/ |
| 清理输入历史 | 删除 ~/.kiki/user-history/ |
强制重新下载托管 rg 和 fd | 删除 ~/.kiki/bin/ |
| 清除供应商 OAuth 登录态 | 运行 /logout，或删除对应的 credentials/<name>.json |
| 清除 MCP server OAuth 登录态 | 删除 credentials/mcp/（/logout 不会清理 MCP 凭据） |
| 移除用户级 MCP 声明 | 删除 $KIKI_HOME/mcp.json（默认为 ~/.kiki/mcp.json） |
| 清理全局 Kiki 专属 Agent 指令 | 删除 $KIKI_HOME/AGENTS.md（默认为 ~/.kiki/AGENTS.md） |
| 清理 plugin 安装记录 | 删除 $KIKI_HOME/plugins/（本地 plugin 源码不受影响） |
| 清空 Kiki 专属用户级 Skills | 删除 $KIKI_HOME/skills/（默认为 ~/.kiki/skills/） |