数据路径

开篇导读

Kimi Code CLI采用集中式数据存储设计，所有运行时数据（配置、会话、日志、凭据等）均统一存放在指定目录下，便于用户备份、迁移、清理与管理。了解数据路径结构可帮助你快速定位核心文件、备份重要会话、清理冗余数据、实现多环境隔离。

掌握本页面内容后，你将能够：

1. 清楚每类数据的存储位置与作用
2. 按需迁移数据目录到自定义路径
3. 安全清理不需要的冗余数据
4. 备份核心配置与会话数据
5. 排查数据相关的异常问题

Kimi Code CLI 把所有运行时数据——配置文件、会话历史、登录凭据、诊断日志——集中存放在 ~/.kimi-code/ 下。本页帮你搞清楚每类数据在哪里、用来做什么，以及需要时怎么清理或搬迁。

数据根目录

操作目的

明确默认数据根目录的位置，以及自定义数据根目录的方法，实现多环境数据隔离，满足不同使用场景的需求。

默认数据根是 ~/.kimi-code/，在不同平台的实际路径：

• macOS：/Users/<name>/.kimi-code
• Linux：/home/<name>/.kimi-code
• Windows：C:\Users\<name>\.kimi-code

如果你需要把数据目录挪到别处（比如用多个独立环境隔离不同项目的配置），设置 KIMI_CODE_HOME 即可：

export KIMI_CODE_HOME="$HOME/.config/kimi-code"

设置后，配置、会话、日志、OAuth 凭据、Kimi 专属用户级 Skills、全局 AGENTS.md 等 Kimi Code 数据都会落到新路径下。KIMI_CODE_HOME 的完整说明见环境变量。

预期结果

设置KIMI_CODE_HOME并启动CLI后，程序会自动在指定路径下创建所有必需的子目录与文件，完全脱离默认路径存储数据，实现环境隔离。

注意事项

• 自定义路径需确保当前用户有可读可写权限，否则CLI启动时会抛出「无法写入数据目录」错误。
• 多个CLI实例共用同一个KIMI_CODE_HOME会共享配置与凭据，但不建议同时运行多个实例，可能导致会话数据写入冲突。
• 数据根目录建议定期备份，避免系统重装、磁盘损坏导致配置与会话丢失。

补充说明

通用.agents目录是跨Agent工具的共享资源目录，所有兼容该规范的AI工具均可读取其中的Skill与指令，方便用户在不同工具间复用自定义能力；Kimi专属资源仅在Kimi Code CLI中生效，随数据根目录移动而迁移。

目录结构

结构说明

以下为数据根目录的完整结构，各目录与文件分工明确，CLI自动维护，普通用户无需手动修改内部文件。

$KIMI_CODE_HOME  （默认 ~/.kimi-code）
├── config.toml             # 用户配置
├── tui.toml                # 终端界面偏好（含自动更新开关）
├── AGENTS.md               # 全局 Kimi 专属 Agent 指令（可选）
├── mcp.json                # 用户级 MCP server 声明（可选）
├── skills/                 # Kimi 专属用户级 Skills（可选）
├── plugins/
│   ├── installed.json      # 已安装 plugin 记录与启用状态
│   └── managed/            # zip/本地路径安装的 plugin 副本
├── session_index.jsonl     # 会话索引
├── credentials/            # OAuth 凭据（目录 0700，文件 0600）
│   ├── <name>.json
│   └── mcp/
│       └── <key>-<suffix>.json
├── sessions/               # 会话数据（详见下文）
│   └── <workDirKey>/<sessionId>/
├── bin/
│   ├── rg                  # Grep 使用的托管 ripgrep 二进制（Windows 为 rg.exe）
│   └── fd                  # 文件引用使用的托管 fd 二进制（Windows 为 fd.exe）
├── logs/
│   └── kimi-code.log       # 全局诊断日志
├── updates/
│   ├── latest.json
│   ├── install.json
│   ├── install.lock
│   └── rollout.log
└── user-history/
    └── <md5(workDir)>.jsonl

各目录核心作用速览

各类文件说明

数据根下的顶层文件各有用途，大部分由 CLI 自动管理：

• config.toml：主运行时配置，存放供应商、模型、循环控制等用户级设置。详见配置文件。
• tui.toml：终端界面客户端偏好，包括 [upgrade].auto_install（自动更新，默认开启）。可在 /settings 关闭，或手动设为 auto_install = false。
• AGENTS.md：全局 Kimi 专属 Agent 指令。该文件会随 KIMI_CODE_HOME 移动；跨工具通用指令仍可放在 ~/.agents/AGENTS.md。
• mcp.json：用户级 MCP server 声明，启动时与项目内的 .kimi-code/mcp.json 合并加载。详见 MCP。
• skills/：Kimi 专属用户级 Skills。该目录会随 KIMI_CODE_HOME 移动；跨工具通用 Skills 仍可放在 ~/.agents/skills/。详见 Agent Skills。
• plugins/installed.json：记录已安装的 plugin、每个 plugin 的启用状态，以及通过 /plugins 或 /plugins mcp disable|enable 修改的 MCP server 能力状态。本地路径和 zip URL 安装的文件会复制到 plugins/managed/<id>/。详见 Plugins。
• credentials/：OAuth 凭据目录，权限 0o700（目录）/ 0o600（文件），仅当前用户可读写。托管供应商凭据存为 credentials/<name>.json，MCP server 凭据存在 credentials/mcp/ 子目录下。凭据写入使用原子流程（tmp → fsync → rename）防止写损。

补充说明

