
Stavrobot 是一个个人 AI 助手,其构建原则是“AI 助手所需的一切访问权限,不多不少”。
它具备 AI 助手的所有出色功能,但专注于沙箱化、隔离和最小权限。它轻量级,只需执行 docker compose up 即可部署。
uv 运行带 pip 依赖的任意 Python 代码,与宿主环境隔离。AI 辅助安装: 让你的编程 AI(Claude Code、Cursor、Windsurf 等)获取并遵循 https://stavrobot.stavros.io/INSTALL.md —— 它会以交互方式引导你完成整个设置过程。
手动安装:
在 Telegram 上给 @BotFather 发消息创建一个机器人并复制 token。给 @userinfobot 发消息获取你的 Telegram 用户 ID(用作聊天 ID)。
将 env.example 复制为 .env,并将 POSTGRES_PASSWORD 改为安全的值,将 TZ 改为你的时区。
将 config.example.toml 复制为 data/main/config.toml,并填写必填字段:apiKey、password、publicHostname、[owner].name、[owner].telegram(你的聊天 ID)以及 [telegram].botToken。文件中的其他内容均为可选。
docker compose up --build
就这样。在 Telegram 上给你的机器人发消息,它就会回复。有关 Signal、WhatsApp、电子邮件及其他选项的详细设置,请参阅下文。
config.example.toml 复制为 data/main/config.toml。authFile(或 apiKey)和 publicHostname。其他内容均为可选。env.example 复制为 .env 并设置你的时区(TZ)。Postgres 凭据和其他环境设置也可以在此覆盖。务必将 POSTGRES_PASSWORD 设置为安全的值 —— 默认值是一个弱占位符,不应在生产环境中使用。应用启动后,打开 /settings/config 即可在浏览器中编辑 config.toml。该页面受 HTTP Basic Auth 保护,并显示原始配置,包括其中包含的任何机密信息。有效保存会创建一个 <CONFIG_PATH>.bak 备份,保存新内容并重启应用;这会中断任何正在进行的智能体回合。
plugin-runner、coder、signal-bridge 和 python-runner 仅在启动时读取 config.toml。影响它们的更改(例如密码)需要手动重启这些容器。
通过设置 config.toml 中的 baseUrl,可以将 Stavrobot 指向任何 OpenAI 兼容端点(Ollama、LiteLLM、vLLM 等)或自定义的 Anthropic 兼容代理。所需字段和示例配置请参见 config.example.toml。仅对支持思考的模型设置 reasoning = true,因为正是它使 thinkingLevel 在自定义端点上生效。
该应用支持两种身份验证模式:API 密钥或 OAuth。
config.toml 中设置 apiKey。无需登录或注销。config.toml 中设置 authFile(用于存储凭据的路径)。登录页面可与 Pi 支持的任何 OAuth 提供商配合使用。
<your-hostname>/login。按照页面上的提示操作,凭据将保存到 auth 文件。Stavrobot 会选择提供商的无头登录方式,因此你永远不会被重定向到无法访问的 localhost 回调。使用 Anthropic 时,在你选择 Authorize 后,Anthropic 会显示一个代码,你将其复制并粘贴到 Stavrobot 登录页面。具有设备代码流程的提供商则会在 Stavrobot 页面上显示代码,你在提供商的网站上输入该代码。如果机器人在运行期间身份验证过期,它会通过你的消息平台向你发送包含登录 URL 的消息。authFile 路径下的文件。机器人将在下一条消息时检测到凭据缺失,并提示你重新登录。coder 容器是可选的(仅自编程功能需要)。默认情况下,它使用带订阅身份验证(OAuth)的 Claude Code,与主应用的 API 密钥分开。若要改用 Anthropic 兼容的 API 端点,请在 config.toml 中同时设置 [coder].apiKey 和 [coder].baseUrl;Claude Code 随后会将它们用作 ANTHROPIC_API_KEY 和 ANTHROPIC_BASE_URL。顶层的 apiKey/baseUrl 仅配置主应用的模型,绝不会影响 coder。仅设置两个 [coder] 键中的一个会导致启动错误。
Docker Compose 配置文件以逗号分隔,因此你可以组合它们(例如 COMPOSE_PROFILES=signal,coder)。
.env 文件中设置 COMPOSE_PROFILES 以包含 coder(例如 COMPOSE_PROFILES=coder,或者如果你同时使用 Signal,则为 COMPOSE_PROFILES=signal,coder)。docker compose --profile coder up --build[coder].apiKey/[coder].baseUrl,请跳过此步骤和下一步):docker compose exec -u coder coder claude(如果你尚未登录,它会提示你登录)。[coder].model 设置为 Claude Code 模型别名(sonnet、opus 或 haiku)。Signal 需要单独的电话号码——不是你的个人号码。预付费 SIM 卡或 VoIP 号码均可使用。
.env 文件中取消注释 COMPOSE_PROFILES=signal,以启用 signal-bridge 容器。docker compose --profile signal builddocker 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 +YOUR_NUMBER register',然后使用 docker compose --profile signal run --rm --entrypoint bash signal-bridge -c 'signal-cli -u +YOUR_NUMBER verify CODE' 进行验证。[signal].account。docker compose up --build/settings Web UI 添加允许的号码。docker compose exec app node -e "fetch('http://localhost:3001/chat',{method:'POST',headers:{'Content-Type':'application/json'},body:JSON.stringify({message:'Send the message \"Hello from Stavrobot\" to my Signal number.'})}).then(r=>r.text()).then(console.log)"
[telegram].botToken。[owner].telegram 中设置聊天 ID(不是你的手机号码)。/settings Web 界面添加允许的聊天 ID。WhatsApp 需要一个单独的电话号码,否则你就是在给自己发消息,这实际上行不通。
WhatsApp 使用 Baileys,这是一个非官方的 WhatsApp Web 库,作为配套设备(类似 WhatsApp Web)进行关联。无需单独的电话号码——它会关联到你现有的 WhatsApp 账户。
风险: Baileys 使用非官方 API。WhatsApp 可能会封禁使用它的账户。使用风险自负。
config.toml 中添加 [whatsapp] 部分(格式参见 config.example.toml)。docker compose up --builddocker compose logs -f app)。./data/whatsapp 中。/settings Web 界面添加允许的电话号码。电子邮件使用 Cloudflare Email Worker 进行入站投递,使用 SMTP 进行出站发送。完整的 worker 代码和详细设置说明请参见
config.example.toml。
config.toml 中添加 [email] 部分,包含 SMTP 凭据和一个随机的 webhookSecret。config.example.toml 中),并在 worker 上设置 WEBHOOK_URL 和 WEBHOOK_SECRET 环境变量。/settings Web 界面添加允许的发件人地址。配置 Pebble Index,使用 Stavrobot 配置的密码,通过 HTTP
Basic 认证将 ring webhook 发送到 POST /pebble-index/webhook。multipart 请求必须
包含 recordedAt(epoch 毫秒)和 client,并且可以包含 transcription
和 audio/mp4 格式的 audio 文件。音频录音会作为 .m4a
附件排队等待 agent 处理。
docker compose up --build
API 可在 http://localhost:10567/chat 访问。完整端点列表请参见 HTTP API。
注意: Docker Compose 仅在 localhost:10567 上暴露应用。若要从外部访问,请设置指向 localhost:10567 的反向代理(例如 Nginx、Caddy)。Signal webhook 以及 publicHostname 设置(用于机器人发送的链接,如登录、页面)都需要此配置。Telegram 无需可公开访问的端点或 webhook,因为应用会对其进行长轮询。你也可以直接暴露端口,但不推荐这样做,因为流量将不会被加密。
需要 Node.js >= 26 以及一个运行中的 PostgreSQL 实例。
npm install && npm run build && npm start
注意:Python 执行和 Signal 集成仅在 Docker 容器内有效。
除下文标记为 public 的端点外,每个端点都需要使用 config.toml 中的 password 进行 HTTP Basic 认证(用户名会被忽略)。错误响应是形如 {"error": "..."} 的 JSON 对象。
POST /chat向 agent 发送消息并返回其回复。这是主要入口:Web UI、Signal 桥接、插件运行器、coder 和 cron 调度器都使用它。
消息通过单个队列逐条处理。默认情况下,请求会阻塞直到 agent 完成本轮处理,如果 agent 使用了工具,这可能需要一段时间。设置 "async": true 可在消息通过 enqueueMessage 提交后立即确认,而不等待本轮处理完成。
请求体是一个 JSON 对象(最大 25 MB),包含以下字段。message、files 或 attachments 中至少需要提供一个。