Keyhole 是一个小型 MCP 服务器，运行在你的 Mac、Linux 或 Windows 电脑上，同时提供名为 keyhole 的命令行工具。你通过 keyhole open 打开一个文件夹，网页版 ChatGPT 即可经由 OpenAI 官方 Secure MCP Tunnel 读取它；若给文件夹授予 rw 权限，ChatGPT 还能在其中创建和编辑文本文件。每次编辑都会与文件当前哈希进行比对，并在应用前记录，单个文件替换是原子的，保留下来的变更可以在不覆盖后续编辑的情况下恢复。
该项目为非官方项目，与 OpenAI 无关联。
主要能力
- 默认只读：只有你打开文件夹后 ChatGPT 才能看到它；在你说 --access rw 之前，ChatGPT 无法修改文件。ChatGPT 自身无法扩大权限，授权只由本地 CLI 管理。
- 可撤销的谨慎编辑：写入需要文件当前 SHA-256；基于过期哈希的更新会被拒绝。先前内容保存在私有本地历史中，restore_change 可将其回滚。
- 多文件夹与多种文件格式：可独立打开多个文件夹，各自拥有 ro/rw 权限。文本、PDF、Word、PowerPoint、Excel 和图片返回时带哈希和范围，答案可以引用所读内容。文档解析器有 CPU、时间和输入大小限制，但以你的操作系统权限运行，并非操作系统沙箱。
- 连接使用 OpenAI 官方客户端：不暴露公网端点，也没有远程 shell。关闭最后一个文件夹，隧道即停止。
使用方式
- 在终端中允许示例文件夹被编辑。一次性设置会创建 ~/KeyholeDemo，内含虚构的 notes.md，并以只读方式共享为 demo。编辑需要显式的本地命令。
- 在 ChatGPT 中选择你的 Keyhole 应用并提出请求，例如：Read notes.md in demo, turn its three ideas into TODO checkboxes, and save the file.
- 回到终端检查同一文件，三个想法现在含有复选框。 可要求 ChatGPT 恢复返回的 change id；完成后运行 keyhole close demo 停止共享文件夹。
设置向导可下载经校验的官方客户端、恢复未完成的配置并打开只读示例。若 PyPI 不可用，可使用 GitHub Releases 中的确切 wheel URL。Windows 上请改用 PowerShell 指南，其安装命令会请求 Keyhole 依赖所需的 x64 Python，在 x64 和 ARM 电脑上均如此。首次完整流程约需 15 分钟（账号访问就绪后）：检查账号访问、安装工具、连接你自己的隧道、创建私有 ChatGPT 应用、读取真实示例文件。无需安装 Python、Git、Node、Docker 或 tmux。需要 macOS、Ubuntu Linux 或 Windows 11、ChatGPT 开发者模式，以及创建 OpenAI Platform 隧道和受限运行时密钥的权限。
GitHub 仓库提供软件。你需要创建自己的隧道和私有 ChatGPT 应用；不存在一键添加的公开 Keyhole 应用。OpenAI 的 Secure MCP Tunnel 用于私有连接，而非公开插件商店分发。
适用场景
- 独立打开多个文件夹，保持部分只读，在另一些中允许可恢复的文本编辑。
- 既读文档也读源码，任务完成后关闭文件夹。文件夹访问始终由你本地控制。
- 示例请求：读取 app/src/config.py，修正错误信息中的拼写错误，然后读回文件确认；在 notes 中搜索“invoice”，然后引用匹配行及其文件路径。
写入行为：编辑时 ChatGPT 读取文件及其哈希、提出更改，并调用 apply_text_patch 或 write_file。ChatGPT 是否在写入前询问你，取决于 ChatGPT 对应用自身的设置（默认会询问，且可在一次对话中记住你的回答）；若你从未看到提示，请检查应用详情。
各文件类型能力 复制、移动、删除和恢复将每个不超过 8 MiB 的常规文件视为不透明字节，因此对二进制文件也适用。Keyhole 无法写入 Office 文档、PDF 或图片，也不运行代码、宏或公式。
限制：文本文件最大 8 MiB；文档和图片最大 64 MiB；每次读取 400 行或 64 KiB；每次 write_file 1 MiB；仅限单个文件，无递归目录操作。每个响应会说明何时被截断。
恢复历史 ChatGPT 所做的每项更改都会在文件被触及前写入 ~/.config/keyhole/changes.sqlite3（仅你可读）：路径、哈希，以及默认的先前内容。restore_change 和 keyhole history 使用这些数据。ChatGPT 能看到路径、哈希和 change id，但永远看不到存储的内容。
历史记录上限为 1000 条或 450 MiB。写满时，最旧的已完成记录被自动丢弃；被中断的操作永不丢弃。恢复可临时预留一条额外记录和 48 MiB，以免历史写满妨碍修复。使用相同请求 id 重试被中断的恢复；恢复成功后历史回到正常上限。
关闭或遗忘文件夹会保留其历史。keyhole purge-history --before 2026-01-01 --confirm 会删除某日期之前的已完成记录。逐出或清除会同时移除这些记录的恢复与重放保护；历史不是永久审计日志。
若你偏好自己的版本控制，keyhole open <dir> --access rw --recovery off 只保留路径和哈希。编辑仍会经过哈希校验，被中断的操作仍可修复，但 restore_change 会拒绝该文件夹的已提交编辑。
安全设定 授权保存在 ~/.config/keyhole/grants.json，仅通过 keyhole 更改。没有远程工具可添加文件夹、运行命令、使用 Git 或获取 URL。
诸如 .git、.ssh、.env*、.key、.pem、credentials.json、node_modules 以及 agent 状态目录等名称，在任何深度、任何大小写下都会被隐藏。keyhole open 会打印完整列表。
自定义 --exclude 规则：不含斜杠的模式在任何深度隐藏匹配名称（Private、.log）；含斜杠的模式锚定在文件夹根并隐藏该子树（Secret/、docs/*.md）。匹配忽略大小写和 Unicode 规范化。
ChatGPT 永远无法修改 Keyhole 自身的代码或环境、状态目录，或 .zshrc、.envrc 等 shell 启动文件，无论其使用路径的哪种写法。
符号链接、硬链接文件和特殊文件会被拒绝。路径在 macOS/Linux 上使用 O_NOFOLLOW 逐组件打开，在 Windows 上使用父目录句柄，并在每次操作前后重新检查。
按文件名隐藏不等于机密检测：共享源文件中的令牌在文件夹打开期间可被读取，且任何已发送给 ChatGPT 的内容无法通过关闭文件夹召回。威胁模型、范围外内容及漏洞报告方式见 SECURITY.md。
命令与工具 命令默认打印 JSON；"ok": false 会附带可据此处理的 error.code。status --human 打印可读文本。上述设置/状态选项需要 Keyhole 0.4.0 或更高版本。
五个读取工具标记为只读，七个写入工具标记为破坏性，这正是 ChatGPT 写入确认的依据。完整参数、错误码和限制见 docs/reference.md。升级、自定义路径和卸载见 maintenance。
术语与故障排查 Workspace：一个已打开的文件夹，以名称显示给 ChatGPT。并非 ChatGPT workspace（团队账号）。 ro / rw：只读 / 读写。新文件夹为 ro。 Runtime：保持隧道连接并运行 Keyhole 服务器的 tunnel-client 进程。 Chat vs Work：ChatGPT 的撰写模式。Keyhole 在纯 Chat 模式下测试；不需要 Work。
非目标及何时改用其他方案 Keyhole 不会运行 shell 命令、测试或 Git，不会控制你的屏幕，不会暴露公网端点，也不会让远端管理授权。若你使用 ChatGPT 桌面应用，其本地 Work 模式可能已在此机器上满足需求。若想让 ChatGPT 在仓库中运行命令，请使用面向编码的工具。Keyhole 面向网页版 ChatGPT、作为证据的文档，以及谨慎编辑。
可选：Codex 配套 skills/keyhole/ 是一个面向 OpenAI Codex 的技能，可让它在你明确指示下运行 keyhole 并解释边界。将该目录链接到 ~/.codex/skills/（Codex 发现的布局）；.codex-plugin/plugin.json 为 Codex 插件安装器描述同一技能。ChatGPT 不需要它。
跟踪内容：服务器和 CLI（src/keyhole/）、测试、文档、Codex 技能。运行时状态、密钥、授权和恢复历史存放在 ~/.config/keyhole/，从不属于仓库。
由 Jovi 维护；尽力而为，单一维护者。缺陷和想法见 issues。如何开发见 CONTRIBUTING.md。变更见 CHANGELOG.md。
