TangleClaw v3：基于tmux的本地AI编码会话持久化与编排平台

1. 项目概述：一个为AI编码会话打造的本地化指挥中心

如果你和我一样，日常开发已经离不开Claude Code、Codex或者Aider这类AI编码助手，那你肯定也经历过那种让人抓狂的瞬间：正和AI聊得火热，它已经理解了你的项目架构，写了几百行代码，突然网络波动了一下，SSH连接断了，或者你只是合上了笔记本盖子。等你重新连回去，刚才那个充满“上下文”的会话已经烟消云散，一切都要从头开始解释。这种体验就像是在沙滩上写字，一个浪头打来就全没了。

TangleClaw v3就是为了彻底解决这个问题而生的。它本质上是一个本地部署的AI编码会话编排器。它的核心魔法是会话持久化：通过将每个AI编码助手的进程包裹在tmux会话中，确保即使你的客户端连接完全断开，服务器端的AI会话依然在后台安静地运行。你可以用电脑开始一个会话，然后关掉电脑，拿起手机，在同一个Wi-Fi网络下打开浏览器，无缝接上刚才的对话，AI助手完全察觉不到你离开过。

但TangleClaw的野心远不止于此。一旦解决了“不断线”这个基本问题，很多更高级的需求就自然浮现了。比如，你希望有一个统一的仪表盘来管理手头所有的项目；你希望你的开发方法论（比如TDD、特定代码规范）能被强制执行，而不是作为建议被AI忽略；你希望Claude、Codex、Gemini这些不同引擎的配置能自动同步，不用维护好几套文件；你还希望管理端口冲突、从手机访问、检测会话闲置……TangleClaw把这些功能全部打包，形成了一个运行在你本地机器上的完整平台。它就像一个位于你和各种AI编码助手之间的智能中间层，通过浏览器即可访问，让你能从任何设备、任何地方，以一致、可控的方式与AI协同编码。

2. 核心功能深度解析：不止于“不断线”

2.1 会话持久化：tmux的妙用与实现细节

TangleClaw实现会话持久化的核心是tmux（Terminal Multiplexer）。这是一个在Unix-like系统中广泛使用的工具，允许用户在单个终端窗口内创建多个“窗格”或“窗口”，更重要的是，这些会话可以脱离当前终端连接而独立存在。

它是如何工作的？当你通过TangleClaw仪表盘为一个项目启动一个AI引擎（比如Claude Code）时，后台实际执行的操作是：

1. 在服务器上创建一个新的、唯一命名的tmux会话。
2. 在该tmux会话中，启动指定的AI引擎CLI进程。
3. 通过ttyd（一个将终端转换为Web应用的工具）将这个tmux会话的输入/输出流映射到一个WebSocket端口。
4. 你的浏览器通过TangleClaw的反向代理连接到这个WebSocket，从而与AI进程交互。

关键在于，tmux会话的生命周期与你的浏览器连接解耦了。即使你关闭浏览器标签页、断开Wi-Fi，甚至重启TangleClaw的Web服务（只要不重启tmux服务），那个tmux会话以及其中运行的AI进程依然在后台存活。当你重新打开TangleClaw并进入该项目时，它会自动帮你“附着”（attach）到那个已有的tmux会话，所有历史输出和上下文瞬间恢复。

实操心得：确保你的tmux版本较新（建议通过brew install tmux安装），并理解tmux的基本命令（如tmux ls查看会话，tmux attach -t <session-name>手动附着）对于调试非常有帮助。有时AI进程卡死，你可能需要手动进入tmux会话去终止它。

2.2 多引擎统一管理与原生配置生成

支持多个AI引擎并不稀奇，但TangleClaw做得更深入。它内置了对Claude Code、OpenAI Codex、Google Gemini CLI、Aider以及OpenClaw的支持。其精髓在于**“一次编写，处处生效”**的规则配置。

