Chat2Local

<h1 align="center">Chat2Local</h1> <p align="center"> <strong>简体中文</strong> · <a href="https://github.com/mmc-cloud/Chat2Local/blob/master/README.en.md">English</a> </p> <p align="center"> <a href="https://pypi.org/project/chat2local/"><img src="https://img.shields.io/pypi/v/chat2local" alt="PyPI"></a> <a href="https://pypi.org/project/chat2local/"><img src="https://img.shields.io/pypi/pyversions/chat2local" alt="Python"></a> <a href="https://github.com/mmc-cloud/Chat2Local/actions/workflows/test.yml"><img src="https://github.com/mmc-cloud/Chat2Local/actions/workflows/test.yml/badge.svg" alt="Tests"></a> <a href="https://github.com/mmc-cloud/Chat2Local/blob/master/LICENSE"><img src="https://img.shields.io/pypi/l/chat2local" alt="License"></a> </p> <p align="center"><strong>让 ChatGPT 通过 MCP 访问并操作你授权的本地电脑和项目。</strong></p>

Chat2Local 是一个面向单用户、自托管场景的轻量 MCP Agent。它可以读取和修改本地文件、运行命令、管理长时间运行的进程，并通过 Hub + Agent 模式连接多台电脑或服务器。

项目同时提供 Core / CLI 和 Windows Desktop：前者适合开发者、服务器和命令行环境，后者在同一套 Core 外提供图形化管理、系统托盘、日志和 portable EXE。

额度变更提醒： OpenAI 宣布，从 12 月起，Plus、Pro、Business 的 ChatGPT 与 Codex 将共用按 Token 计量的额度。这意味着，此前在 Chat 模式下使用 Sol 高推理时近乎无限的使用体验将受到限制；Instant 聊天不受此次额度计量影响。查看官方公告

Features

你可以直接在 ChatGPT 中让它：

• 阅读和搜索本地项目代码，而不需要反复上传文件
• 修改文件、应用 patch，并继续检查修改结果
• 运行测试、构建、脚本或其他 Shell 命令
• 查看长时间运行进程的输出，并继续与进程交互
• 在多台电脑或服务器之间选择目标设备执行操作
• 通过 Handoff 保存项目工作线或个人研究、计划和想法，让新的 Chat 继续之前的上下文
• 通过可选 Chrome 扩展读取和操作网页，支持 DOM 探查、点击、输入和滚动

Chat2Local 主要围绕 ChatGPT + MCP 的实际工作流开发和测试。其他支持 MCP 的客户端也可以连接，但目前不是主要测试目标。

架构

单设备时，ChatGPT 直接连接 Chat2Local：

ChatGPT
   │ MCP / HTTPS
   ▼
Chat2Local
   │
   └── Local workspace / processes

多设备时，由 Hub 提供统一 MCP endpoint，各 Agent 主动连接 Hub：

                    ┌── Hub local workspace
                    │
ChatGPT ── MCP ──▶ Hub
                    │
                    ├── Agent: Windows PC
                    ├── Agent: Server
                    └── Agent: Other device

Agent 不对 ChatGPT 暴露 MCP endpoint，也不需要对公网开放入站端口；它只需要能够主动连接 Hub。

安装

Windows Desktop

Windows 用户可以从 GitHub Releases 下载：

Chat2Local-v<version>-windows-x64.zip

解压后直接运行：

Chat2Local.exe

portable 版本已经包含 Python runtime、Core 和 Desktop GUI，不要求系统预先安装 Python。

Core / CLI

Core 要求 Python 3.12+。

独立 Core 在 Windows、Linux、macOS 上均自带本地 Web UI。启动后可在浏览器访问 http://127.0.0.1:8767/（实际地址也会写入日志），管理配置、日志、设备、Token 和自启。 Browser Bridge 固定使用用户配置的端口（默认 8766）。Web UI 未指定端口时从 8767 起最多尝试 10 个端口， 成功后显示实际地址；通过配置或 CLI 显式指定端口时不自动回退。 运行时无需 Node.js；详见本地 Web UI 与跨平台自启。原 Windows ZIP / EXE 使用方式保持不变。

推荐使用 uv tool 安装到独立环境：

uv tool install chat2local
chat2local --help

也可以使用 pip：

python -m pip install chat2local
chat2local --help

快速开始

Standalone

在希望授权给 Chat2Local 的目录中运行：

chat2local

也可以显式指定 workspace：

chat2local --workspace D:\Projects\example

如果不传 --workspace，启动时的当前目录就是默认 workspace。

Hub + Agent

Hub：

$env:CHAT2LOCAL_HUB_TOKEN = '<shared-secret>'
chat2local hub --device-id hub --host 127.0.0.1 --port 8765

