Clawlet

超轻量且高效的个人AI助手

Clawlet 是一款轻量级的个人AI代理，具备混合语义记忆搜索功能——它是一个单一的静态二进制文件，无需运行时环境，也不使用CGO。
内置SQLite + sqlite-vec。只需将其部署到任何机器上，记忆搜索功能即可直接使用。

该项目受到 OpenClaw 和 nanobot 的启发。

安装

从 GitHub Releases 下载。

macOS (Apple Silicon):

curl -L https://github.com/mosaxiv/clawlet/releases/latest/download/clawlet_Darwin_arm64.tar.gz | tar xz
mv clawlet ~/.local/bin/

快速入门

# 初始化
clawlet onboard \
  --openrouter-api-key "sk-or-..." \
  --model "openrouter/anthropic/claude-sonnet-4.5"

# 检查有效配置
clawlet status

# 对话
clawlet agent -m "2加2等于多少？"

配置 (~/.clawlet/config.json)

配置文件：~/.clawlet/config.json

支持的提供商

clawlet 目前支持以下LLM提供商：

• OpenAI (openai/<model>，API密钥：env.OPENAI_API_KEY)
• OpenAI Codex (OAuth) (openai-codex/<model>，无需API密钥；登录方式：clawlet provider login openai-codex)
• OpenRouter (openrouter/<provider>/<model>，API密钥：env.OPENROUTER_API_KEY)
• Anthropic (anthropic/<model>，API密钥：env.ANTHROPIC_API_KEY)
• Gemini (gemini/<model>，API密钥：env.GEMINI_API_KEY 或 env.GOOGLE_API_KEY)
• 本地（Ollama / vLLM / 兼容OpenAI的本地端点） (ollama/<model> 或 local/<model>，默认基础URL：http://localhost:11434/v1，API密钥可选）

最小配置（OpenRouter）：

{
  "env": { "OPENROUTER_API_KEY": "sk-or-..." },
  "agents": { "defaults": { "model": "openrouter/anthropic/claude-sonnet-4-5" } }
}

代理生成的默认设置可配置：

{
  "agents": {
    "defaults": {
      "model": "openrouter/anthropic/claude-sonnet-4-5",
      "maxTokens": 8192,
      "temperature": 0.7
    }
  }
}

最小配置（通过Ollama使用本地模型）：

{
  "agents": { "defaults": { "model": "ollama/qwen2.5:14b" } }
}

最小配置（通过vLLM使用相同的ollama/路由）：

{
  "agents": { "defaults": { "model": "ollama/meta-llama/Llama-3.1-8B-Instruct" } },
  "llm": { "baseURL": "http://localhost:8000/v1" }
}

OpenAI Codex (OAuth)：

# 一次性登录
clawlet provider login openai-codex

# 无头环境（SSH / 容器）
clawlet provider login openai-codex --device-code

{
  "agents": { "defaults": { "model": "openai-codex/gpt-5.1-codex" } }
}

选项：记忆搜索设置

要启用语义记忆搜索，可在代理默认设置中添加memorySearch：

{
  "env": {
    "OPENAI_API_KEY": "sk-..."
  },
  "agents": {
    "defaults": {
      "memorySearch": {
        "enabled": true,
        "provider": "openai",
        "model": "text-embedding-3-small"
      }
    }
  }
}

本地嵌入（Ollama / 兼容OpenAI的本地端点）：

{
  "agents": {
    "defaults": {
      "memorySearch": {
        "enabled": true,
        "provider": "openai",
        "model": "nomic-embed-text",
        "remote": {
          "baseURL": "http://localhost:11434/v1"
        }
      }
    }
  }
}

启用后：

• 代理将获得memory_search和memory_get工具，用于检索过往上下文。
• clawlet会索引MEMORY.md、memory.md以及memory/**/*.md文件以供检索。
• 索引数据库将在{workspace}/.memory/index.sqlite中创建。

禁用时（默认）：

• memorySearch.enabled默认为false；搜索工具不会暴露给模型。
• 记忆文件（memory/MEMORY.md、memory/YYYY-MM-DD.md）仍会按常规注入到上下文中。
• 正常的对话行为则保持不变。

安全性

安全默认设置

• tools.restrictToWorkspace默认为true（工具仅能访问工作目录内的文件）
• gateway.listen默认为127.0.0.1:18790
• gateway.allowPublicBind默认为false

安全检查清单

工具

多模态输入（音频/图片/附件）

传入渠道的消息可以包含附件。clawlet可以：

• 将图片发送给具备视觉能力的模型，
• 使用配置的提供商转录音频，
• 并将类似文本的文件附件内联到用户上下文中。

可在tools.media中进行配置（以下值为当前默认值）：

{
  "tools": {
    "media": {
      "enabled": true,
      "audioEnabled": true,
      "imageEnabled": true,
      "attachmentEnabled": true,
      "maxAttachments": 4,
      "maxFileBytes": 20971520,
      "maxInlineImageBytes": 5242880,
      "maxTextChars": 12000,
      "downloadTimeoutSec": 20
    }
  }
}

聊天应用

聊天应用集成在channels中配置（以下为示例）。

{
  "channels": {
    "telegram": {
      "enabled": true,
      "token": "123456:ABCDEF...",
      "allowFrom": ["123456789"]
    }
  }
}

clawlet gateway

{
  "channels": {
    "whatsapp": {
      "enabled": true,
      "allowFrom": ["15551234567"]
    }
  }
}

# 一次性登录（在启动网关前必须完成）
clawlet channels login --channel whatsapp

# 正常运行时
clawlet 网关

{
  "channels": {
    "discord": {
      "enabled": true,
      "token": "YOUR_BOT_TOKEN",
      "allowFrom": ["YOUR_USER_ID"]
    }
  }
}

clawlet gateway

{
  "channels": {
    "slack": {
      "enabled": true,
      "botToken": "xoxb-...",
      "appToken": "xapp-...",
      "groupPolicy": "mention",
      "allowFrom": ["U012345"]
    }
  }
}

clawlet gateway

CLI 参考

clawlet cron add 格式

--message 为必填项，且必须精确设置 --every、--cron 或 --at 中的一项。

# 每 N 秒执行一次
clawlet cron add --message "总结我的收件箱" --every 3600

# Cron 表达式（5 字段）
clawlet cron add --message "每日站会记录" --cron "0 9 * * 1-5"

# 在特定时间执行一次（RFC3339 格式）
clawlet cron add --message "提醒我" --at "2026-02-10T09:00:00Z"

# 发送至聊天（需同时设置 --channel 和 --to）
clawlet cron add --message "ping" --every 600 --channel slack --to U012345

🐳 Docker

使用预构建镜像

预构建镜像可在 GitHub Container Registry 上获取：

# docker-compose.yml
services:
  clawlet:
    image: ghcr.io/mosaxiv/clawlet:latest
    volumes:
      - ~/.clawlet:/root/.clawlet
    command: gateway
    restart: unless-stopped

docker compose up -d

本地构建

# 构建镜像
docker build -t clawlet .

# 初始化配置（仅首次）
docker run -v ~/.clawlet:/root/.clawlet --rm clawlet onboard

# 在主机上编辑配置文件以添加 API 密钥
vim ~/.clawlet/config.json

# 运行网关
docker run -v ~/.clawlet:/root/.clawlet clawlet gateway

# 或者运行单个命令
docker run -v ~/.clawlet:/root/.clawlet --rm clawlet agent -m "Hello"
docker run -v ~/.clawlet:/root/.clawlet --rm clawlet status

Clawlet 快速上手指南

Clawlet 是一款超轻量级、高效的个人 AI 助手。它是一个独立的静态二进制文件，无需运行时环境，无需 CGO，内置 SQLite 和向量搜索功能，开箱即用。

环境准备

• 操作系统：支持 macOS (Intel/Apple Silicon)、Linux 等主流系统。
• 前置依赖：无。Clawlet 为单文件二进制，无需安装 Python、Node.js 或 Docker 即可运行（除非你选择使用 Docker 部署）。
• API 密钥：需准备一个大模型服务商的 API Key（如 OpenRouter, OpenAI, Anthropic, Gemini）或本地大模型服务（如 Ollama）。

安装步骤

方式一：直接下载二进制文件（推荐）

访问 GitHub Releases 下载对应系统的压缩包。

macOS (Apple Silicon) 一键安装命令：

curl -L https://github.com/mosaxiv/clawlet/releases/latest/download/clawlet_Darwin_arm64.tar.gz | tar xz
mv clawlet ~/.local/bin/

提示：请确保 ~/.local/bin/ 已添加到你的 $PATH 环境变量中。其他系统请下载对应架构的文件并手动移动至路径下。

方式二：使用 Docker

如果你更倾向于容器化部署：

# docker-compose.yml
services:
  clawlet:
    image: ghcr.io/mosaxiv/clawlet:latest
    volumes:
      - ~/.clawlet:/root/.clawlet
    command: gateway
    restart: unless-stopped

启动服务：

docker compose up -d

基本使用

1. 初始化配置

首次使用前，需要运行 onboard 命令初始化工作区并配置 API Key 和模型。

示例：使用 OpenRouter 接入 Claude 模型

clawlet onboard \
  --openrouter-api-key "sk-or-..." \
  --model "openrouter/anthropic/claude-sonnet-4.5"

注：如果使用本地 Ollama，只需指定模型即可，无需 API Key： clawlet onboard --model "ollama/qwen2.5:14b"

2. 检查配置状态

确认配置是否生效：

clawlet status

3. 开始对话

直接在命令行与 AI 助手交互：

clawlet agent -m "What is 2+2?"

4. 进阶：启用长期记忆（可选）

Clawlet 支持基于语义的记忆搜索。若需启用，编辑配置文件 ~/.clawlet/config.json，在 agents.defaults 中添加 memorySearch 配置：

{
  "env": {
    "OPENAI_API_KEY": "sk-..."
  },
  "agents": {
    "defaults": {
      "memorySearch": {
        "enabled": true,
        "provider": "openai",
        "model": "text-embedding-3-small"
      }
    }
  }
}

启用后，助手将自动索引工作区下的 MEMORY.md 及 memory/ 目录文件，并获得 memory_search 工具以检索过往上下文。

5. 连接聊天软件（可选）

Clawlet 可作为网关连接到 Telegram、WhatsApp、Discord 或 Slack。

示例：连接 Telegram

1. 在 ~/.clawlet/config.json 中添加配置：

   {
     "channels": {
       "telegram": {
         "enabled": true,
         "token": "123456:ABCDEF...",
         "allowFrom": ["你的 Telegram 数字 ID"]
       }
     }
   }
   

2. 启动网关服务：

   clawlet gateway
   

现在，你可以在对应的聊天软件中与你的个人 AI 助手对话了。