传统痛点：每个AI引擎都有自己的配置文件格式和指令风格。比如，你想让AI遵循“每次修改前先写测试”的规则，你需要在Claude Code的CLAUDE.md里写一套，在Aider的.aider.conf.yml里再写一套，格式完全不同，维护起来很麻烦。

TangleClaw的解决方案：

1. 统一规则定义：你在TangleClaw的“方法论”（Methodology）中，以结构化的JSON模板定义开发阶段、规则和钩子函数。
2. 动态配置生成：当你为一个项目选择某个方法论和AI引擎后，TangleClaw会在运行时，根据该引擎的“配置文件模板”（Engine Profile），将通用的规则“编译”成该引擎原生支持的配置文件格式。
3. 自动注入：在启动AI会话时，这个新生成的配置文件会被放置在项目的正确位置（或通过环境变量、命令行参数注入），确保AI助手一启动就运行在你定义的规则之下。

这意味着，你只需要在TangleClaw中维护一套核心的开发规则，它就能自动适配到你所有的AI编码工具上，极大地降低了管理成本。

2.3 方法论强制执行：从建议到规则

“方法论”是TangleClaw中一个非常强大的概念。它超越了简单的“提示词工程”，将开发流程结构化、可执行化。

一个典型的方法论模板（JSON格式）可能包含：

• 阶段（Phases）：如“发现”、“规划”、“构建”、“审查”。
• 规则（Rules）：每个阶段下具体的约束，例如：“在‘构建’阶段，任何对src/目录下.js文件的修改，都必须先存在对应的test/目录下的.test.js文件”。
• 动作（Actions）：规则触发时执行的操作，比如“阻止提交并返回错误信息”。
• 钩子（Hooks）：在会话开始、结束或阶段转换时运行的脚本，用于更新项目状态、生成报告等。

与Prawduct的深度集成：TangleClaw对 Prawduct （一个强调“规划-构建-审查”分离的AI开发框架）提供了开箱即用的支持。如果系统检测到Prawduct已安装，TangleClaw会自动将其工作流集成进来，实现由独立“评审者”（Critic）AI进行代码审查的治理模式。

注意事项：方法论中的规则是“结构性门禁”，AI无法轻易绕过。这要求你在定义规则时必须非常精确，否则可能会过度限制AI的能力。建议从简单的规则开始，逐步增加复杂度，并充分利用TangleClaw提供的“启动模式”来在不同严格度间切换。

2.4 启动模式：精细化的会话权限控制

不是所有编码任务都需要AI拥有同样的自主权。为此，TangleClaw引入了“启动模式”（Launch Modes），让你在开始会话时就能设定好本次协作的“基调”。

• 交互模式（Interactive）：AI的每一个动作（读文件、写文件、运行命令）都需要你手动批准。适合探索性、高风险的操作。
• 接受编辑模式（Accept Edits）：自动批准文件读取和编辑请求，但运行命令仍需确认。平衡了效率与控制。
• 仅规划模式（Plan Only）：AI只能读取文件和分析，不能做任何修改。适合代码审查或架构设计讨论。
• 自动模式（Auto）：AI拥有较高自主权，但TangleClaw内置的安全分类器会拦截可疑操作（如rm -rf /）。适合成熟的、模式固定的任务。
• 绕过模式（Bypass）：完全信任AI，所有操作自动批准。仅建议在容器或虚拟机等隔离环境中使用。

这个功能将AI从“一刀切”的工具，变成了一个可以根据任务风险动态调整的、拥有不同“权限等级”的合作伙伴。

2.5 项目组与共享文档：上下文联动

在实际开发中，我们经常同时进行多个关联项目（比如一个前端Repo、一个后端Repo、一个共享组件库）。TangleClaw的“项目组”功能允许你将它们逻辑上分组。

