Spacebot

一款面向团队、社区及多用户环境的AI智能体。
同时思考、执行并响应——并非依次进行。
永不阻塞，永不遗忘。

spacebot.sh • 工作原理 • 架构 • 快速入门 • 技术栈 • 文档

通过spacebot.sh一键部署 — 连接你的Discord、Slack、Telegram或Twitch，配置好你的智能体即可使用。无需自行托管。

---

问题所在

大多数AI智能体框架都在单一会话中运行所有任务。一个大语言模型线程负责对话、思考、工具执行、记忆检索以及上下文压缩——全部在一个循环里完成。当它忙于处理任务时，就无法与你交流；在压缩上下文时，又会进入“黑屏”状态；而当它调用记忆时，原始结果往往会混入上下文中，造成干扰。

虽然OpenClaw确实引入了子智能体的概念，但其管理方式并不完善，且缺乏对子智能体使用的有效约束。整个系统的瓶颈始终在于单一会话。

Spacebot则将这一单体架构拆分为多个专门化的进程，每个进程只负责一项特定任务，并将其他事务委托给相应的组件。

---

专为团队与社区打造

大多数AI智能体都是为单人单次对话设计的。而Spacebot则是为多人协作场景量身定制——无论是拥有数百名活跃成员的Discord社区、包含多个团队并行工作的Slack工作区，还是跨越不同时区协同行动的Telegram群组。

这正是Spacebot架构存在的意义。对于单线程智能体而言，一旦两人同时发言，系统就会崩溃。而Spacebot采用的委托模式使其能够同时处理以下任务：思考用户A的问题、为用户B执行任务、回应用户C的闲聊——这一切都能在同一时刻完成，且彼此互不干扰。

面向社区 — 将Spacebot接入Discord服务器，它能高效处理跨频道和线程的并发对话，记住每位成员的上下文信息，并在不“黑屏”的情况下完成实际工作（如代码编写、研究任务、文件操作等）。最多可支持五十人同时与其互动。

针对消息高频涌入的频道 — 当大量消息快速到达时，Spacebot并不会试图逐一回复。它内置的消息聚合系统能够检测到密集的消息流，将其合并为一次统一的交互回合，让大语言模型更好地理解当前情境，从而选择最值得关注的内容进行回应，或者在没有合适话题时保持沉默。此外，还可自定义去抖动时间、自动绕过私信，并确保大语言模型始终清楚哪些消息是同时到达的。

适用于团队 — 将Spacebot连接至Slack，每个频道都将拥有独立的对话会话及共享的记忆空间。它可以为一位工程师持续进行长时间的编程工作，同时回答另一位工程师的即时问题。后台的工作者负责处理繁重的任务，而频道始终保持流畅响应。

多智能体部署场景 — 在同一实例上运行多个智能体。例如，在Discord上部署一个性格友好的社区机器人，在Slack上部署一个严谨高效的开发助手，再搭配一个负责后台研究任务的智能体。每个智能体都拥有独立的身份、记忆和安全权限。只需一个二进制文件，一次部署即可实现。

部署方式

方法	你能获得什么
spacebot.sh	一键托管式部署。连接你的平台，配置好智能体，即刻使用。
自托管	单一Rust二进制文件。无需Docker，无服务器依赖，也无需微服务架构。克隆、构建、运行即可。
Docker	包含所有内容的容器镜像。挂载卷以保存持久化数据。

---

核心能力

任务执行

Spacebot的工作者预装了多种实用工具，可用于执行真实任务：

• Shell — 可运行任意命令，并支持设置超时时间
• File — 支持读取、写入和列出文件，同时会自动创建目录
• Exec — 可运行指定程序，支持传递参数和环境变量
• OpenCode — 启动一个完整的编码智能体作为持久性工作者，具备代码库探索、LSP感知及深度上下文管理功能
• Browser — 基于无头Chrome的自动化工具，配备无障碍树引用系统。导航、点击、输入、截图、管理标签页——大语言模型通过简短引用（如e0、e1）来定位元素，而非依赖易失效的CSS选择器
• Brave网络搜索 — 提供带有新鲜度过滤、本地化支持及可配置结果数量的网页搜索功能

消息交互

Spacebot原生适配Discord、Slack、Telegram、Twitch以及Webchat，全面支持各平台的功能特性：

