octos-org/octos
GitHub: octos-org/octos
一个 Rust 原生、API 优先的开源 AI 智能体操作系统，以单一二进制提供多租户隔离、多 LLM 管道编排和全通道网关能力。
Stars: 727 | Forks: 61
# Octos 🐙
**开放式认知任务协调系统 (Open Cognitive Tasks Orchestration System)** — 一个 Rust 原生的、API 优先的 Agentic OS。
31MB 静态二进制文件。约 140 个 REST 端点。15 个 LLM 提供商。14 个消息通道。多租户。零外部运行时服务。
## 什么是 Octos？
Octos 是一个开源 AI 智能体平台，允许你在单台机器或云-设备对上运行自己的 AI 系统。你只需部署一个 Rust 二进制文件，连接你的 LLM 提供商和通道，Octos 就会通过 Web 仪表板和 REST API 处理路由、会话、工具、内存和多用户隔离。
你可以把它看作是 **AI 智能体的后端操作系统**。无需为每个用例构建新的聊天机器人技术栈，你可以配置具有自己提示词、模型、工具和通道的 Octos 配置文件，然后从一个控制平面管理它们。
对新用户来说，重要的是 Octos 可以通过三种不同的方式使用：
1. **Octos Cloud 注册** — 最简单的途径；创建一个账户，选择一个节点名称，并在你的设备上运行生成的设置命令。
2. **自托管本地模式** — 仅在你自己的机器或本地网络上运行 Octos。
3. **自托管云 + 租户对模式** — 运行你自己的公共 VPS 以及你自己的租户设备，以实现可从互联网访问的远程使用。
## 为什么选择 Octos
大多数智能体系统都是单租户聊天助手——一次只有一个用户、一个模型、一段对话。Octos 与众不同：
- **API 优先的 Agentic OS**：约 140 个 REST 端点（chat、sessions、admin、profiles、skills、swarm、pipeline、metrics、webhooks、SSE）。任何前端——Web、移动端、CLI、CI/CD——都可以在其之上构建。
- **设计上支持多租户**：一个 31MB 的二进制文件可以在 16GB 的机器上服务 200 多个配置文件。每个配置文件都是一个独立的 OS 进程，具有隔离的内存、会话和数据。支持家庭计划子账户。
- **多 LLM DOT 管道**：将工作流定义为 DOT 图。按节点选择模型。动态并行扇出在运行时生成 N 个并发工作者，并具有限界并发性以保证集群稳定性。
- **Swarm 调度器**：将合约扇出到 N 个子智能体，聚合产物，通过验证器进行门控，汇总成本——内置于 `/api/swarm/dispatch`。
- **3 层提供商故障转移**：RetryProvider → ProviderChain → AdaptiveRouter。Hedge racing（竞速请求）、通道评分、熔断器。
- **LRU 工具延迟加载**：约 15 个活动工具用于快速的 LLM 推理，约 50 个按需调用。空闲工具会自动驱逐。`spawn_only` 工具会自动重定向到后台执行。
- **每个会话 5 种队列模式**：Followup、Collect、Steer、Interrupt、Speculative——用户可以通过 `/queue` 控制智能体并发。
- **任何通道中的会话控制**：`/new`、`/s `、`/sessions`、`/back`——可在 Telegram、Discord、Slack、WhatsApp、Matrix、飞书中使用。
- **粘性 thread_id + committed_seq**：每个 SSE 事件都绑定到一个线程；通过提交的序列号进行确定性回放 (M8.10)。
- **3 层内存**：长期（实体库，自动注入）、情景（redb 中的任务结果）、会话（JSONL + LLM 压缩，三层）。
- **原生办公套件**：通过纯 Rust 生成 PPTX/DOCX/XLSX (zip + quick-xml)。
- **沙箱隔离**：bwrap + sandbox-exec + Docker + Windows AppContainer。工作区范围禁用 `deny(unsafe_code)`。67 项提示注入测试。
## 选择设置路径
这三种路径都是可行的。最简单的是 Octos Cloud 注册，但自托管模式也是同等支持的一等公民。
| 选项 | 涉及的机器 | 公共互联网访问 | 谁管理基础设施 | 最适合 |
| --- | --- | --- | --- | --- |
| **1. Octos Cloud 注册** | 你的设备 + Octos Cloud | 是 | Octos Cloud + 你 | 最快途径 |
| **2. 自托管纯本地模式** | 一台机器 | 否 | 你 | 本地/私人使用 |
| **3. 自托管云 + 租户对模式** | 你的 VPS + 你的设备 | 是 | 你 | 带有远程访问的完全自托管 |
视觉概览：
### 选项 1：注册 Octos Cloud
这是最简单的入门方式。
1. 前往 Octos Cloud 注册页面。
2. 使用你的邮箱注册。
3. 选择一个自定义节点名称。
4. 在你的设备上运行生成的设置命令。
该设置命令是针对你的机器量身定制的，并包含了将你的设备连接到 Octos 云中继所需的值。设置完成后，你的 Octos 实例就可以在你的节点名下通过公共互联网访问了。
当你在门户中点击 `Send Code` 时，如果邮件没有立即到达，请检查你的垃圾邮件文件夹。将 Octos 的发送域名/地址添加到你的地址簿也是一个好主意，这样未来的登录和设置邮件就能可靠地送达。
注册后，门户将显示你的节点详细信息、公共 URL 以及要在你的设备上运行的设置命令：
如果你想要以下几点，此路径是最佳选择：
- 最短的达到首个可用系统的时间
- 无需运行自己的 VPS 即可获得公共访问权限
- 托管的注册和隧道流程
### 选项 2：自托管纯本地模式
如果你希望 Octos 运行在自己的机器上且不对外暴露，请选择此项。你的仪表板只能在本机或你的本地网络上访问。
```
# macOS / Linux
curl -fsSL https://github.com/octos-org/octos/releases/latest/download/install.sh | bash
```
```
# Windows (PowerShell)
irm https://github.com/octos-org/octos/releases/latest/download/install.ps1 | iex
```
这会安装二进制文件，将 `octos serve` 设置为服务，并在 `http://localhost:8080/admin/` 启动本地仪表板。
支持的平台：**macOS ARM64**、**Linux x86_64**、**Linux ARM64** 和 **Windows x64**。
如果你想要以下几点，请选择此路径：
- 最简单的自托管设置
- 仅限一台机器
- 仅限本地网络访问
- 以后可以选择升级到租户模式
### 选项 3：自托管云 + 租户对模式
如果你想要完全自托管但仍希望自己的设备能从公共互联网的任何地方访问，请选择此项。
此模式使用两台机器：
- 一台运行公共中继和 HTTPS 入口的 **云 VPS**
- 一台运行你自己的 Octos 实例的 **租户设备**
租户设备使用 `frpc` 向外连接到 VPS。VPS 运行公共组件，包括 TLS 和路由。这为你提供了类似 ngrok 风格的公共访问，但是通过你自己的基础设施实现的。
对于生产环境的使用，VPS 还需要通配符 HTTPS。当前的设置使用 Caddy 加上 Cloudflare DNS 挑战，或其他受支持的 DNS 提供商，来为主域名和租户子域名颁发和管理证书。
此选项的要求：
1. **你自己的托管域名**
示例：`octos.example.com`
2. **DNS 提供商 / 权威 DNS API**
它的具体作用是作为 Caddy 内部 ACME 客户端使用的 ACME `DNS-01` 验证器，为 `*.octos.example.com` 签发通配符证书，这也是租户子域名所使用的。如果你只使用 HTTP（带有 `--http-only`），或者你只需要主域名，则不需要此通配符 DNS 流程。
3. **SMTP 服务**
这是必需的，以便云主机可以在门户注册和登录期间向租户发送 OTP 电子邮件。
#### 1. 引导 VPS
在已将 DNS 指向它的 Linux VPS 上，你可以选择：
- 使用带有完整标志的脚本运行以实现几乎非交互式的流程，或者
- 不带任何标志运行 `bash scripts/cloud-host-deploy.sh`，让它以交互方式提示你
在运行之前，请导出你所选提供商所需的环境变量。例如：
```
export CF_API_TOKEN=xxx
export SMTP_PASSWORD=xxx
```
注意：
- 对于 Cloudflare，脚本期望 `CF_API_TOKEN` 作为 DNS 提供商令牌。
- 对于 SMTP，你可以预先导出 `SMTP_PASSWORD`，这样引导过程就不需要稍后再输入该密钥。
- 如果你启用了 SMTP，脚本还将提示或使用其余的 SMTP 设置，如主机、端口、用户名和发件人地址。
使用显式标志的示例：
```
git clone https://github.com/octos-org/octos.git
cd octos
bash scripts/cloud-host-deploy.sh \
--domain octos.example.com \
--https --dns-provider cloudflare
```
交互模式：
```
git clone https://github.com/octos-org/octos.git
cd octos
bash scripts/cloud-host-deploy.sh
```
这封装了三个主机端步骤：
- `scripts/install.sh` — 安装 `octos serve` 并设置 `mode = "cloud"`
- `scripts/frp/setup-frps.sh` — 安装并配置 `frps`
- `scripts/frp/setup-caddy.sh` — 配置公共路由和通配符 HTTPS
推荐的 DNS 划分：
- `octos.example.com` 和 `*.octos.example.com` 用于门户和租户仪表板
- `frps.octos.example.com` 设置为 `DNS only`，以便租户机器可以访问 FRP 控制端口
#### 2. 注册或创建租户
VPS 启动并运行后，云主机可以发布个性化的租户设置命令。该命令包含租户名称、每个租户的隧道令牌、SSH 端口、仪表板认证令牌、域名和中继地址。用户可以直接在门户中接收此命令，也可以通过电子邮件接收。
#### 3. 在你自己的设备上运行租户设置命令
使用在第 2 步中提供的确切命令。以下示例仅供参考，用于展示门户发布的命令类型：
```
curl -fsSL https://github.com/octos-org/octos/releases/latest/download/install.sh | bash -s -- \
--tunnel \
--tenant-name alice \
--frps-token \
--ssh-port 6001 \
--domain octos.example.com \
--frps-server frps.octos.example.com \
--auth-token
```
安装程序会写入租户隧道配置，安装 `frpc`，并在 `octos serve` 的同时启动公共隧道。
### 我可以从本地开始稍后再升级吗？
可以。
一旦你拥有可用的云主机，纯本地自托管的机器以后就可以升级到租户模式。保存的安装程序直接支持此操作：
```
# macOS / Linux
~/.octos/bin/install.sh --tunnel
~/.octos/bin/install.sh --doctor
```
```
# Windows
& "$HOME\.octos\bin\install.ps1" -Tunnel
& "$HOME\.octos\bin\install.ps1" -Doctor
```
此升级路径是有意设计的：从一台机器开始，然后仅在需要面向互联网的访问时才添加 VPS。
### 可选的自托管功能
```
# 自动安装运行时依赖 (git, node, python, ffmpeg, chromium)
curl ... | bash -s -- --install-deps
# 为自托管的本地部署设置带有 HTTPS 的 Caddy 反向代理
curl ... | bash -s -- --caddy-domain crew.example.com
```
### 卸载
在你要移除的机器上使用匹配的卸载标志：
```
# 租户或本地机器 (macOS / Linux)
~/.octos/bin/install.sh --uninstall
# 租户或本地机器 (Windows PowerShell)
& "$HOME\.octos\bin\install.ps1" -Uninstall
# 云端 VPS — 移除 octos serve、frps 和 Caddy
bash scripts/cloud-host-deploy.sh --uninstall
# 云端 VPS + 同时清除数据目录 (~/.octos)
bash scripts/cloud-host-deploy.sh --uninstall --purge
```
### 运行时部署模式
Octos 使用 `~/.octos/config.json` 中的 `"mode"` 来描述运行节点的行为方式：
- **`local`** — 独立机器
- **`tenant`** — 具有可选公共隧道的终端用户机器
- **`cloud`** — 具有租户管理和公共注册功能的 VPS 中继
`scripts/install.sh` 和 `scripts/install.ps1` 创建本地或租户配置。`scripts/cloud-host-deploy.sh` 创建或更新带有 `mode = "cloud"` 以及 `tunnel_domain` 和 `frps_server` 的云主机配置。
## 从源代码构建
针对未发布版本的开发：
```
# 构建并安装。以下功能是规范的默认设置
# （匹配 scripts/milestone-ci.sh）— `octos serve` 需要 `api`，
# 并且网关需要各个传输通道（telegram、discord 等）的相关通道功能。
# 仅执行基本的 `cargo install --path
# crates/octos-cli` 会得到一个缺失 `serve` 且
# 没有通道适配器的二进制文件。
cargo install --path crates/octos-cli \
--features "api,telegram,discord,whatsapp,feishu,twilio,wecom,wecom-bot"
# 初始化工作区
octos init
# 设置 API key（任何受支持的提供商 — 在安装期间自动检测）
export OPENAI_API_KEY=your-key-here # or ANTHROPIC_API_KEY, GEMINI_API_KEY, etc.
# 交互式聊天
octos chat
# 多通道网关
octos gateway
# Web 控制台 + REST API
octos serve
```
对于仓库本地的租户部署（从源代码构建，设置与 `install.sh` 相同的服务 + 隧道），请使用 `scripts/local
### 选项 1：注册 Octos Cloud
这是最简单的入门方式。
1. 前往 Octos Cloud 注册页面。
2. 使用你的邮箱注册。
3. 选择一个自定义节点名称。
4. 在你的设备上运行生成的设置命令。
该设置命令是针对你的机器量身定制的，并包含了将你的设备连接到 Octos 云中继所需的值。设置完成后，你的 Octos 实例就可以在你的节点名下通过公共互联网访问了。
当你在门户中点击 `Send Code` 时，如果邮件没有立即到达，请检查你的垃圾邮件文件夹。将 Octos 的发送域名/地址添加到你的地址簿也是一个好主意，这样未来的登录和设置邮件就能可靠地送达。
注册后，门户将显示你的节点详细信息、公共 URL 以及要在你的设备上运行的设置命令：
如果你想要以下几点，此路径是最佳选择：
- 最短的达到首个可用系统的时间
- 无需运行自己的 VPS 即可获得公共访问权限
- 托管的注册和隧道流程
### 选项 2：自托管纯本地模式
如果你希望 Octos 运行在自己的机器上且不对外暴露，请选择此项。你的仪表板只能在本机或你的本地网络上访问。
```
# macOS / Linux
curl -fsSL https://github.com/octos-org/octos/releases/latest/download/install.sh | bash
```
```
# Windows (PowerShell)
irm https://github.com/octos-org/octos/releases/latest/download/install.ps1 | iex
```
这会安装二进制文件，将 `octos serve` 设置为服务，并在 `http://localhost:8080/admin/` 启动本地仪表板。
支持的平台：**macOS ARM64**、**Linux x86_64**、**Linux ARM64** 和 **Windows x64**。
如果你想要以下几点，请选择此路径：
- 最简单的自托管设置
- 仅限一台机器
- 仅限本地网络访问
- 以后可以选择升级到租户模式
### 选项 3：自托管云 + 租户对模式
如果你想要完全自托管但仍希望自己的设备能从公共互联网的任何地方访问，请选择此项。
此模式使用两台机器：
- 一台运行公共中继和 HTTPS 入口的 **云 VPS**
- 一台运行你自己的 Octos 实例的 **租户设备**
租户设备使用 `frpc` 向外连接到 VPS。VPS 运行公共组件，包括 TLS 和路由。这为你提供了类似 ngrok 风格的公共访问，但是通过你自己的基础设施实现的。
对于生产环境的使用，VPS 还需要通配符 HTTPS。当前的设置使用 Caddy 加上 Cloudflare DNS 挑战，或其他受支持的 DNS 提供商，来为主域名和租户子域名颁发和管理证书。
此选项的要求：
1. **你自己的托管域名**
示例：`octos.example.com`
2. **DNS 提供商 / 权威 DNS API**
它的具体作用是作为 Caddy 内部 ACME 客户端使用的 ACME `DNS-01` 验证器，为 `*.octos.example.com` 签发通配符证书，这也是租户子域名所使用的。如果你只使用 HTTP（带有 `--http-only`），或者你只需要主域名，则不需要此通配符 DNS 流程。
3. **SMTP 服务**
这是必需的，以便云主机可以在门户注册和登录期间向租户发送 OTP 电子邮件。
#### 1. 引导 VPS
在已将 DNS 指向它的 Linux VPS 上，你可以选择：
- 使用带有完整标志的脚本运行以实现几乎非交互式的流程，或者
- 不带任何标志运行 `bash scripts/cloud-host-deploy.sh`，让它以交互方式提示你
在运行之前，请导出你所选提供商所需的环境变量。例如：
```
export CF_API_TOKEN=xxx
export SMTP_PASSWORD=xxx
```
注意：
- 对于 Cloudflare，脚本期望 `CF_API_TOKEN` 作为 DNS 提供商令牌。
- 对于 SMTP，你可以预先导出 `SMTP_PASSWORD`，这样引导过程就不需要稍后再输入该密钥。
- 如果你启用了 SMTP，脚本还将提示或使用其余的 SMTP 设置，如主机、端口、用户名和发件人地址。
使用显式标志的示例：
```
git clone https://github.com/octos-org/octos.git
cd octos
bash scripts/cloud-host-deploy.sh \
--domain octos.example.com \
--https --dns-provider cloudflare
```
交互模式：
```
git clone https://github.com/octos-org/octos.git
cd octos
bash scripts/cloud-host-deploy.sh
```
这封装了三个主机端步骤：
- `scripts/install.sh` — 安装 `octos serve` 并设置 `mode = "cloud"`
- `scripts/frp/setup-frps.sh` — 安装并配置 `frps`
- `scripts/frp/setup-caddy.sh` — 配置公共路由和通配符 HTTPS
推荐的 DNS 划分：
- `octos.example.com` 和 `*.octos.example.com` 用于门户和租户仪表板
- `frps.octos.example.com` 设置为 `DNS only`，以便租户机器可以访问 FRP 控制端口
#### 2. 注册或创建租户
VPS 启动并运行后，云主机可以发布个性化的租户设置命令。该命令包含租户名称、每个租户的隧道令牌、SSH 端口、仪表板认证令牌、域名和中继地址。用户可以直接在门户中接收此命令，也可以通过电子邮件接收。
#### 3. 在你自己的设备上运行租户设置命令
使用在第 2 步中提供的确切命令。以下示例仅供参考，用于展示门户发布的命令类型：
```
curl -fsSL https://github.com/octos-org/octos/releases/latest/download/install.sh | bash -s -- \
--tunnel \
--tenant-name alice \
--frps-token 标签：Agentic OS, AI Agent平台, AI基础设施, API-first, DLL 劫持, DOT工作流, LLM编排, REST API, Rust, SSE实时通信, Webhook, 云设备协同, 任务调度, 会话管理, 力导向图, 单机部署, 可视化界面, 后端即服务, 多模型路由, 多租户系统, 大语言模型, 家庭账户隔离, 开源, 开源认知系统, 微服务架构, 网络流量审计, 聊天机器人开发框架, 请求拦截, 通知系统