thClaws 🦞

项目定位#

thClaws 面向需要高度可控、本地化 AI 辅助的开发者与知识工作者，解决多模型接入、Agent 协作编排以及工具链集成的痛点。其能力边界明确限定在本地优先运行，知识库（KMS）采用 grep + read 而非向量嵌入，子 Agent 递归深度上限为 3 层。

核心能力#

模型与交互模式#

• 多模型提供商支持：接入 Anthropic、OpenAI、Gemini、Alibaba DashScope、OpenRouter、Ollama（本地）等，兼容通用 OpenAI 接口（如 LiteLLM / Portkey / Helicone / vLLM），按模型名前缀自动检测，支持会话中实时切换。
• 三种交互模式：① Desktop GUI (thclaws) 含 Terminal/Chat/Files/Team 标签页；② CLI REPL (thclaws --cli) 交互式终端；③ 非交互单次执行 (thclaws -p "prompt") 适合脚本与 CI。

编排与记忆机制#

• Agent 编排：通过 Task 工具委托子任务给隔离子 agent（最多 3 层递归）；Agent Teams 实现多进程协调，共享邮箱和任务队列，各自拥有独立 tmux 窗格和可选 git worktree。
• Memory（记忆系统）：持久化存储，分为 user / feedback / project / reference 四类，以 Markdown 形式保存，支持直接阅读和编辑。
• Knowledge Bases (KMS)：项目级和用户级 Wiki，agent 按需搜索阅读，基于 grep + read 实现（无嵌入向量），遵循 Karpathy LLM-wiki 模式。

扩展与工具集成#

• MCP 服务器集成：支持 stdio 和 HTTP Streamable 传输，集成 OAuth 2.1 + PKCE 认证，可接入 GitHub、文件系统、数据库、浏览器、Slack 等第三方工具。
• Skills（技能系统）：可复用专家工作流（含 SKILL.md + 可选脚本），按 whenToUse 触发器自动匹配或手动 /skill-name 调用，支持从 git URL 或 .zip 安装。
• Plugin 系统：将 Skills + Commands + Agent Definitions + MCP Servers 打包为单一清单，支持一键安装/卸载。

安全与隐私#

• 安全沙箱：文件系统沙箱限定文件工具仅在工作目录内操作；破坏性 shell 命令执行前强制确认；所有变更操作需用户批准（除非开启 auto-approve）。
• 离线运行：通过 Ollama 接入可实现完全本地运行，无需云端 API。
• Shell Escape：REPL 中使用 ! 前缀直接执行 shell 命令，无 token 消耗。
• 开放标准：采用 MCP（工具协议）、AGENTS.md（项目指令）、SKILL.md（YAML frontmatter）等业界开放标准。

架构概览#

• 整体架构：Monorepo 结构，核心逻辑位于 crates/core/（Rust 89.6%），前端位于 frontend/（TypeScript 10.0% + React + Vite）。
• GUI 渲染机制：前端使用 CodeMirror（文件编辑）和 Tiptap（富文本），构建为单一 HTML 文件嵌入 Rust 二进制中。底层基于 Rust + webview 架构（依赖 webkit2gtk，推断使用 Tauri 框架），支持 light/dark/system 主题。
• Agent 多进程协调：Agent Teams 采用多进程隔离设计，各进程分配独立的 tmux 窗格，底层通过共享邮箱和任务队列通信。
• 工具通信协议：严格遵循 MCP，实现 stdio 与 HTTP Streamable 两种传输方式。
• 知识检索实现：KMS 存储于 .thclaws/kms/<name>/pages/，直接利用 grep + read 进行文件级检索。

典型场景#

• AI 辅助编程：读取、编辑、浏览项目文件，运行命令，自动测试，代码重构。
• 多 Agent 并行开发：后端/前端分别由不同 agent 在独立 git worktree 中并行构建，lead agent 合并分支。
• 知识工作者辅助：研究人员、PM、运维、法务等通过 Chat 标签页进行自然语言交互、文件访问、知识库查询。
• CI/CD 集成：单次执行模式适合管道中的自动化任务。
• 本地私有化部署：全部数据留在本机，云调用可选，适合安全敏感场景。

安装与快速开始#

预编译二进制#

支持 macOS (Apple Silicon & Intel)、Windows (x86_64 & ARM64)、Linux (x86_64 & ARM64)。

curl -L https://github.com/thClaws/thClaws/releases/latest/download/thclaws-v0.7.4-aarch64-apple-darwin.tar.gz \
  | tar -xz && sudo mv thclaws /usr/local/bin/

从源码构建#

前置条件: Rust 1.85+、Node.js 20+、pnpm 9+

git clone https://github.com/thClaws/thClaws.git
cd ThClaws
cd frontend && pnpm install && pnpm build && cd ..
cargo build --release --features gui --bin thclaws
./target/release/thclaws          # GUI
./target/release/thclaws --cli    # CLI

配置要点#

• 配置优先级：CLI flags > .thclaws/settings.json（项目级）> ~/.config/thclaws/settings.json（用户级）> ~/.claude/settings.json（兼容回退）> 编译内置默认值
• API 密钥存储于 OS keychain（macOS Keychain / Windows Credential Manager / Linux Secret Service），CI 环境回退到 .env
• 关键文件：CLAUDE.md/AGENTS.md（系统提示词）、.thclaws/skills/（技能）、.thclaws/agents/（子 agent）、.mcp.json（MCP 配置）、.thclaws-plugin/plugin.json（插件清单）

开发组织与版本#

• 开发组织：ThaiGPT Co., Ltd.（泰国）
• 双重许可：MIT License / Apache License 2.0
• 当前版本：v0.7.6（截至调研时，共 28 个 release，162 次提交）

待确认事项#

• GUI 框架推断为 Tauri（基于 webkit2gtk + Rust + webview 组合），但未在文档中显式声明
• 用户手册在线版发布状态待确认（仓库中已有 24 章 + 7 个案例研究）
• Enterprise Edition 具体功能差异未公开
• 未公开性能基准测试数据
• Agent Teams 支持的最大 agent 数量限制未明确