• 消息聚合 — 高频消息会被批量整合为一次大语言模型交互，附带时间上下文信息，使智能体能够综合判断当前局势，而非盲目回复
• 文件附件 — 支持发送和接收文件、图片及文档
• 富文本消息 — Discord支持嵌入卡片、交互式按钮、下拉菜单和投票；Slack则支持Block Kit消息和Slash命令
• 线程功能 — 自动为长对话创建线程
• 反应功能 — 支持在消息上添加表情反应
• 打字指示器 — 当智能体正在思考时，会显示视觉反馈
• 历史消息回填 — 在首次收到消息时，自动加载最近的对话上下文
• 按频道权限控制 — 支持公会、频道及私信级别的访问控制，且可热更新
• Webchat — 可嵌入的门户聊天界面，采用SSE流式传输，每个智能体拥有独立的会话隔离

记忆

这不是 Markdown 文件，也不是向量数据库中的“非结构化”块。Spacebot 的记忆是一个类型化的、图状连接的知识系统——正是这种有明确观点的结构，使得代理开箱即用，高效工作。

每个记忆都有一个类型、一个重要性评分，以及连接到相关记忆的图边。代理不仅仅是“记住一些事情”——它能区分自己学到的事实、做出的决策、正在努力实现的目标，以及用户表达的偏好。正是这种结构让大脑皮层能够合成一份有用的简报，而不是简单地将原始搜索结果塞入上下文中。

• 八种记忆类型——事实、偏好、决策、身份、事件、观察、目标、待办事项
• 图边——相关、更新、矛盾、因果、部分
• 混合检索——通过互反排名融合（RRF）将向量相似度与全文搜索相结合
• 记忆导入——将文件转储到 ingest/ 文件夹中，Spacebot 会自动提取结构化记忆。支持文本、Markdown 和 PDF 文件。从 OpenClaw 迁移？只需将你的 Markdown 记忆文件丢进去，然后走开。
• 跨渠道检索——分支可以读取其他对话的记录
• 记忆公告——大脑皮层会定期生成代理知识的简报，并将其注入到每次对话中
• 预热就绪合约——分支/工作者/定时任务调度会检查 ready_for_work 状态（预热状态 + 嵌入已准备好 + 最新公告），记录冷启动指标，并在不阻塞渠道的情况下触发后台强制预热

调度

从对话或配置中创建和管理的 Cron 任务：

• 自然调度——“每 30 分钟检查一次我的收件箱”会变成一个带有交付目标的 Cron 任务
• 严格的时间表——使用 Cron 表达式来精确控制本地时间执行（例如，0 9 * * * 表示每天早上 9 点）
• 旧版间隔兼容性——现有的 interval_secs 任务仍然会运行，并且可以继续配置
• 可配置超时——为每个任务设置 timeout_secs 来限制执行时间（默认 120 秒）
• 活跃时段——将任务限制在特定的时间窗口内（支持午夜跨越）
• 断路器——连续失败 3 次后自动禁用
• 完整的代理能力——每个任务都会获得一个新的通道，配备分支和工作者

模型路由

四层路由系统，为每一次 LLM 调用选择合适的模型。结构化路由处理常见情况——进程类型和任务类型在启动时已知。提示级别路由则处理其余情况，通过对用户消息进行评分，自动将简单的请求降级到更便宜的模型。

• 进程类型默认值——通道使用最佳的对话模型，工作者使用快速且廉价的模型，压缩者则使用最便宜的层级
• 任务类型覆盖——编码工作者会升级到更强的模型，而摘要工作者则保持低成本
• 提示复杂度评分——轻量级关键词评分器将用户消息分为三个等级（轻、标准、重），并路由到能够处理该消息的最便宜模型。仅对用户消息进行评分——系统提示和上下文不包括在内。耗时不到 1 毫秒，无需外部调用。
• 备用链路——当某个模型返回 429 或 502 错误时，链路中的下一个模型会自动接管
• 速率限制跟踪——所有代理中被 429 错误标记的模型都会在可配置的冷却期内被降级优先级
• 代理专属路由配置——生态、均衡或高级预设，调整各层级对应的模型。预算代理会将简单消息路由到免费模型，而高级代理则坚持使用 opus 模型。

[defaults.routing]
channel = "anthropic/claude-sonnet-4"
worker = "anthropic/claude-haiku-4.5"

[defaults.routing.task_overrides]
coding = "anthropic/claude-sonnet-4"

[defaults.routing.prompt_routing]
enabled = true
process_types = ["channel", "branch"]

[defaults.routing.fallbacks]
"anthropic/claude-sonnet-4" = ["anthropic/claude-haiku-4.5"]

Z.ai (GLM) 示例——使用 GLM 模型，需订阅 GLM 编程计划：