Agent：

$env:CHAT2LOCAL_HUB_TOKEN = '<shared-secret>'
chat2local agent --device-id desktop --hub-url wss://hub.example.com/device/ws

Hub 和 Agent 使用同一个 shared token。公网 Agent 应使用 wss://。

上面的 Hub 示例只监听 loopback。只有在已经配置防火墙、TLS 反向代理或其他可信网络边界时， 才应把 Hub 直接监听到 0.0.0.0。CHAT2LOCAL_HUB_TOKEN 只保护 Hub ↔ Agent 的 /device/ws， 不会保护 MCP /mcp endpoint；公网 MCP endpoint 应另外启用 OAuth 或可信的外部访问控制。

连接到 ChatGPT

ChatGPT Web 不能直接访问 localhost 上的 MCP Server，因此需要为 Chat2Local 提供一条 ChatGPT 可以使用的连接路径。

OpenAI Secure MCP Tunnel

对于个人使用、本地开发或不希望把 MCP Server 暴露到公网的场景，可以使用 OpenAI 官方的 Secure MCP Tunnel。

tunnel-client 运行在能够访问 Chat2Local 的机器或网络中，并主动通过 HTTPS 连接 OpenAI。这样 Chat2Local 本身不需要开放公网入站端口，也不需要拥有公开 HTTPS 地址。

典型结构：

ChatGPT
   │
   │ OpenAI Secure MCP Tunnel
   ▼
tunnel-client
   │
   ▼
Chat2Local /mcp

在 ChatGPT 中创建自定义 MCP Server / Plugin 时，Connection 选择 Tunnel，再选择或填写对应的 tunnel_id 即可。

Standalone 模式下，tunnel-client 可以直接运行在本机；Hub + Agent 模式下，可以把它运行在 Hub 所在机器或其他能够访问 Hub MCP endpoint 的环境中。

Secure MCP Tunnel 适合私有连接和开发测试；如果准备公开发布 Plugin，则仍需要稳定、可公网访问的 HTTPS MCP endpoint。

公网 HTTPS endpoint

另一种方式是通过反向代理、隧道服务或自己的域名，把 Chat2Local 的 MCP endpoint 暴露为公网 HTTPS 地址，例如：

https://mcp.example.com/mcp

然后在 ChatGPT 中创建自定义 MCP Server / Plugin，并填写该 Server URL。公网部署建议启用 HTTPS，并配置 OAuth 或其他可信的访问控制。

连接成功后，可以先让 ChatGPT 读取当前 workspace，或者调用 list_devices 验证 Chat2Local 是否已经正常连接。

MCP Tools

Chat2Local 当前公开 12 个 MCP tools，覆盖文件读取与搜索、patch 修改、Shell / Process 操作、多设备选择、Handoff 和可选扩展能力。

capability_discover 默认以 summary 查询指定设备的能力概览和实时可用状态；选中能力后用 detail: "full" 查询参数 JSON Schema、结果契约和恢复指导，再通过 capability_execute 执行。 浏览器提供 28 个内部能力，包括标签页创建/查询/选择与激活/关闭/移动/固定、普通窗口查询/创建/聚焦/安全关闭、基础导航及状态查询/有限等待、独立授权的标签分组及书签查询与管理，以及网页读取/定位、点击/填写、双击/悬停/聚焦、原生选择/勾选、滚动、合成按键和元素状态等待。 这些能力均通过已配对的可选 Chrome 扩展执行，网页内容读取与 DOM 操作还需按网站授权。窗口标签概要支持有界分页，续页使用精确窗口和无状态快照标识核验集合/顺序；关闭整个窗口前由上层 Agent 在对话中取得确认，并独立校验完整标签页 ID 集合。基础导航执行前复核目标，只表示已发起，不等待加载。默认不启动浏览器监听；扩展未连接不会影响原有工具。 Chrome 扩展 ZIP 可从 GitHub Releases 下载；安装与配对见 浏览器扩展说明。 导航等待默认 5 秒、上限 8 秒，Chrome complete 不等于 SPA 业务就绪；旧页面 complete 不会自动作为新导航完成证据。分组功能使用独立可选 tabGroups 权限，只能由用户在扩展设置页点击授权；多步操作部分失败会报告已完成步骤，不自动回滚或重试。 观察后等待 URL 变化时，使用 navigation.status 返回的短期随机 url_baseline_id，绑定精确标签和完整 URL，避免脱敏显示 URL 导致误判；独立知道精确 URL 时仍可使用互斥的 baseline_url。分组移动会核验实际位置及成员连续性，允许 Chrome 合法调整索引并返回 actual_index，未达到位置时不误报成功。

