一、工具简介
Claude Conversation Extractor是一款专为 Claude Code 用户设计的命令行工具，用于解决 Claude Code 官方不提供对话导出功能的痛点。它直接读取 Claude Code 存储在本地~/.claude/projects/目录下的 JSONL 格式日志文件，将其转换为干净、可读的 Markdown 文档，方便你备份、归档或后续分析。
该工具的核心特点包括：
- 零依赖：仅使用 Python 标准库，无需安装任何额外包
- 跨平台：支持 Windows、macOS 和 Linux
- 只读安全：不会修改 Claude Code 的原始文件，也不会上传任何数据
- 实时搜索：支持按内容、日期或会话名称搜索对话
- 批量导出：可一次性导出所有会话或仅导出最近的几条
二、安装方法
pipinstallclaude-conversation-extractor⚠️ 注意：在较新的系统（如 Ubuntu 23.04+、macOS 13+）上，直接运行
pip install可能会遇到 “externally managed environment” 错误，此时建议改用 pipx 或创建虚拟环境。
三、快速上手
安装完成后，系统会提供以下命令：
| 命令 | 说明 |
|---|---|
claude-extract | 主命令，启动交互式界面或执行导出 |
claude-start | claude-extract的快捷别名，功能相同 |
claude-search | 搜索对话内容 |
3.1 启动交互式界面
claude-start# 或claude-extract--interactive# 或claude-extract-i启动后，你会看到一个带有 ASCII 艺术标志的交互式终端界面，提供以下选项：
- 输入
A— 导出所有对话 - 输入
R— 导出最近5条对话 - 输入
S—选择特定对话导出 - 输入
Q— 退出
界面会列出所有对话的日期和大小，并支持选择导出目录（如 Desktop、Documents、Downloads）。
3.2 命令行模式（常用）
# 列出所有 Claude 会话claude-extract--list# 导出最近 5 个会话claude-extract--recent5# 导出指定编号的会话（多个用逗号分隔）claude-extract--extract1,3,5# 导出所有会话claude-extract--all# 导出到指定目录claude-extract--all--output~/Documents/Claude-Backups四、搜索功能详解
claude-search是该工具的一大亮点，支持全文实时搜索，无需记住复杂的命令参数。
# 交互式搜索（提示输入关键词）claude-search# 直接搜索特定内容claude-search"API integration"claude-search"error handling"claude-search"Docker 部署"搜索特性：
- 全文检索：不区分大小写，支持部分匹配
- 预览上下文：显示匹配内容的上下文片段
- 直接导出：在搜索结果中可直接选择导出匹配的会话
五、数据存储位置与导出格式
5.1 Claude Code 原始日志位置
Claude Code 将对话记录以 JSONL 格式存储在以下路径：
| 平台 | 路径 |
|---|---|
| macOS / Linux | ~/.claude/projects/*/chat_*.jsonl |
| Windows | %USERPROFILE%\.claude\projects\*\chat_*.jsonl |
5.2 导出文件格式
默认导出为Markdown文件，保存路径通常为：
~/Desktop/Claude logs/claude-conversation-YYYY-MM-DD-XXXXXX.mdMarkdown 格式已清理了终端转义码和 ANSI 颜色代码，保留了纯净的对话内容，适合直接阅读或导入到 Obsidian、Notion 等笔记软件中。
六、进阶用法
6.1 配合 Obsidian 构建知识库
你可以将导出的 Markdown 文件自动导入 Obsidian 等笔记软件，构建个人 AI 对话知识库。具体流程包括：
- 创建导出目录：
mkdir -p ~/claude-exports - 定期执行
claude-extract --all --output ~/claude-exports - 编写后处理脚本，自动添加 YAML frontmatter 和标签
- 通过 cron 定时任务实现每日自动备份
6.2 语义搜索（可选增强）
如果你需要更强大的语义搜索能力，可以安装 spaCy：
pipinstallspacy python-mspacy download en_core_web_sm安装后，搜索功能将支持基于语义的理解，而不仅仅是关键词匹配。
七、常见问题排查
7.1 提示 “No Claude sessions found”
- 确认使用过 Claude Code：该工具仅适用于 Claude Code 的命令行版本，不适用于 claude.ai 网页版。你必须至少成功运行过一次
claude命令。 - 检查日志目录是否存在：
ls-la~/.claude/projects/# macOS/Linuxdir%USERPROFILE%\.claude\projects\# Windows - 确认权限：确保当前用户有读取
~/.claude/projects/的权限。
7.2 命令找不到（command not found）
macOS/Linux：
# 将 ~/.local/bin 加入 PATHecho'export PATH="$HOME/.local/bin:$PATH"'>>~/.zshrcsource~/.zshrcWindows：
# 将 Python Scripts 目录加入环境变量setx PATH"%PATH%;C:\Users\YourName\AppData\Local\Programs\Python\Python311\Scripts"7.3 安装后无法运行
# 验证安装pipx list|grepclaude# 或pip show claude-conversation-extractor# 查看帮助claude-extract--helpclaude-extract--version八、隐私与安全说明
该工具在设计上充分考虑了隐私保护：
- ✅100% 本地运行：所有处理都在你的机器上完成，不会发送任何对话内容到外部服务器
- ✅无需联网：安装后完全离线工作
- ✅无遥测：不包含任何追踪、分析或数据收集
- ✅开源可审计：源代码托管在 GitHub 上，可自由审查
- ✅只读访问：仅读取 Claude Code 的日志文件，不会修改或删除原始数据
九、总结
Claude Conversation Extractor 填补了 Claude Code 生态中对话管理的空白，让你能够真正"拥有"自己的 AI 对话数据。无论是日常备份、知识归档，还是配合笔记软件构建第二大脑，这款工具都能胜任。
如果你在使用过程中遇到问题，可以访问项目仓库提交 Issue 或参与贡献：
- GitHub 仓库：https://github.com/ZeroSumQuant/claude-conversation-extractor
- 当前版本：v1.1.0+（截至 2025 年 9 月）