[llm]
zhipu_key = "env:ZHIPU_API_KEY"

[defaults.routing]
channel = "zhipu/glm-4.7"
worker = "zhipu/glm-4.7"

[defaults.routing.task_overrides]
coding = "zhipu/glm-4.7"

Ollama 示例——直接对接本地 Ollama 实例：

[llm]
ollama_base_url = "http://localhost:11434"

[defaults.routing]
channel = "ollama/gemma3"
worker = "ollama/gemma3"

[defaults.routing.task_overrides]
coding = "ollama/qwen3"

自定义提供商示例——添加任何兼容 OpenAI 或 Anthropic 的端点：

[llm.provider.my-provider]
api_type = "openai_completions"  # 或 "openai_chat_completions", "openai_responses", "anthropic"
base_url = "https://my-llm-host.example.com"
api_key = "env:MY_PROVIDER_KEY"

[defaults.routing]
channel = "my-provider/my-model"

Azure OpenAI 服务——配置 Azure OpenAI 部署：

[llm.provider.azure]
api_type = "azure"
base_url = "https://{resource-name}.openai.azure.com"
api_key = "env:AZURE_API_KEY"
api_version = "2024-06-01"  # 必填
deployment = "gpt-4o"        # 必填——你的部署名称

[defaults.routing]
channel = "azure/gpt-4o"
worker = "azure/gpt-4o-mini"

重要提示：

• base_url 必须以 .openai.azure.com 结尾
• api_version 和 deployment 是必填字段
• API 密钥认证会通过 api-key 头部自动处理
• 对于 Azure AI Foundry（通过 Azure 的模型目录访问 Anthropic、Llama 等模型），请使用 api_type = "openai_chat_completions"，并相应配置部署端点。

此外，内置的提供商还包括 Kilo Gateway、OpenCode Go、NVIDIA、 MiniMax、Moonshot AI (Kimi) 以及 Z.AI 编程计划——可通过 [llm] 中的 kilo_key、opencode_go_key、nvidia_key、minimax_key、moonshot_key 或 zai_coding_plan_key 进行配置。

技能

可扩展的技能系统，与 skills.sh 集成：

• skills.sh 注册中心——只需一条命令即可安装公共生态系统中的任何技能
• CLI 管理——使用 spacebot skill add owner/repo 来安装、列出、移除和检查技能
• 工作者注入——技能会被注入到工作者的系统提示中，用于执行特定任务
• 捆绑资源——脚本、参考文献和资产随技能一起打包
• OpenClaw 兼容——可以直接使用现有的 OpenClaw 技能，或者来自 skills.sh 的任何技能。

从注册中心安装技能：

spacebot skill add vercel-labs/agent-skills
spacebot skill add anthropics/skills/pdf
spacebot skill list

MCP 集成

将工作进程连接到外部 MCP（模型上下文协议）服务器，以访问任意工具——数据库、API、SaaS 产品、自定义集成等——而无需原生 Rust 实现：

• 每个代理的配置 — 每个代理在 config.toml 中声明自己的 MCP 服务器
• 两种传输方式 — 使用 stdio（子进程）处理本地工具，使用可流式传输的 HTTP 处理远程服务器
• 自动工具发现 — 工具通过 MCP 协议被发现，并以命名空间名称（{server}_{tool}）注册到工作进程的 ToolServer 上
• 自动重试 — 连接失败时会在后台以指数退避策略重试（初始 5 秒，上限 60 秒，最多 12 次）。故障服务器绝不会阻塞代理启动
• 热加载支持 — 在配置中添加、移除或更改服务器时，它们会实时重新协调
• API 管理 — 提供完整的 CRUD API，在 /api/mcp/ 下管理服务器定义并以编程方式监控连接状态

[[mcp_servers]]
name = "filesystem"
transport = "stdio"
command = "npx"
args = ["-y", "@modelcontextprotocol/server-filesystem", "/workspace"]

[[mcp_servers]]
name = "sentry"
transport = "http"
url = "https://mcp.sentry.io"
headers = { Authorization = "Bearer ${SENTRY_TOKEN}" }

安全性

Spacebot 运行自主的 LLM 进程，这些进程会执行任意 shell 命令并派生子进程。安全性并非附加功能，而是一个分层系统，旨在确保即使发生单点故障，也不会泄露凭据或破坏隔离机制。

凭据隔离

秘密分为两类：系统级（LLM API 密钥、消息传递令牌——绝不会暴露给子进程）和 工具级（CLI 凭据，如 GH_TOKEN——作为环境变量注入到工作进程中）。类别根据秘密名称自动分配，也可显式设置。

