Stavrobot

Stavrobot 是一个基于“AI 助手所需的一切访问权限，且不多一分”的原则构建的个人 AI 助手。

它拥有 AI 助手的所有优秀功能，但专注于沙箱化、隔离和最小权限。它很轻量，只需 docker compose up 即可部署。

功能

• 安全。 一切都在容器中运行，你的主机操作系统对 AI 完全不可见。除非你允许，否则 AI 看不到任何秘密。
• 轻量。 不会为每个组件运行一个容器。所有插件都在一个容器中运行，通过 Unix 权限隔离。
• 使用你想要的任何模型。 本地、OpenRouter、Anthropic/OpenAI。只要是 Pi 支持的，机器人就能用。
• Signal/Telegram/WhatsApp/邮件集成。 双向消息，支持格式化、附件等。
• 三级知识体系。 在不撑爆上下文的情况下记住一切。智能且透明地从其记忆中检索数据。
• 低 Token 消耗。 进行了多种优化以减少 Token 使用。它内部甚至使用了 TOON。
• 插件。 安装插件并通过提供一个 git 仓库 URL 来扩展 Stavrobot 的能力。插件之间相互隔离——每个插件作为专用的系统用户运行，无法访问其他插件的文件或配置。
• 子代理。 主代理可以创建具有自己的对话上下文、系统提示和受限工具访问权限的子代理。适用于通过外部人员完成任务或安排事务，同时在外部人员和主代理之间建立缓冲区。
• 自编程。 代理可以编程并扩展自身。
• 沙箱化 Python 执行。 通过 uv 运行带有 pip 依赖的任意 Python 代码，与主机环境隔离。
• 调度。 代理可以调度自己的周期性或一次性任务。

快速开始

AI 辅助安装： 让你的编码 AI（Claude Code、Cursor、Windsurf 等）获取并执行 https://stavrobot.stavros.io/INSTALL.md —— 它将引导你完成整个设置过程。

手动安装：

1. 在 Telegram 上向 @BotFather 发消息创建一个机器人并复制 Token。向 @userinfobot 发消息以获取你的 Telegram 用户 ID（这用作聊天 ID）。

2. 将 env.example 复制为 .env，并将 POSTGRES_PASSWORD 改为一个安全的密码，将 TZ 改为你的时区。

3. 将 config.example.toml 复制到 data/main/config.toml，并填写必填字段：apiKey、password、publicHostname、[owner].name、[owner].telegram（你的聊天 ID）和 [telegram].botToken。文件中其他所有内容都是可选的。

4. docker compose up --build

就是这样。在 Telegram 上给你的机器人发消息，它会回复。有关 Signal、WhatsApp、邮件和其他选项的详细设置，请参见下面的详细设置章节。

设置

配置

1. 将 config.example.toml 复制到 data/main/config.toml。
2. 填写 API 密钥和设置。示例文件中每个部分都有注释说明。
3. 至少设置 authFile（或 apiKey）和 publicHostname。其他所有内容都是可选的。
4. 将 env.example 复制为 .env，并设置你的时区（TZ）。Postgres 凭据和其他环境设置也可以在那里覆盖。始终将 POSTGRES_PASSWORD 设置为一个安全的密码 —— 默认值是一个弱的占位符，不应在生产环境中使用。

自定义和兼容 OpenAI 的端点

Stavrobot 可以指向任何兼容 OpenAI 的端点（Ollama、LiteLLM、vLLM 等）或自定义的兼容 Anthropic 的代理，只需在 config.toml 中设置 baseUrl。有关必填字段和示例配置，请参阅 config.example.toml。

身份验证

应用支持两种身份验证模式：API 密钥或 OAuth。

• API 密钥： 在 config.toml 中设置 apiKey。无需登录或注销。
• OAuth： 在 config.toml 中设置 authFile（一个凭据存储路径）。登录页面支持 Pi 支持的任何 OAuth 提供商。
  • 登录： 在浏览器中访问 <你的主机名>/login。按照页面上的提示操作，凭据将保存到 auth 文件中。如果在机器人运行时身份验证过期，它会通过你的消息平台向你发送包含登录 URL 的消息。
  • 注销： 删除 authFile 路径下的文件。下次消息时机器人会检测到缺少凭据并提示你重新登录。

Claude Code 设置

coder 容器是可选的（仅在自编程功能时需要）。它使用带有订阅认证（OAuth）的 Claude Code，与主应用的 API 密钥分开。

Docker Compose 配置文件是用逗号分隔的，因此你可以组合使用（例如 COMPOSE_PROFILES=signal,coder）。