共享文档是此功能的核心。你可以在组内创建共享的Markdown文档（如架构设计.md、API约定.md）。这些文档会被自动同步到组内每个项目的.tangleclaw/目录下。当你在任何一个项目的AI会话中启动时，这些共享文档会作为上下文的一部分被注入给AI。

更妙的是文档锁：当某个会话正在编辑一份共享文档时，该文档会被锁定，防止组内其他会话同时修改造成冲突。这为跨项目的AI协同提供了基础的协作协议。

2.6 会话记忆与项目版本检测

会话记忆：TangleClaw在每个项目根目录下维护一个.tangleclaw/memories/文件夹，其中MEMORY.md是索引文件。AI在会话中总结的“经验教训”、“待办事项”、“项目特定知识”都可以被引导记录在这里。这个记忆文件会被注入到后续所有会话的上下文中，实现了跨会话的、项目专属的知识积累。

通用项目版本检测：为了在仪表盘上清晰展示每个项目的状态，TangleClaw实现了一个智能的版本检测链。它会按以下顺序查找版本号：

1. .tangleclaw/project-version.txt(由AI在会话总结时记录)
2. CHANGELOG.md(解析最新的版本条目)
3. version.json
4. package.json

这种设计兼容了不同语言、不同团队的项目管理习惯，确保仪表盘上的版本信息总是准确且有意义的。

3. 从零开始部署与配置实战

3.1 环境准备与依赖安装

TangleClaw目前仅支持macOS，因为它依赖launchd进行服务管理。Linux支持已在规划中。

核心依赖清单：

1. Node.js 22+：TangleClaw使用Node.js 22的node:sqlite和node:test等内置模块，实现“零依赖”。可通过nvm或官网安装包安装。
2. ttyd：用于提供浏览器内的终端访问。brew install ttyd
3. tmux：会话持久化的基石。brew install tmux
4. 至少一个AI引擎CLI：根据你的偏好安装，例如：
   • Claude Code:npm install -g @anthropic-ai/claude-code
   • Aider:pip install aider-chat（请务必参考各引擎官方文档完成API密钥等基础配置）

可选依赖：

• Prawduct:pip install prawduct(用于治理工作流)
• OpenClaw: 用于连接远程AI代理实例，需单独部署。
• mkcert:brew install mkcert(用于一键生成本地HTTPS证书)

3.2 一键安装与服务部署

TangleClaw的安装过程被高度自动化。

# 克隆仓库 git clone https://github.com/Jason-Vaughan/TangleClaw.git cd TangleClaw # 运行安装脚本 ./deploy/install.sh

这个install.sh脚本会完成以下关键操作：

1. 环境检查：验证Node.js版本、ttyd、tmux等是否已安装。
2. 生成launchd配置文件：根据当前用户的路径，生成com.tangleclaw.server.plist和com.tangleclaw.ttyd.plist文件，并放置到~/Library/LaunchAgents/。
3. 加载服务：使用launchctl load命令将这两个服务注册到当前用户的launchd中，并设置开机自启。
4. 健康检查：尝试访问本地服务端点，确认安装成功。

安装完成后，TangleClaw的服务器和ttyd服务就已经在后台运行了。你可以通过launchctl list | grep tangleclaw来查看服务状态。

3.3 首次运行与初始化向导

打开浏览器，访问http://localhost:3102。你会看到TangleClaw的引导页面，并自动启动首次运行设置向导。

这个向导会引导你完成几个关键配置：

1. 选择项目目录：这是最重要的设置。指定一个文件夹（例如~/Developer或~/Projects）作为TangleClaw管理的根目录。TangleClaw会扫描此目录，自动识别其中的Git仓库和已配置的AI引擎。
2. HTTPS设置（推荐）：向导会检测你是否安装了mkcert。如果已安装，它会引导你一键为localhost生成受信任的证书，并自动将TangleClaw切换到HTTPS模式（https://localhost:3102）。这对于后续使用OpenClaw的Web UI配对功能是必需的，也提升了本地通信的安全性。
3. 默认引擎与方法论：设置新项目创建时的默认AI引擎和开发方法论模板。