• 环境净化 — 每个子进程都从一个干净的环境开始（Linux 上使用 --clearenv，其他平台使用 env_clear()）。只有安全的基础变量（PATH、HOME、LANG）、工具级秘密以及显式指定的 passthrough_env 条目才会保留。在沙箱模式下，HOME 被设置为工作目录；在透传模式下，HOME 继承父进程的环境。系统级秘密绝不会进入任何子进程
• 秘密存储 — 凭据存储在一个专用的 redb 数据库中，而不是 config.toml 文件中。配置文件通过别名引用秘密（例如 anthropic_key = "secret:ANTHROPIC_API_KEY"），因此配置文件可以安全地展示、截图或直接查看
• 静态加密 — 可选的 AES-256-GCM 加密，使用通过 Argon2id 导出的主密钥。主密钥存储在操作系统凭据存储中（macOS Keychain、Linux 内核密钥环），绝不在磁盘上、不在环境变量中，也绝不会被工作进程的子进程访问
• 密钥环隔离 — 在 Linux 上，工作进程通过 pre_exec 启动时会创建一个新的空会话密钥环。即使没有启用沙箱，工作进程也无法访问父进程的内核密钥环，而主密钥就存储在那里
• 输出脱敏 — 所有工具使用的秘密值都会在工作进程输出到达渠道或 LLM 上下文之前被屏蔽。滚动缓冲区会处理跨多个数据块的秘密信息。渠道只会看到 [REDACTED]，而绝不会看到原始值
• 工作进程秘密管理 — 工作进程可以通过 secret_set 工具存储自己获取的凭据（如账户创建时的 API 密钥、OAuth 令牌等）。存储的秘密会立即对后续工作进程可用

进程隔离

• 进程沙箱 — shell 和 exec 工具运行在操作系统级别的文件系统隔离环境中。在 Linux 上，bubblewrap 创建一个挂载命名空间，其中整个文件系统除代理的工作目录和配置的可写路径外均为只读。在 macOS 上，sandbox-exec 通过 SBPL 配置文件强制实施类似的限制。这些限制由内核强制执行，而非字符串过滤
• 动态沙箱模式 — 沙箱设置支持热加载。可通过仪表板或 API 切换，无需重启代理
• 工作目录隔离 — 文件工具会对所有路径进行规范化，并拒绝任何位于代理工作目录之外的路径。逃逸的符号链接也会被阻止
• 泄漏检测 — 在渠道出口处（回复和明文回退输出）会对明文、URL 编码、base64 和十六进制编码中的秘密模式进行检查。匹配秘密模式的输出会被拦截；工作进程的工具输出不再会导致工作进程崩溃
• 库注入拦截 — exec 工具会拦截危险的环境变量（如 LD_PRELOAD、DYLD_INSERT_LIBRARIES、NODE_OPTIONS 等），这些变量可能会劫持子进程的加载过程
• SSRF 防护 — 浏览器工具会阻止向云元数据端点、私有 IP 地址、环回地址和链路本地地址发起请求
• 身份文件保护 — 对 SOUL.md、IDENTITY.md 和 USER.md 的写操作会在应用层被阻止
• 持久化二进制存储 — PATH 中的 tools/bin 目录可以在托管升级过程中保持不变。工作进程被指示将二进制文件安装到该目录，而不是临时的包管理器位置

[agents.sandbox]
mode = "enabled"                              # "enabled"（默认）或 "disabled"
writable_paths = ["/home/user/projects/myapp"] # 除工作目录外的额外可写目录
passthrough_env = ["CUSTOM_VAR"]              # 将特定环境变量传递给工作进程

---

工作原理

五种进程类型，每种各司其职。

渠道

面向用户的 LLM 进程——与人类沟通的桥梁。每个对话（Discord 线程、Slack 频道、Telegram 私信等）对应一个渠道。拥有灵魂、身份和个性，与用户交流，并将其他任务委托给工作进程。

渠道 不 负责：直接执行任务、自行搜索记忆，或进行任何繁重的工具操作。它始终保持响应，绝不会因工作繁忙或内存压缩而卡顿。

当需要思考时，它会分支；当需要完成工作时，它会派生一个工作进程。

分支

渠道上下文的一个分支，用于独立思考。拥有渠道的完整对话历史——相同的上下文、相同的记忆和相同的理解。独立运作，渠道仅能看到最终结果，而看不到中间过程。

