SmallClaw

在大型模型动辄消耗高昂 API 费用的今天，SmallClaw 是一个本地优先（Local-First）的开源 AI 智能体框架，专为 4B 至 32B 参数的小型模型 优化设计。它让你的旧笔记本或家用服务器也能运行具备文件操作、网络搜索、浏览器自动化及终端控制能力的智能助手，且数据永不离开本地，无需任何 API 成本。

核心理念：小模型，大能力

SmallClaw 并非简单地将大模型的功能缩小，而是针对小模型的特性进行了深度重构：

• 本地优先，混合云可选：默认完全本地运行（Ollama, llama.cpp, LM Studio），同时也支持接入 OpenAI 等云端提供商作为混合补充。
• 零成本永续运行：利用免费开源模型（如 Qwen, DeepSeek Coder），彻底摆脱 Token 计费焦虑。
• 行级精准编辑：针对小模型容易在重写长文件时丢失内容的弱点，设计了精细化的行级编辑工具，确保代码和文档修改的安全性与准确性。

架构革新：单次交互（Single-Pass）引擎

与小模型协调多个角色往往导致延迟高、逻辑混乱不同，SmallClaw v2 采用了高效的单次聊天处理器架构：

1. 统一入口：用户消息进入后，系统构建精简的系统提示和短历史上下文。
2. 单次决策：LLM 进行一次调用，直接决定是回复文本还是调用工具。
3. 闭环执行：若调用工具，SmallClaw 在沙箱中执行并将结果反馈给模型，模型继续推理直到输出最终回复。
4. 实时流式：全过程通过 SSE (Server-Sent Events) 实时推送到 Web UI，延迟极低。

优势：这种架构消除了复杂的“规划 - 执行”多轮协调开销，特别适合上下文窗口有限、推理能力稍弱的小模型，显著提升了稳定性和响应速度。

全能工具箱：像人类一样操作电脑

SmallClaw 提供了一套结构化的原生工具调用接口（兼容 Ollama 格式），涵盖四大核心领域：

1. 精细化文件操作

不再暴力重写整个文件，而是提供手术刀般的编辑能力：

• read_file：读取文件并显示行号。
• replace_lines / delete_lines：精确替换或删除指定行。
• insert_after：在特定行后插入内容。
• find_replace：查找并替换精确字符串。
• 防止了小模型常见的“幻觉性重写”导致代码损坏的问题。

2. 多级网络搜索

内置提供商瀑布流机制，确保搜索成功率：

• 优先级：Tavily → Google CSE → Brave → DuckDuckGo。
• 无密钥备用：若未配置 API Key，自动降级使用 DuckDuckGo 免费搜索。
• 功能：web_search (搜摘要) + web_fetch (抓全文)。

3. 真实浏览器自动化

基于 Playwright 驱动真实浏览器实例：

• browser_open / snapshot：打开网页并捕获 DOM 快照。
• browser_click / fill / press_key：模拟点击、输入、按键。
• 让 AI 能真正操作网页表单、登录系统、抓取动态内容。

4. 安全终端与系统控制

• run_command：在安全工作区执行系统命令。
• start_task：启动后台长期任务。

快速上手指南

前置要求

• Node.js 18+
• 至少 8GB 内存
• Ollama (推荐) 或其他兼容后端

安装步骤

# 1. 克隆仓库
git clone https://github.com/xposemarket/smallclaw.git
cd smallclaw

# 2. 安装依赖并构建
npm install
npm run build

# 3. 全局链接 CLI
npm link

启动流程

# 1. 拉取推荐模型 (根据内存选择)
# 8GB 内存推荐：qwen3:4b
# 16GB 内存推荐：qwen2.5-coder:32b
ollama pull qwen3:4b

# 2. 启动网关
smallclaw gateway start

# 3. 访问 Web UI
# 打开浏览器访问 http://localhost:18789

技能系统 (Skills)

SmallClaw 支持即插即用的 SKILL.md 文件。只需将技能文件放入 .localclaw/skills/<skill-name>/ 目录，模型会在相关场景下自动加载并应用这些专家知识。

• 示例：添加一个 "Python 专家" 技能，定义特定的编码规范和调试流程。
• 扩展：社区可共享技能文件，快速赋予智能体新领域的专业能力。

硬件与模型推荐