1. 在你的 .env 文件中将 COMPOSE_PROFILES 设置为包含 coder（例如 COMPOSE_PROFILES=coder，或者如果你也在使用 Signal，则为 COMPOSE_PROFILES=signal,coder）。
2. 启动容器：docker compose --profile coder up --build
3. 登录：docker compose exec -u coder coder claude（如果你尚未登录，它会提示你登录）。
4. 按照基于浏览器的 OAuth 流程操作。
5. 在你的配置中设置 [coder].model 为一个 Claude Code 模型别名（sonnet、opus 或 haiku）。

Signal 设置

Signal 需要一个单独的电话号码——不是你的个人号码。可以使用预付费 SIM 卡或 VoIP 号码。

1. 在你的 .env 文件中取消注释 COMPOSE_PROFILES=signal 以启用 signal-bridge 容器。
2. 构建容器：docker compose --profile signal build
3. 在容器上注册 Signal（选择一种）：
   • 链接到现有 Signal 账户： docker compose --profile signal run --rm --entrypoint bash signal-bridge -c 'signal-cli link -n "Stavrobot" | tee >(xargs -L 1 qrencode -t utf8)' —— 用你的手机扫描二维码（Signal > 设置 > 已链接设备）。
   • 注册新号码： docker compose --profile signal run --rm --entrypoint bash signal-bridge -c 'signal-cli -u +你的号码 register'，然后用 docker compose --profile signal run --rm --entrypoint bash signal-bridge -c 'signal-cli -u +你的号码 verify CODE' 验证。
4. 在你的配置中设置 [signal].account。
5. 启动容器：docker compose up --build
6. 首次启动后，通过 /settings 网页界面添加允许的号码。
7. 重要提示： signal-cli 不会解析尚未联系过的联系人的电话号码。机器人必须先向每个联系人发送第一条消息（通过电话号码），然后才能接收并识别来自他们的传入消息。要为所有者触发此操作，请运行：

Telegram 设置

1. 在 Telegram 上向 @BotFather 发消息，创建一个新机器人并复制 Token。
2. 在 Telegram 上向 @userinfobot 发消息以获取你的用户 ID（这用作聊天 ID）。
3. 在你的配置中设置 [telegram].botToken。
4. 在你的配置中将聊天 ID（不是你的手机号码）设置到 [owner].telegram 中。
5. 首次启动后，通过 /settings 网页界面添加允许的聊天 ID。
6. 应用启动时会自动注册 Webhook。

WhatsApp 设置

WhatsApp 需要一个单独的电话号码，否则你会给自己发消息，这实际上行不通。

WhatsApp 使用 Baileys，一个非官方的 WhatsApp Web 库，以 Companion 设备方式链接（类似于 WhatsApp Web）。不需要单独的电话号码——它链接到你现有的 WhatsApp 账户。

风险： Baileys 使用非官方 API。WhatsApp 可能会封禁使用它的账户。使用风险自负。

1. 在你的 config.toml 中添加一个 [whatsapp] 部分（格式请参阅 config.example.toml）。
2. 启动容器：docker compose up --build
3. 二维码会出现在应用日志中（docker compose logs -f app）。
4. 在手机上打开 WhatsApp，进入已链接设备，扫描二维码。
5. 会话在 ./data/whatsapp 中持久化，重启后不变。
6. 通过 /settings 网页界面添加允许的电话号码。

邮件设置

邮件使用 Cloudflare Email Worker 处理入站投递，使用 SMTP 处理出站。完整的 Worker 代码和详细设置说明请参阅 config.example.toml。

1. 在你的 config.toml 中添加一个 [email] 部分，包含 SMTP 凭据和一个随机的 webhookSecret。
2. 部署 Cloudflare Email Worker（代码在 config.example.toml 中），并在 Worker 上设置 WEBHOOK_URL 和 WEBHOOK_SECRET 环境变量。
3. 在 Cloudflare Email Routing 中，添加一条规则将入站邮件转发到该 Worker。
4. 通过 /settings 网页界面添加允许的发件人地址。

运行

docker compose up --build

API 在 http://localhost:10567/chat 可用。

注意： Docker Compose 只将应用暴露在 localhost:10567 上。要使其可从外部访问（Telegram/Signal Webhook 和 publicHostname 设置需要），请设置一个反向代理（例如 Nginx、Caddy）指向 localhost:10567。你也可以直接暴露端口，但不推荐，因为流量将是未加密的。

不使用 Docker

需要 Node.js >= 20 和一个运行中的 PostgreSQL 实例。

npm install && npm run build && npm start

注意：Python 执行和 Signal 集成只能在 Docker 容器内工作。

知识体系

Stavrobot 有一个三级知识体系：记忆、草稿本和数据库。它会自动很好地管理这些，但你了解它们很重要，因为你需要帮助机器人正确使用它们。

记忆总是整体注入到系统提示中。你应该谨慎使用它们，因为它们每次都会包含在上下文中，数量过多会增加上下文。一个好的记忆例如“用户喜欢非正式聊天风格。”，这是机器人每次都应该知道的事情，即使这会增加额外的上下文长度。