用户 A：“你对 X 了解什么？”
    → 渠道分支（branch-1）

用户 B：“嘿，最近怎么样？”
    → 渠道直接回复：“还不错！正在帮 A 处理一件事。”

Branch-1 得出结论：“关于 X，我找到的内容如下：[精选记忆]”
    → 渠道在下一次轮询时看到分支结果
    → 游戏频道回复用户 A，告知其调查结果

多个分支可以同时运行。先完成的分支会优先被合并。每个分支在创建时都基于渠道的上下文进行分支，就像 Git 分支一样。

工作者

独立运行的进程，负责执行具体任务。它们接收特定的任务、专注的系统提示以及与任务相匹配的工具。没有对话上下文，也没有灵魂或个性。

一次性任务 — 执行一项工作并返回结果。例如摘要生成、文件操作、单次性任务等。

交互式任务 — 长时间运行，可接受来自对话通道的后续输入。例如编码会话、多步骤任务等。

用户: “重构认证模块”
    → 分支会启动一个交互式的编码工作者
    → 分支返回: “已开始认证模块的重构编码会话”

用户: “其实，也请更新一下测试”
    → 对话通道将消息路由到当前活跃的工作者
    → 工作者接收到后续指令，并在原有上下文中继续执行

工作者是可插拔的。任何能够接收任务并汇报状态的进程都可以作为工作者。

内置工作者 附带了 Shell、文件、执行和浏览器等工具，开箱即用。它们可以编写代码、执行命令、管理文件、浏览网页——足以从零开始构建整个项目。

OpenCode 工作者 是一种内置集成，它会以持久子进程的形式启动一个完整的 OpenCode 编码代理。OpenCode 自带代码库探索、LSP 感知和上下文管理功能——专为深度编码会话而设计。当用户请求复杂的重构或新功能时，对话通道可以启动一个 OpenCode 工作者，该工作者在整个会话过程中都能保持对代码库的深刻理解。无论是内置工作者还是 OpenCode 工作者，都支持交互式的后续操作。

压缩器

并非 LLM 进程。它是每个对话通道的程序化监控器，用于监测上下文大小，并在对话通道内容过多之前触发压缩操作。

阈值	行动
>80%	后台压缩（总结最旧的 30%）
>85%	强制压缩（总结最旧的 50%）
>95%	紧急截断（直接丢弃，不使用 LLM）

压缩工作者会在对话通道旁运行，不会阻塞通道的正常流程。总结内容会按时间顺序堆叠在上下文窗口的顶部。

皮层

这是智能体的内部独白。唯一一个能够同时跨所有对话通道、工作者和分支进行观察的进程。它会生成一份“记忆简报”——由 LLM 定期更新并精选的智能体知识摘要，注入到每一次对话中。它还负责监督正在运行的进程（终止挂起的工作者、清理过时的分支），维护记忆图谱（衰减、修剪、合并近似重复项、跨通道整合），检测对话中的模式并形成观察记录。此外，它还提供一个直接的交互式管理员聊天界面，拥有全部工具访问权限，便于系统检查和手动干预。

---

架构

用户发送消息
    → 对话通道接收
        → 分支进入思考阶段（拥有对话通道的上下文）
            → 分支调用记忆，决定如何行动
            → 对于繁重任务，分支可能会启动一个工作者
            → 分支得出结论
        → 分支被删除
    → 对话通道回复用户

当对话通道的上下文占用率达到 80%
    → 压缩器检测到
        → 启动一个压缩工作者
            → 工作者总结旧的上下文并提取记忆
            → 将压缩后的摘要替换进上下文
    → 对话通道始终畅通无阻

各个进程的职责

进程	类型	工具	上下文
对话通道	LLM	回复、分支、启动工作者、路由	对话内容 + 压缩总结
分支	LLM	调用记忆、保存记忆、启动工作者	对话通道上下文的分叉
工作者	可插拔	Shell、文件、执行、浏览器（可配置）	新鲜的提示词 + 任务描述
压缩器	程序化	监控上下文、触发压缩工作者	无
皮层	LLM + 程序化	记忆管理、整合、系统监控	整个智能体范围

记忆系统

记忆是以结构化对象形式存储的，而非文件。每条记忆都是 SQLite 数据库中的一行，包含类型化的元数据和图谱连接，并与 LanceDB 中的向量嵌入相对应。