书签采用独立可选授权，支持分页查询、精确字符串 ID 管理，以及完整预览后在对话中确认的递归删除。根/内置/受管理节点受保护；删除前重新核验完整内容和层级快照，失败或结果不确定时不自动重试。

当前公开的 Tool：

read · search · apply_patch · exec_command · interact_process
kill_process · list_devices · handoff_list · handoff_get · handoff_save

远程调用可以通过 device 指定目标设备；省略时使用当前 MCP Server 所在设备。

普通命令的输出会持续读取到 EOF。显式调用 kill_process 或停止 Core 时，在父进程退出、进程树信号处理结束后，最多再等待 1 秒读取输出；后代仍持有继承的 stdout/stderr 管道时，Chat2Local 会关闭本端读端，并用 output_incomplete: true 标记已保留的输出。此项清理不会向已经退出的父进程旧 PID 发送信号，但后代继续写入时可能发生写入错误甚至异常退出，不能保证其继续正常运行。需要独立运行的后台程序应在启动时将 stdin、stdout、stderr 重定向到独立文件或 DEVNULL。返回的 state / exit_code 描述所启动的父进程，output_incomplete 描述输出完整性，均不代表后代任务的健康状态。

三个 Handoff Tool 均接受可选的 scope：默认 "workspace" 按项目工作区保存，兼容旧调用； 没有具体项目归属的研究、计划或初步想法使用 "personal"，无需 Workspace，也不能显式传入 workspace（包括 null）。两种作用域允许相同的 Workstream ID，记录彼此独立。

记录均使用 Markdown，保存在选定设备的用户数据目录中：Workspace 使用 ~/.chat2local/handoffs/<workspace-key>/，Personal 使用 ~/.chat2local/handoffs/_personal/。 现有文件无需迁移，各设备之间不自动同步。先用 handoff_list 查看标题和摘要，再按需 handoff_get 读取正文；handoff_save 用 expected_revision=0 新建，更新使用最新 revision。

配置

默认配置文件：

~/.chat2local/config.yaml

完整示例见 config.example.yaml。

一个最小的 Hub / Agent 配置示例：

hub:
  device_id: hub
  host: 127.0.0.1
  port: 8765
  token_file: ~/.chat2local/hub.token

agent:
  device_id: desktop
  hub_url: wss://hub.example.com/device/ws
  token_file: ~/.chat2local/hub.token
  proxy: system

security.allowed_roots 用来限制本机可选择的 workspace 范围。默认值 [] 不代表开放整个文件系统，而是只授权启动时的默认 workspace。

CLI 参数只覆盖当前启动，不会自动写回 config.yaml。Windows Desktop 的 Settings 可以编辑持久化配置。

进阶配置

Chat2Local 还支持：

• Agent → Hub 使用系统代理、直连或显式 HTTP / HTTPS / SOCKS4 / SOCKS5 代理
• Standalone / Hub MCP HTTP endpoint 启用 OAuth Resource Server 模式
• 当前 OAuth provider 支持 WorkOS AuthKit

Core / CLI 使用 SOCKS 时需要额外安装 python-socks[asyncio]；Windows Desktop portable 已内置该依赖。

安全模型

Chat2Local 提供明确的应用级访问边界，但它不是 OS sandbox。

• 文件工具始终限制在当前 workspace 内
• workspace 必须位于本机允许的 security.allowed_roots 内
• 阻止通过 ..、workspace 外绝对路径、symlink / junction 逃逸
• exec_command 仍拥有 Chat2Local 当前 OS 用户的权限
• Agent shared token 只保护 Hub ↔ Agent 连接
• 公网 MCP endpoint 应使用 HTTPS，并配置 OAuth 或可信的外部访问控制
• 日志不会记录 token、完整认证 payload 或 Tool 参数内容

如果需要更强隔离，应配合独立 OS 用户、容器、虚拟机或其他系统级机制使用。

Windows Desktop

Desktop GUI 当前提供：

• Core 状态和 Standalone / Hub / Agent 启停
• workspace 选择
• Hub 在线设备列表
• config.yaml 设置编辑
• Core 日志查看
• Windows 系统托盘
• 登录启动与静默启动
• Core 自动启动
• 简体中文 / English
• single-instance

关闭窗口默认隐藏到系统托盘；退出 Desktop 不会自动停止正在运行的 Core。

Desktop 的开发与打包说明见 gui/pywebview/README.md。

从源码运行与构建

如果你希望直接从仓库运行、测试或修改 Chat2Local，克隆仓库后：

uv sync
uv run pytest

构建 Windows portable：

uv sync --group pywebview-gui --group desktop-build
uv run --group pywebview-gui --group desktop-build python scripts/build_windows.py

输出目录：

dist/windows/Chat2Local/

License

Chat2Local 使用 MIT License。