• AGENTS.md中可定义全局生效的Agent行为规范，例如「所有代码必须添加中文注释」、「优先使用TypeScript编写」等，所有新建会话的Agent都会遵循该指令，优先级低于项目级AGENTS.md。
• skills/目录支持多级子目录，可按分类存放Skill（如skills/coding/、skills/debug/），CLI会自动递归扫描所有子目录中的Skill文件。
• credentials/目录的权限由CLI自动设置，请勿修改目录或文件权限，否则可能导致凭据读取失败或泄露风险。
• 手动安装的本地插件源码不会被复制到plugins/managed/目录，仅记录启用状态，删除plugins/目录不会影响本地插件源码。

会话数据

存储说明

每个会话的数据独立存储，按工作目录分类，便于按项目管理会话历史，会话数据支持完整恢复与导出。

每个会话的数据存在 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：主 Agent 的完整通信记录，用于会话恢复和回放。
• agents/main/plans/：Plan 模式下写入的计划文件，按计划 id 命名（<id>.md）。
• agents/agent-0/ 等：子 Agent 实例目录，各自含 wire.jsonl。
• logs/kimi-code.log：该会话的诊断日志，只有发生诊断事件时才存在。
• tasks/：后台任务持久化——tasks/<task_id>.json 保存状态/pid/退出码，tasks/<task_id>/output.log 保存输出。
• cron/：定时任务持久化，kimi resume 时重新加载到调度器。详见定时任务。

补充说明与最佳实践

• wire.jsonl是会话恢复的核心文件，包含所有对话、工具调用、返回结果的完整记录，只要该文件存在，会话即可完整恢复。
• 会话标题可在TUI中手动修改，修改后会自动同步到state.json中。
• Plan模式下的计划文件为标准Markdown格式，可手动编辑修改，Agent会按照修改后的计划执行。
• 重要会话建议通过kimi export命令导出为压缩包备份，避免数据丢失。
• 不需要的会话可直接删除对应目录，session_index.jsonl会自动更新，无需手动修改索引文件。
• 定时任务会持久化存储在cron/目录中，重启CLI后执行kimi resume即可重新加载所有定时任务，不会丢失。

内置工具缓存

作用说明

CLI内置依赖的工具自动下载缓存，无需用户手动安装，降低使用门槛。

Grep 工具第一次需要 ripgrep 时，CLI 可自动下载 rg 并缓存到 bin/rg（Windows 为 bin/rg.exe）。终端界面的文件引用补全使用 fd；需要时 CLI 会在后台自动下载并缓存到 bin/fd（Windows 为 bin/fd.exe）。之后的运行会直接复用缓存的二进制。rg 优先使用系统 PATH，再使用缓存；fd 优先检查托管缓存，再回退到系统 fd / fdfind。删除 bin/ 目录会在下次需要时触发重新下载。

补充说明与问题排查

• ripgrep（rg）是高性能全文搜索工具，fd是高性能文件查找工具，均为开源第三方工具，CLI自动下载对应平台的官方二进制包，无需手动安装。
• 若CLI启动时提示找不到rg或fd，通常是网络问题导致下载失败，可手动安装ripgrep和fd到系统PATH中，CLI会优先使用系统安装的版本。
• 若缓存的工具版本过旧，可直接删除bin/目录，CLI下次使用时会自动下载最新版本。

日志与更新状态

作用说明

日志用于问题排查，更新状态由自动更新机制维护，帮助用户了解版本更新情况。

• logs/kimi-code.log（全局）：记录启动、登录、导出等跨会话事件。
• <sessionDir>/logs/kimi-code.log（会话级）：记录单个会话内的诊断事件。

报 bug 时，优先用 kimi export 导出相关会话（详见 kimi 命令）；会话日志默认包含在导出包里。不想分享全局日志时加 --no-include-global-log。

updates/ 下的文件（latest.json、install.json、install.lock、rollout.log）由自动更新机制维护，通常无需手动编辑。rollout.log 记录每次更新检查命中的灰度分批情况，可用于排查设备何时能收到新版本。

补充说明

• 遇到CLI启动失败、登录异常、API调用错误等问题时，可查看全局日志定位原因；遇到单个会话异常时，查看对应会话的会话级日志。
• 日志文件默认自动滚动，不会无限增长占用磁盘空间，默认保留最近5份全局日志、3份会话日志。
• 若长时间未收到版本更新，可查看rollout.log确认是否处于灰度分批范围内，灰度发布阶段会逐步推送新版本。

输入历史

作用说明

按工作目录独立存储终端输入历史，便于快速复用之前的提示词，提升输入效率。

终端输入历史按工作目录分开保存，路径为 user-history/<md5(workDir)>.jsonl。用于在终端界面里用方向键浏览历史提示词。

补充说明

• 输入历史按工作目录隔离，例如在~/project1目录下的输入历史仅在该目录下启动CLI时可见，避免不同项目的历史输入混乱。
• 输入历史仅存储用户输入的提示词，不存储对话内容与工具调用结果。

清理数据

操作说明

提供不同粒度的数据清理操作，满足不同场景的清理需求，操作前请注意备份重要数据。

删除数据根目录（~/.kimi-code/ 或 KIMI_CODE_HOME 指定路径）可清除所有运行时数据。只需清理部分内容时：

注意事项与最佳实践

• 所有删除操作均不可逆，操作前请确认已备份重要数据（如配置文件、重要会话）。
• 重置配置后，下次启动CLI会自动生成新的默认config.toml，原有配置将丢失，建议操作前备份配置文件。
• 清理所有会话会删除全部会话历史，无法恢复，操作前请确认是否有需要保留的会话。
• 清除OAuth登录态后，需要重新登录才能使用托管服务，建议优先使用/logout命令，避免手动删除文件导致凭据异常。
• 删除数据根目录会清除所有配置、会话、凭据、日志等全部数据，仅建议彻底卸载或重置环境时使用。