• 八种类型 — 事实、偏好、决策、身份、事件、观察、目标、待办
• 图谱边 — 关联、更新、矛盾、因果、部分
• 混合搜索 — 向量相似度 + 全文检索，通过倒排秩融合算法合并
• 三种创建路径 — 分支发起、压缩器发起、皮层发起
• 重要性评分 — 访问频率、时效性、图谱中心性。身份记忆不受衰减影响。

定时任务

计划好的周期性任务。每个定时任务都会获得一个全新的短期对话通道，具备完整的分支和工作者能力。

• 多个定时任务按照挂钟时间表（或传统的时间间隔）独立运行
• 存储在数据库中，可通过配置、对话或程序化方式创建
• Cron 表达式会根据解析后的时区执行，确保在本地时间准时触发
• 持久化的 next_run_at 游标用于实现确定性的重启行为和错过任务的快速推进
• 采用“先占后执行”的调度机制，防止多进程或重启的调度器重复触发周期性任务
• 一次性任务则采用“至多一次”的占取语义，并在执行开始前禁用
• 每个任务都有 timeout_secs 设置，以限制执行时间
• 如果连续失败三次，熔断器会自动禁用该任务
• 支持活动时段设置，并可在午夜时分自动切换
• 执行和交付的结果会被分别记录，且具有有限的重试/退避机制，以便主动重新发送

多智能体

每个智能体都是一个独立的实体，拥有自己的工作空间、数据库、身份文件、皮层和消息传递绑定。所有智能体共享同一个二进制文件、同一个 Tokio 运行时以及同一组 API 密钥。

---

Spacedrive 集成（未来）

Spacebot 是 Spacedrive 的 AI 对应产品——一个基于虚拟分布式文件系统的开源跨平台文件管理器。这两个项目各自独立且功能完备，但在设计上互为补充。Spacedrive 通过内容寻址身份、语义搜索和本地 AI 分析，在你的所有设备、云存储和平台上索引文件；而 Spacebot 则带来自主推理、记忆和任务执行能力。两者结合，便能打造出一个既会思考、又能记忆和行动的智能体——背后依托的是你所拥有的每一台设备上可查询的数 TB 数据。

完整愿景请参阅 路线图。

---

快速入门

前提条件

• Rust 1.85 或更高版本（可通过 rustup 安装）
• 来自任意支持提供商的 LLM API 密钥（Anthropic、OpenAI、OpenRouter、Kilo Gateway、Z.ai、Groq、Together、Fireworks、DeepSeek、xAI、Mistral、NVIDIA、MiniMax、Moonshot AI、OpenCode Zen、OpenCode Go）——或者使用 spacebot auth login 通过 Anthropic OAuth 进行登录

构建与运行

git clone https://github.com/spacedriveapp/spacebot
cd spacebot

# 可选：构建 OpenCode 嵌入式 UI（需要 Node 22+ 和 bun）
# 如果不执行此步骤，OpenCode 工作器仍然可以正常工作——“Workers”选项卡将显示对话记录视图。
# ./scripts/build-opencode-embed.sh

cargo build --release

最小配置

创建 config.toml 文件：

[llm]
openrouter_key = "env:OPENROUTER_API_KEY"

[defaults.routing]
channel = "anthropic/claude-sonnet-4"
worker = "anthropic/claude-sonnet-4"

[[agents]]
id = "my-agent"

[messaging.discord]
token = "env:DISCORD_BOT_TOKEN"

[[bindings]]
agent_id = "my-agent"
channel = "discord"
guild_id = "your-discord-guild-id"

# 可选：路由一个命名的适配器实例
[[bindings]]
agent_id = "my-agent"
channel = "discord"
adapter = "ops"

spacebot                      # 以后台守护进程方式启动
spacebot start --foreground   # 或在前台运行
spacebot stop                 # 优雅关闭
spacebot restart              # 先停止再启动
spacebot status               # 显示进程 ID 和运行时长
spacebot auth login           # 通过 Anthropic OAuth 进行认证

首次运行时，二进制文件会自动创建所有数据库和目录。更多详细信息请参阅快速入门指南。

身份验证

Spacebot 支持使用 Anthropic OAuth 作为静态 API 密钥的替代方案。您可以直接使用自己的 Claude Pro、Max 或 API 控制台订阅：

spacebot auth login             # 通过 Claude Pro/Max 进行 OAuth（打开浏览器）
spacebot auth login --console   # 通过 API 控制台进行 OAuth
spacebot auth status            # 显示凭据状态及过期时间
spacebot auth refresh           # 手动刷新访问令牌
spacebot auth logout            # 删除已存储的凭据