草稿本用于存储不经常访问但与某个主题相关的知识。草稿本条目有一个标题和一个正文，标题会自动注入到上下文中。对于重要但不太频繁需要、通常属于特定主题的事情使用它。

例如，一个好的草稿本条目是“饮食偏好”，包含你喜欢吃什么、什么时候吃等细节。机器人会看到有一个“饮食偏好”主题，但不会自动将实际文本加载到上下文中，只在需要时访问。

当你和机器人谈论食物时，它会知道有一个“饮食偏好”草稿本条目可以查看，并且通常会自己去做。

数据库是第三级，用于不属于记忆或草稿本的结构化或批量数据。机器人通过无限制的 SQL 对 PostgreSQL 拥有完整的读写访问权限，因此它可以创建表、运行查询和存储任何内容。对于列表、日志、结构化记录或任何更适合查询而不是作为散文阅读的数据使用它。

机器人通常很清楚何时使用什么，但有时你会想明确告诉它哪些信息放在哪里。

与其他人交谈

Stavrobot 可以通过 Signal、Telegram、WhatsApp 或邮件代你向他人发消息。需要和朋友安排晚餐吗？告诉机器人找到适合你们两人的时间，它会向他们发消息，协商日期，并添加到你的日历中。想要安排预约、协调团体活动，或者在你忙碌时向某人提问？只需告诉机器人你的需求以及要和谁交谈。

机器人为每次对话启动一个专用的子代理，带有自己的指令和上下文，因此它可以在不占用主聊天空间的情况下与对方来回沟通。任务完成后，它会禁用该联系人并向你报告结果。

为了安全起见，机器人需要满足两个条件才能与某人交谈：

1. 你将其添加到允许列表中。 前往 /settings 添加他们的电话号码（Signal 或 WhatsApp）或聊天 ID（Telegram）。这是每个联系人的一次性步骤。机器人无法修改此列表，无论何种情况都不能向列表之外的人发消息。
2. 机器人创建一个联系人记录。 当你要求机器人向允许列表上的人发消息时，它会创建一个联系人记录，并为对话启动一个专用的子代理。任务完成后，它会禁用该联系人，这将阻止双向消息，直到你要求机器人重新启用它。

一个典型流程：你通过 /settings 一次性添加朋友的电话号码到允许列表，然后告诉机器人“找下周和 Alex 吃晚饭的时间”。机器人为 Alex 创建一个联系人记录，启动一个子代理，通过 Signal 向 Alex 发消息，来回沟通找到日期，并向你报告结果。

技能

技能是纯文本指令文件，用来教机器人新能力——比如创建表、存储知识、制作页面或遵循特定工作流。它们不是代码；而是机器人读取并遵循的自然语言指令。

要安装技能系统，告诉机器人获取 https://stavrobot.stavros.io/skills/bootstrap.md 并遵循其指令。

完整的可用技能列表在 https://stavrobot.stavros.io/skills/index.md。要安装一个技能，只需告诉机器人从该 URL 获取并安装它。机器人会向你显示技能的功能，并在继续之前请求确认。

技能文件位于此仓库的 pages 分支上（通过 Cloudflare Pages 提供）。要贡献一个技能，在该分支上的 skills/ 目录下添加一个 Markdown 文件。每个技能文件包含带有 title、description、version 和可选的 author 的 YAML 前言，后跟正文中的纯语言指令。完整编写指南请参见 SKILL-AUTHORING.md。向 pages 分支提交 PR。

如何创建自己的插件

有关创建 Stavrobot 插件所需的一切，请参见 PLUGIN.md。该文档也可以作为人类和 LLM 的参考。

推荐插件

插件对于启用机器人的核心功能相当必要，例如“听”语音笔记、回复语音笔记、感知你周围的地点、搜索网络等。

这些功能不内置提供，以便你可以随心所欲地定制你的机器人。不过，你应该安装插件，否则你会缺少关键功能。

你可以在这里找到一些第一方插件：

https://github.com/orgs/stavrobot/repositories

架构

三个核心 Docker 容器：app（TypeScript 服务器，暴露 POST /chat，在 POST /telegram/webhook 处理 Telegram Webhook，在 POST /email/webhook 处理入站邮件 Webhook，并通过 Baileys 在进程中运行 WhatsApp），postgres（PostgreSQL 17 用于持久状态），以及 plugin-runner（Node.js 服务器 —— 列出、检查并执行插件，包括本地创建的和通过 git 安装的）。一个可选的 coder 容器（用于创建和修改可编辑插件的 Claude Code 无头代理）通过 coder Docker Compose 配置文件启用。主代理可以创建子代理，每个子代理都有自己的对话历史、系统提示和工具白名单。对话者是指派给代理用于入站消息路由的联系人记录。

许可证

AGPL-3.0