cheetahclaws
SafeRL-Lab/cheetahclaws加载项目详情…
本应用为开源项目，仅供学习研究，请遵守其开源协议。
微信扫码咨询客服
POMOAI — 让开源 AI 即刻运行
加载项目详情…
本应用为开源项目，仅供学习研究，请遵守其开源协议。
Claude Code 是 Anthropic 官方推出的 AI 编程助手，功能强大，但它的源代码是一个约 12 MB 的编译后 TypeScript/Node Bundle（超 1300 个文件，约 28.3 万行代码），与 Anthropic API 深度耦合，修改门槛极高，且无法对接本地模型或其他云端供应商。
CheetahClaws 正是对这个问题的一次正面回应——它在约 9 万行可读的 Python 代码中重新实现了 Claude Code 的核心循环，保留了真正重要的部分，删除了不必要的部分，并叠加了多供应商 + 本地模型支持。2026 年 6 月 16 日项目刚刚完成 v3.5.82 版本的大规模重构，将所有内部模块统一收束到 cheetahclaws 包命名空间下，解决了与其他项目 config/ 目录或 PyPI python-daemon 包冲突导致的 ImportError 问题，测试覆盖率达 2449 个用例全部通过。
图1：CheetahClaws Web UI 截图，支持多用户浏览器对话、工具卡片和 Markdown 流式输出
"Agent Harness" 这个概念对普通用户可能陌生，但类比非常直观——就像给赛车换装一套通用接口的线束，让同一套电子设备可以无缝适配不同发动机。CheetahClaws 本质上是一套让 AI 智能体（Agent）能够自主循环执行任务的运行时基础设施：接收用户指令 → 调用工具 → 观察结果 → 继续决策 → 直到任务完成。
传统的 Claude Code 是一个封闭的黑盒：模型固定（Claude）、工具固定、行为固定。而 CheetahClaws 做了三件关键的事：
第一，多模型支持。 支持 Anthropic、OpenAI、Google Gemini、Moonshot(Kimi)、阿里 Qwen、智谱 GLM、DeepSeek、MiniMax 等 8+ 云端供应商，以及通过 Ollama / LM Studio / vLLM 对接任意本地模型。切换模型只需一条命令 --model ollama/qwen2.5-coder，无需重新编译。
第二，可读的 Agent 循环。 整个 Agent 主循环（streaming + tool-use）集中在单个 agent.py 文件中，约 740 行，代码结构清晰可审计。相比 Claude Code 28 万行的编译产物，CheetahClaws 让研究者和开发者能真正理解"AI Agent 内部是如何运转的"。
第三，开放扩展机制。 支持 MCP（Model Context Protocol）服务器接入（stdio/SSE/HTTP 三种协议）、Markdown 格式的 Skill 技能系统、Git 插件系统、运行时动态工具注册（register_tool()），以及 bridges（桥接器）将 AI 能力输出到 Telegram、微信、Slack、QQ 等即时通讯平台。
CheetahClaws 的代码结构可以大致分为五层，每一层都有明确的职责边界。
第一层：Provider（供应商抽象）。 providers.py 实现了统一的 Provider 接口，将 Anthropic 的 SDK 调用、OpenAI 的 SDK 调用、以及 Ollama 的原始 HTTP 请求全部转换为内部统一的 AssistantTurn（助手轮次）和 TextChunk/ThinkingChunk（文本/思考块）格式。无论底层用的是哪个模型，Agent 核心看到的永远是同一种数据结构。
第二层：Agent Core（Agent 核心循环）。 agent.py 实现了生成器风格（Generator-based）的多轮对话循环，核心逻辑约 740 行。它负责管理消息历史（messages）、Token 计数、上下文窗口压缩（compaction）、循环检测（loop guard）——防止模型在工具调用失败时陷入无限重试，以及只读去重（Read/Glob/Grep 等工具的重复调用结果直接复用而非真正执行）。
第三层：Kernel（内核子系统）。 这是最复杂的子系统，包含以下子模块：
kernel/api.py 的 Kernel 统一 facade 类，将上述 9 个独立存储的初始化逻辑封装为单入口 Kernel.open(db_path)，极大降低了测试和集成的复杂度。第四层：Daemon（守护进程）。 daemon/ 目录实现了完整的守护进程模式，包括：Agent 方法（通过 RPC 暴露）、Bridge 监督（自动重启 Telegram/WeChat/Slack 连接）、认证与权限、主动调度（proactive_scheduler）、会话管理、Spike 客户端等。F1-F9 的完整 Daemon 路线图已在 2026 年 5 月全部落地。
第五层：Tool System（工具系统）。 内置 27 种工具涵盖文件系统操作（Read/Write/Edit/Bash/Glob/Grep）、Web 能力（WebFetch/WebSearch）、Notebook 编辑、代码诊断、内存管理、子 Agent 调用、Skill 技能执行、任务管理（TaskCreate/Update/Get/List）、计划模式（EnterPlanMode/ExitPlanMode）等。工具通过 tool_registry.py 统一注册，支持 MCP 插件和 Git 插件的动态注入。
最简安装（推荐）：
curl -fsSL https://raw.githubusercontent.com/SafeRL-Lab/cheetahclaws/main/scripts/install.sh | bash
source ~/.zshrc
cheetahclaws
脚本自动检测操作系统（Linux/macOS/WSL2/Android Termux），创建独立 Python venv，安装核心依赖，配置 PATH，整个过程无需手动干预。2026 年 6 月 6 日的 v3.5.82 还专门修复了 macOS 上安装后 PATH 未正确写入 ~/.zshrc 的历史遗留 bug。
Web UI 部署（Docker 方式）：
cp .env.example .env # 填写 API key
mkdir -p ./workspace ./data
docker compose up -d --build
# 打开 http://<host-ip>:8080/chat
Dockerfile 使用 python:3.13-slim，非 root 用户（UID 1000），通过 tini 处理 PID-1 信号，内置健康检查（每 30 秒检查 /api/config 返回状态）。docker-compose 挂载工作目录和配置目录，支持 Ollama 宿主机联动（通过 host.docker.internal），同时启动 Web UI 和 Telegram Bridge。
从源码直接运行：
pip install -e '.[all]'
python -m cheetahclaws
[all] 额外依赖组包含：语音（sounddevice）、视觉（Pillow）、浏览器自动化（playwright）、文档处理（pymupdf）、量化交易（yfinance + rank-bm25）等。
CheetahClaws 早已超越了一个"本地 Claude Code 替代品"的定位，它的野心是成为一套通用的多模型 Agent 运行时平台。
Trading Agent（量化交易智能体）。 /trading 命令基于多智能体架构：analyst（分析师）研究市场数据 → researcher（研究员）收集宏观信息 → portfolio_manager（组合经理）计算配比 → risk_manager（风险管理）评估回撤。同时提供完整的回测引擎（backtest_strategy）、因子分析（factors）、异常检测（anomaly discovery）和板块轮动（sector_rotation）模块。
Research Lab（研究实验室）。 /research 将查询任务分发到 20 个信息源，包括 arXiv、HuggingFace Papers、Google Scholar、Semantic Scholar、OpenAlex、Polymarket、Reddit、HackerNews、Twitter、微博、小红书、知乎、Bilibili、SEC EDGAR 等，通过注意力热力图展示各源的信息权重，并支持趋势分析和多源对比。
Multi-Agent 多智能体编排。 支持通过 AgentCreate 创建子 Agent（类型可选：coder/reviewer/researcher 等），每个子 Agent 在独立的 git worktree 中运行（避免代码冲突），支持后台模式和与主 Agent 的消息传递。fanout.py 实现了任务广播——一个任务可以同时分发给多个专业 Agent 并行处理。
Bridges 桥接生态。 Telegram、微信（支持 smart_reply 智能回复）、Slack、QQ 均有官方 Bridge 实现，Bridge 接收消息后转发给 CheetahClaws 处理，结果通过同一 Channel 返回。Slack Bridge 支持 slash 命令透传（/research、/brainstorm），Telegram Bridge 支持 per-bridge 独立任务队列（!jobs/!retry/!cancel）。
长程任务中 Token 消耗是核心瓶颈。CheetahClaws 实现了一套四层协作的上下文压缩机制：
max_tokens 上限（第一层）：每个模型有独立的上下文窗口注册表，系统根据当前已用 Token 比例实时调整下一轮回复的 max_tokens 上限。v3.5.82 版本还引入了自适应 Markdown 流式输出（Adaptive Markdown Streaming），自动根据终端能力选择渲染模式：支持 ANSI 转义码的现代终端使用原地刷新，SSH/Apple Terminal/管道/CJK 文本使用追加提交，其他情况降级为纯文本。
2026 年 5 月 12 日，项目进行了一次全面安全加固，修复了两个 CRITICAL 和多个 HIGH 级别漏洞：
***REDACTED***）。X-CSRF-Token 头。2447 个安全相关测试用例全部通过。
CheetahClaws 的 GitHub 页面引用了一篇 arXiv 论文《Scaling the Harness》（arXiv:2605.26112），提出了"Harness Engineering"（线束工程）这一概念——类比传统汽车工程中"平台化线束"让不同车型共享零部件的思路，Harness Engineering 指的是构建一套与具体模型解耦的 Agent 基础设施，使同一套工具链、工作流和扩展生态可以在不同模型间自由切换。
随着 Claude、GPT-5、Gemini、DeepSeek R2 等模型的能力持续分化，开发者越来越需要一个"模型无关"的 Agent 框架来保护他们的工具链投资——今年用 Claude，明年换成 Qwen 或 DeepSeek，不需要重写任何工具、工作流和插件。CheetahClaws 正是这个方向上走得最远的开源实现之一。
开发团队： SafeRL-Lab（Safe AI and Robot Learning Lab，上海人工智能实验室相关），联系人 gushangding@gmail.com。项目采用 Apache-2.0 许可证，完全开源。