OAuth 令牌会存储在 anthropic_oauth.json 文件中，并在每次 API 调用前透明地自动刷新。当存在 OAuth 凭据时，它们会优先于静态的 ANTHROPIC_API_KEY。

---

技术栈

层次	技术
编程语言	Rust（2024 版）
异步运行时	Tokio
LLM 框架	Rig v0.31 — 代理循环、工具执行、钩子
关系型数据	SQLite（sqlx）— 对话记录、记忆图、定时任务
向量数据库 + FTS	LanceDB — 嵌入向量（HNSW）、全文检索（Tantivy）、混合搜索（RRF）
键值存储	redb — 设置、加密密钥
嵌入向量	FastEmbed — 本地嵌入生成
加密技术	AES-256-GCM — 静态数据加密
Discord	Serenity — 网关、缓存、事件、富文本消息、交互
Slack	slack-morphism — Socket Mode、事件、Block Kit、斜杠命令、通过消息编辑实现流式传输
Telegram	teloxide — 长轮询、媒体附件、群组/私信支持
Twitch	twitch-irc — 聊天集成，带有触发前缀
浏览器	Chromiumoxide — 通过 CDP 使用无头 Chrome
命令行界面	Clap — 命令行接口

无需任何服务器依赖。单个二进制文件即可运行。所有数据都存储在本地目录中的嵌入式数据库中。

---

文档

文档	描述
快速入门	设置、配置、首次运行
配置参考	完整的 config.toml 参考
代理	多代理设置与隔离
记忆	内存系统设计
工具	所有可用的 LLM 工具
压缩	上下文窗口管理
皮层	内存公告板与系统观察
定时任务	定期执行的任务
路由	模型路由与回退链
密钥	凭据存储、加密及输出脱敏
沙盒	进程隔离与环境净化
消息传递	适配器架构（Discord、Slack、Telegram、Twitch、Webchat、Webhook）
Discord 设置	Discord 机器人设置指南
浏览器	无头 Chrome 用于工作器
MCP	通过模型上下文协议连接外部工具服务器
OpenCode	OpenCode 作为工作器后端
理念	为什么选择 Rust

---

为什么选择 Rust

Spacebot 并不是聊天机器人——它是一个用于协调自主 AI 流程的层，这些流程可以并发运行、共享内存并相互委派任务。这属于基础设施范畴，而基础设施理应使用机器代码来实现。

Rust 的严格类型系统和编译器确保了每种逻辑都只有一种正确的表达方式。当多个 AI 流程共享可变状态并无需人工监督地创建任务时，“编译器不允许你这样做”恰恰是一项优势。最终结果是一个单一的二进制文件，没有任何运行时依赖、没有垃圾回收停顿，并且资源使用情况可预测。

完整的论述请参阅 docs/philosophy。

---

贡献说明

欢迎贡献！在编写任何代码之前，请先阅读 RUST_STYLE_GUIDE.md，并查看 AGENTS.md 以获取完整的实现指南。

1. 克隆仓库并创建分支
2. 创建一个功能分支
3. 如果尚未安装 just（https://github.com/casey/just），请先进行安装（例如：`brew install just或cargo install just --locked`）
4. 运行一次 ./scripts/install-git-hooks.sh（安装 pre-commit 格式化钩子）
5. 进行更改
6. 分别运行 just preflight 和 just gate-pr
7. 提交 Pull Request

虽然格式检查仍然会在 CI 中执行，但该钩子会在每次提交前运行 cargo fmt --all，从而更早地发现问题。just gate-pr 则与 CI 检查流程一致，包含迁移安全性检查、编译检查以及测试验证。

---

许可证

FSL-1.1-ALv2 — 功能性源代码许可证；两年后将转换为 Apache 2.0 许可证。详情请参阅 LICENSE。

Spacebot 快速上手指南

Spacebot 是一款专为团队、社区及多用户环境设计的 AI 代理工具。它采用并发架构，能够同时处理思考、执行和响应任务，支持 Discord、Slack、Telegram 等平台，具备强大的记忆系统和任务调度能力。

环境准备

系统要求

• 操作系统：Linux, macOS, Windows (WSL 推荐)
• 核心语言：Rust (用于编译源码或运行二进制文件)
• 内存：建议至少 2GB RAM（根据并发负载调整）
• 网络：需访问外部 LLM API (如 Anthropic, OpenAI, Z.ai, Ollama 等)

前置依赖