完成向导后，你的主仪表盘就会显示在扫描到的项目目录中发现的所有项目。你可以选择“附加”（Attach）现有项目，或创建新项目。

3.4 核心配置文件详解

TangleClaw的全局配置位于~/.tangleclaw/config.json。理解这些配置项有助于高级定制：

{ "serverPort": 3102, // Web仪表盘服务端口 "ttydPort": 3101, // ttyd终端服务端口 "projectsDir": "/Users/yourname/Projects", // 项目根目录 "defaultEngine": "claude", // 默认引擎 (claude, codex, gemini, aider, openclaw) "defaultMethodology": "standard", // 默认方法论模板 "deletePassword": "your-secure-password", // 删除操作密码（非访问控制） "httpsEnabled": true, // 启用HTTPS "httpsCertPath": "/Users/yourname/.tangleclaw/certs/cert.pem", // 证书路径 "httpsKeyPath": "/Users/yourname/.tangleclaw/certs/key.pem" // 私钥路径 }

重要安全提示：deletePassword仅用于保护删除项目、重置数据等破坏性操作。TangleClaw本身不提供用户认证。这意味着任何能访问http(s)://your-machine-ip:3102的人都能看到你的项目和启动终端会话。因此：

• 强烈建议启用HTTPS。
• 仅在受信任的局域网内运行，或通过Tailscale、Zerotier等组建虚拟专用网络访问。
• 切勿将TangleClaw的服务端口暴露在公网。

4. 日常使用工作流与高级技巧

4.1 典型工作流：从启动到收尾

1. 项目接入：在仪表盘，点击“附加项目”，选择一个已有代码库的文件夹。TangleClaw会为其生成.tangleclaw/目录，包含记忆文件和初始配置。
2. 启动会话：点击项目卡片上的“启动会话”。在弹出的模态框中，选择本次要使用的AI引擎（如Claude Code）和启动模式（如“接受编辑”）。
3. 协同编码：浏览器中会打开一个新的标签页，里面是一个功能完整的终端，AI助手已经就绪。你可以像在本地终端一样与它对话，它会在你设定的规则下工作。
4. 多设备切换：如果你要离开办公桌，直接关闭这个浏览器标签即可。AI会话在服务器的tmux中持续运行。在手机上打开浏览器，输入你电脑的本地IP和端口（如https://192.168.1.100:3102），登录TangleClaw，进入同一个项目，点击“恢复会话”，刚才的对话和终端输出完整呈现。
5. 会话总结：工作完成后，在终端中输入TangleClaw约定的结束命令（例如/wrap），会触发结构化会话收尾。AI会帮助你更新CHANGELOG.md、将本次学到的要点写入.tangleclaw/memories/、并更新项目版本。最后，会话会被安全地终止（tmux会话结束）。

4.2 PortHub：智能端口冲突管理

这是一个集成但非常实用的功能。当你的多个项目都需要启动本地开发服务器（如React on:3000, Node.js on:3001）时，手动管理端口非常容易冲突。

TangleClaw内置的PortHub维护了一个中央端口注册表。任何通过TangleClaw启动的、需要占用端口的进程（比如你在会话中让AI启动一个本地服务器），都应该通过PortHub API“租用”一个端口。PortHub会确保这个端口在当前系统上没有冲突（通过lsof检测），并可以设置租约期限和心跳检测，避免端口被长期占用。

在仪表盘的“PortHub”页面，你可以清晰看到所有项目的端口租用情况，及时发现冲突。

4.3 移动端PWA体验

TangleClaw的Web界面是一个渐进式Web应用（PWA）。这意味着你可以在手机或平板的浏览器中，将其“安装”到主屏幕，获得一个类似原生应用的体验，包括离线缓存（静态资源）和全屏显示。

这对于上文提到的“多设备切换”场景至关重要。你可以把TangleClaw当作一个常驻的手机App，随时随地接续在电脑上未完成的AI编码会话。

4.4 自定义引擎与方法论

添加自定义引擎：如果你使用一个TangleClaw尚未内置的AI CLI工具，可以很容易地添加支持。在~/.tangleclaw/engines/目录下创建一个新的JSON文件（例如my-engine.json）。这个配置文件需要定义引擎的启动命令、参数、配置文件生成模板、支持的启动模式等。TangleClaw在启动时会加载所有此目录下的引擎定义。

创建自定义方法论：在~/.tangleclaw/templates/目录下，你可以基于已有的模板（如standard.json）创建自己的方法论。你可以定义独特的阶段、编写严格的规则（使用JSON Schema描述），甚至绑定自定义的Node.js脚本作为钩子。这让你能将团队内部的开发规范“代码化”，并强制AI助手遵守。

5. 故障排查与性能优化

5.1 常见问题与解决方案

1. 仪表盘无法访问（localhost:3102无响应）

• 检查服务状态：在终端运行launchctl list | grep tangleclaw。如果看不到com.tangleclaw.server，可能是服务未加载。尝试运行launchctl load ~/Library/LaunchAgents/com.tangleclaw.server.plist。
• 查看日志：tail -f ~/.tangleclaw/logs/tangleclaw.log，看是否有错误信息。常见错误包括端口被占用（修改config.json中的serverPort或ttydPort）、Node.js版本不符等。
• 手动启动测试：进入TangleClaw目录，运行node server.js。如果能在终端看到启动日志，并在浏览器访问http://localhost:3101（这是代码中的默认端口，launchd配置会覆盖为3102），则说明代码本身无问题，问题出在launchd配置上。

2. 终端会话无法连接/白屏

• 这通常是ttyd服务的问题。首先检查com.tangleclaw.ttyd服务是否运行。
• 检查ttyd是否安装正确：which ttyd。
• 查看ttyd日志：日志通常也输出到~/.tangleclaw/logs/tangleclaw.log，寻找ttyd相关的错误。
• 尝试在终端直接运行ttyd -p 3101 bash，然后在浏览器访问http://localhost:3101，看是否能打开一个基础的终端。这可以隔离是否是TangleClaw的问题。

3. AI引擎启动失败

• 检查引擎路径：确保你选择的AI引擎（如claude，aider）已正确安装，并且其命令可以在系统的PATH中找到。TangleClaw在启动会话时，会直接在tmux中调用这些命令。
• 检查API密钥：大多数AI引擎需要环境变量（如ANTHROPIC_API_KEY,OPENAI_API_KEY）来设置API密钥。确保这些环境变量在启动TangleClaw的服务时是有效的。由于TangleClaw通过launchd启动，你需要确保这些环境变量在用户登录时就已设置（例如放在~/.zshrc或~/.bash_profile中），或者考虑在launchd的plist文件中通过EnvironmentVariables键设置。
• 查看会话日志：在TangleClaw仪表盘的项目页面，通常有查看会话输出日志的选项。启动失败的错误信息会在这里显示。

4. 会话无法持久化（重新连接后是新会话）

• 这几乎总是tmux相关问题。首先确认tmux会话是否真的存在。通过SSH登录到运行TangleClaw的机器，执行tmux list-sessions。你应该能看到以TangleClaw项目ID命名的会话。
• 如果会话不存在，可能是TangleClaw的tmux.js模块创建会话失败，或者会话被意外杀死了。检查TangleClaw的主日志。
• 如果会话存在但无法附着，可能是权限或终端类型问题。尝试手动附着：tmux attach -t <session-name>，看是否成功。

5.2 性能调优与资源管理

• 会话内存管理：每个活跃的AI会话都会占用内存和CPU。虽然TangleClaw本身很轻量，但AI引擎（尤其是本地运行的大模型）可能是资源消耗大户。定期在仪表盘检查并结束不再需要的会话。
• 日志轮转：TangleClaw的日志默认会增长。定期清理~/.tangleclaw/logs/目录下的旧日志文件，或配置日志轮转策略（需要修改lib/logger.js）。
• 项目扫描优化：如果你的projectsDir包含非常多的文件夹（如node_modules），初始扫描可能会稍慢。TangleClaw通常会忽略常见的依赖目录和隐藏目录。如果扫描过慢，可以考虑将项目目录结构化，或者修改项目检测逻辑（在lib/projects.js中）。
• 数据库维护：TangleClaw使用SQLite存储运行时状态。长时间运行后，数据库文件~/.tangleclaw/data/tangleclaw.db可能增大。你可以定期通过命令行进行压缩：sqlite3 ~/.tangleclaw/data/tangleclaw.db "VACUUM;"。

5.3 与OpenClaw远程实例的连接问题

OpenClaw是另一个支持远程AI编码会话的工具。TangleClaw可以与其集成。

• SSH隧道模式：这是最常用的方式。确保TangleClaw服务器所在机器能通过SSH密钥免密登录到OpenClaw主机。在TangleClaw配置中正确填写OpenClaw主机的SSH连接信息。连接失败时，首先测试手动SSH连接是否通畅。
• Web UI模式与HTTPS：Web UI模式需要HTTPS。确保TangleClaw已正确配置HTTPS证书（使用了一键mkcert或提供了有效的证书）。在手机等设备上访问时，浏览器需要信任该证书（mkcert证书需要先在设备上安装其根证书）。
• 防火墙与端口：确保OpenClaw主机上相应的网关端口（默认18789）和ClawBridge端口（默认3201）对TangleClaw服务器所在IP开放。

6. 架构设计与扩展思路

理解TangleClaw的架构，有助于你进行定制化开发或故障排查。

核心架构图（简化）：

用户浏览器 <-> [TangleClaw Web服务器 (Node.js)] | | (反向代理/API路由) v [ttyd进程] <-> [tmux会话] <-> [AI引擎进程 (claude/codex/etc.)] | v [项目文件系统]

• Web服务器：基于Node.js原生http(s)模块，处理仪表盘页面、REST API、以及将/terminal/*路径的请求反向代理到ttyd进程。
• ttyd：一个独立的C++程序，负责将终端I/O通过WebSocket暴露给浏览器。TangleClaw通过launchd管理其生命周期。
• tmux：真正的会话持久化层。每个AI会话都是一个独立的tmux会话。
• 状态存储：使用SQLite存储项目、会话、端口租约等元数据；使用JSON文件存储配置和模板。

扩展方向：

• 自定义技能（Skills）：TangleClaw有一个“技能系统”的雏形（见lib/skills.js）。你可以编写自定义的Node.js模块，在会话开始、结束或特定事件发生时触发，实现自动化工作流，例如：会话结束后自动运行测试、将代码变更同步到远程仓库、发送通知等。
• 引擎增强：通过修改data/engines/下的引擎配置文件，你可以调整AI的启动参数、系统提示词模板，甚至集成更复杂的调用链。
• UI定制：public/目录下是所有的前端资源。你可以修改HTML、CSS和JavaScript来定制仪表盘的外观和交互，使其更符合你的使用习惯。

TangleClaw v3将一个常见的痛点——AI编码会话的脆弱性——作为切入点，构建了一个功能丰富、思想超前的本地化AI开发环境管理平台。它不仅仅是一个“不断线”的工具，更是一个致力于将人类开发者的意图和规范，通过结构化的方式，可靠地传递给AI助手的桥梁。通过将方法论、记忆、多引擎支持、跨设备访问等特性深度整合，它为严肃的、生产级的AI辅助软件开发提供了一个极具潜力的基础框架。