基于 LangChain/LangGraph 的终端 AI Agent 框架
Tclaw 是一个运行在终端中的 AI Agent 框架，基于 LangChain + LangGraph 构建。核心设计思路是让 LLM 在受控的安全环境中调用工具、执行命令、管理任务，并通过长期记忆持续进化。
适用于：个人 AI 助手、自动化工作流、Agent 开发实验、多模型切换测试。
- 多模型适配 — 支持 OpenAI 兼容接口（阿里云/智谱/腾讯混元等）、Anthropic、Ollama，通过
.env一键切换 - 沙盒安全执行 — 所有文件读写和 Shell 命令限制在
workspace/office/沙盒内，多层路径拦截 + 超时熔断 - 定时任务系统 — 后台心跳协程自动轮询任务队列，支持单次/hourly/daily/weekly/monthly 循环
- 懒加载技能系统 — 技能目录即插即用，首次调用时才加载完整内容，支持热更新无需重启
- 长期记忆 — 用户画像（Markdown 档案）+ 上下文摘要压缩（超过 40 回合自动裁剪并摘要）
- 事件日志 — 异步 JSONL 日志，后台线程批量写入，线程级隔离
- 交互式终端 — prompt_toolkit 驱动，动画 spinner、工具调用实时展示
# 克隆项目
git clone <repo-url> && cd TClaw
# 创建虚拟环境（Python ≥ 3.10）
python -m venv .venv
source .venv/bin/activate
# 安装依赖
pip install -r requirements.txt# 启动配置向导（交互式选择提供商 + 模型型号）
python entry/cli.py config
# 或
tclaw config支持以下提供商：
| 提供商 | 配置项 |
|---|---|
| OpenAI | gpt-4o-mini 等，需 OPENAI_API_KEY |
| Anthropic | claude-sonnet-4 等，需 ANTHROPIC_API_KEY |
| 阿里云 (DashScope) | qwen-max 等，用 OpenAI 兼容模式 + OPENAI_API_KEY |
| 智谱 (z.ai) | glm-4 等，用 OpenAI 兼容模式 |
| 腾讯混元 | 用 OpenAI 兼容模式 |
| Ollama | 本地模型，无需 API Key |
配置完成后会在项目根目录生成 .env 文件，可参考 .env.example 手动编辑。
# 进入交互终端
python entry/cli.py run
# 或
tclaw run启动后直接在终端输入，Agent 会自动调用工具或直接回答。
"明天早上 8 点叫我起床"
"以后每天提醒我喝水"
"接下来 3 天，每晚提醒我吃药"
所有操作限制在 workspace/office/ 内，无法越界。
"列出 office 目录下有哪些文件"
"帮我写一个 Python 爬虫脚本"
Agent 会自动从对话中学习用户偏好并写入 workspace/memory/user_profile.md，下次启动仍有效。
用户输入 → agent（LLM 思考） → 需要工具？ → tools（ToolNode） → agent → ...
↓ 否
直接回复
基于 LangGraph 的 StateGraph，核心节点：
- agent: LLM 思考节点，注入 System Prompt（含用户画像 + 上下文摘要），决定回复或调用工具
- tools: ToolNode，执行 agent 调用的工具，结果返回后继续 agent 循环
超过 40 个用户回合（HumanMessage）后自动触发上下文裁剪：
- 按回合分组（一个 HumanMessage + 后续所有 AIMessage/ToolMessage 为一回合）
- 保留最近 10 回合，丢弃最早回合
- 用 LLM 将丢弃的对话压缩为 150 字以内摘要，注入 System Prompt
tclaw/core/ # 核心引擎
agent.py # StateGraph 组装
context.py # AgentState 定义 + 上下文裁剪
provider.py # LLM 工厂适配
heartbeat.py # 定时任务心跳
skill_loader.py # 技能懒加载
tools/ # 工具实现
builtins.py # 内置工具
sandbox_tools.py # 沙盒安全操作
entry/ # 入口层
cli.py # CLI 命令（config/run/monitor）
main.py # 交互式终端 + Agent 循环
monitor.py # 实时监控面板
workspace/ # 运行时数据（非版本控制）
memory/ # 用户画像
office/ # 沙盒工作区
在 tclaw/core/tools/builtins.py 中用装饰器定义函数，加入 BUILTIN_TOOLS 列表：
@tclaw_tool
def my_tool(param: str) -> str:
"""工具描述（作为 LLM 的工具说明）"""
# 实现逻辑
return result在 workspace/office/skills/ 下创建子目录，内含 SKILL.md 或 README.md，文件前 50 行需包含元数据：
name: my-skill
description: 这个技能做什么技能通过统一的 mode='help' | 'run' 接口调用，Agent 会先读取说明书再决定如何执行。
在 tclaw/core/provider.py 的 get_provider() 中新增分支。
# 全部测试
python -m unittest discover tests -v
# 分类测试
python -m unittest tests/test_sandbox_tools.py -v # 沙盒安全
python -m unittest tests/test_builtins.py -v # 内置工具
python -m unittest tests/test_heartbeat.py -v # 定时任务
python -m unittest tests/test_context_advanced.py -v # 上下文裁剪
python -m unittest tests/test_lazy_loader.py -v # 技能懒加载
python -m unittest tests/test_two_phase_skills.py -v # 二阶段安全选择
python -m unittest tests/test_agent.py -v # Agent 流程python entry/cli.py monitor
# 或
tclaw monitor实时查看 LLM 调用、工具调用、错误信息等事件流。