1. 安装 Rust (如果选择自托管编译)

   curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
   source $HOME/.cargo/env
   

   国内加速提示：若下载缓慢，可配置国内镜像源：

   export RUSTUP_DIST_SERVER=https://mirrors.tuna.tsinghua.edu.cn/rustup
   export RUSTUP_UPDATE_ROOT=https://mirrors.tuna.tsinghua.edu.cn/rustup/rustup
   curl --proto '=https' --tlsv1.2 -sSf https://mirrors.tuna.tsinghua.edu.cn/rustup/rustup-init.sh | sh
   

2. LLM API Key

   • 准备至少一个 LLM 服务的 API Key（如 Anthropic, OpenAI, Zhipu/GLM, 或本地 Ollama）。

3. 平台凭证

   • 根据目标部署平台（Discord/Slack/Telegram 等），准备好 Bot Token 或 App ID。

安装步骤

你可以选择以下三种方式之一进行部署：

方式一：一键云部署（推荐新手）

无需自行维护服务器，直接通过官方平台配置。

1. 访问 spacebot.sh
2. 连接你的社交平台账号（Discord, Slack, Telegram 等）。
3. 在网页界面配置 Agent 人格、记忆和工具权限。
4. 点击部署即可生效。

方式二：自托管（单二进制文件）

适合需要完全控制数据和本地运行的开发者。

1. 克隆仓库

   git clone https://github.com/spacedriveapp/spacebot.git
   cd spacebot
   

2. 编译构建

   cargo build --release
   

   编译完成后，二进制文件位于 target/release/spacebot。

3. 配置文件 在项目根目录创建 config.toml，参考以下最小化配置：

   [llm]
   # 示例：使用 Anthropic
   anthropic_key = "env:ANTHROPIC_API_KEY"
   
   [defaults.routing]
   channel = "anthropic/claude-sonnet-4"
   worker = "anthropic/claude-haiku-4.5"
   
   [platforms.discord]
   token = "env:DISCORD_BOT_TOKEN"
   

4. 运行

   export ANTHROPIC_API_KEY="your_api_key_here"
   export DISCORD_BOT_TOKEN="your_bot_token_here"
   ./target/release/spacebot
   

方式三：Docker 部署

适合容器化环境。

1. 拉取镜像并运行

   docker run -d \
     --name spacebot \
     -v $(pwd)/data:/app/data \
     -e ANTHROPIC_API_KEY="your_api_key_here" \
     -e DISCORD_BOT_TOKEN="your_bot_token_here" \
     -v $(pwd)/config.toml:/app/config.toml \
     ghcr.io/spacedriveapp/spacebot:latest
   

   注意：请将 config.toml 挂载到容器中，并确保环境变量已正确设置。

基本使用

1. 邀请机器人加入频道

• Discord: 在开发者门户生成 OAuth2 链接，勾选 bot 和 applications.commands 权限，邀请至服务器。
• Slack: 在 Slack API 页面创建应用，添加 Bot User 并安装到工作区。

2. 触发对话

在已添加 Spacebot 的频道中直接发送消息即可。Spacebot 会自动读取上下文并响应。

示例场景：

• 日常问答：

  用户："今天天气怎么样？" Spacebot: (调用搜索工具) "根据最新数据，今天北京晴朗，气温 25°C..."

• 代码任务 (需配置 OpenCode 工具)：

  用户："帮我写一个 Python 脚本来计算斐波那契数列。" Spacebot: (启动编码 Worker) "好的，正在生成代码... [输出代码块]"

• 定时任务：

  用户："每 30 分钟检查一次我的待办事项列表。" Spacebot: "已创建定时任务，将在每小时的 00 分和 30 分执行。"

3. 管理记忆与上下文

Spacebot 自动维护结构化记忆（事实、偏好、目标等）。你可以通过自然语言指令让它“记住”特定信息：

用户："记住我喜欢用 Rust 编写后端服务。" Spacebot: "已记录偏好：后端开发首选语言为 Rust。"

后续对话中，当涉及技术选型时，它会自动引用此偏好。

4. 高级配置（模型路由）

编辑 config.toml 以优化成本和性能。例如，将简单聊天路由到廉价模型，复杂编码路由到强力模型：

[defaults.routing]
# 频道对话使用高性能模型
channel = "anthropic/claude-sonnet-4"
# 后台_worker_使用低成本模型
worker = "anthropic/claude-haiku-4.5"

[defaults.routing.task_overrides]
# 编码任务强制升级模型
coding = "anthropic/claude-sonnet-4"

[defaults.routing.prompt_routing]
enabled = true
# 启用基于提示词复杂度的自动降级
process_types = ["channel", "branch"]

保存配置后重启 Spacebot 即可生效。