Open Swarm

Operating Swarm

Operating Swarm 可运行 Python Agent 工作流，并通过共享服务连接模型 API、本地 Agent CLI 和外部运行环境。可使用其终端命令、OpenAI 风格的 HTTP 端点或 React WebUI。

实验性 Alpha 版。 源码领先于已发布的软件包。已通过 CLI、API 和 WebUI 测试模型与工具工作流。这并不能证明所有内置配方或远程集成都可用。请参阅带日期的验证报告。

Operating Swarm 最初名为 Open Swarm，是 OpenAI 实验性 Swarm 的衍生项目。目前，它使用 OpenAI Agents SDK 来处理 Agent、工具和交接。这是一个独立项目，并非 OpenAI 产品。请参阅 LICENSE 和 NOTICE。

架构

Python 导入模块名为 swarm。Django 提供配置、身份验证和持久化对话。蓝图类实现工作流：ApiKindBase 运行 Agents SDK 图，CLI 适配器启动宿主进程，远程适配器调用外部运行环境的协议。团队名册组合这些功能。API 和 WebUI 共用此后端。

蓝图通过 CLI 和 API 运行；它们不会提供独立网页。WebUI 是共用的产品界面。

术语仍在统一中：代码使用 api、cli、remote 和 team 基类，而较早的文档将程序化工作流称为“蓝图”。模型配置选择推理端点。封装 CLI 或远程运行环境不会将 SDK 注入该外部进程。上下文传递和恢复取决于适配器；尚未证实不同运行环境之间能够普遍保持连续性。

安装当前源码

使用 Python 3.12 或 3.13、uv；如果要使用 WebUI，还需 Node.js 24+。Linux/WSL 是运行完整后端测试套件的参考环境。下方的本地工作流也已在 Windows 上测试。Bash 语法：

git clone https://github.com/matthewhand/operating-swarm.git
cd operating-swarm
uv sync --locked --extra tui
export SWARM_CONFIG_DIR="$PWD/.runtime/config"
export SWARM_USER_DATA_DIR="$PWD/.runtime/data"
export SWARM_CONFIG_PATH="$PWD/.runtime/swarm_config.json"
mkdir -p "$SWARM_CONFIG_DIR"
cp docs/examples/inventory-config.json "$SWARM_CONFIG_PATH"
export OPENAI_BASE_URL="https://api.openai.com/v1"
export OPENAI_MODEL="YOUR_MODEL_ID"
read -rsp 'Model API key: ' OPENAI_API_KEY; echo
export OPENAI_API_KEY
export API_AUTH_TOKEN="$(uv run python -c 'import secrets; print(secrets.token_urlsafe(32))')"
export DJANGO_DEBUG=true

请选择账户可访问的模型。如果 Ollama 服务已在运行，请使用 OPENAI_BASE_URL=http://127.0.0.1:11434/v1、已安装且支持工具的模型的准确名称，以及 OPENAI_API_KEY=ollama（本地占位值）。支持情况因模型而异。本次审查使用了现有的 OpenAI 兼容网关；发现 Ollama 模型并不代表已完成 Ollama 工作流测试。

克隆并同步后，在 PowerShell 中设置环境：

$env:SWARM_CONFIG_DIR = "$PWD/.runtime/config"
$env:SWARM_USER_DATA_DIR = "$PWD/.runtime/data"
$env:SWARM_CONFIG_PATH = "$PWD/.runtime/swarm_config.json"
New-Item -ItemType Directory -Force $env:SWARM_CONFIG_DIR | Out-Null
Copy-Item docs/examples/inventory-config.json $env:SWARM_CONFIG_PATH
$env:OPENAI_BASE_URL = 'https://api.openai.com/v1'
$env:OPENAI_MODEL = 'YOUR_MODEL_ID'
$key = Read-Host 'Model API key' -AsSecureString
$env:OPENAI_API_KEY = [System.Net.NetworkCredential]::new('', $key).Password
$env:API_AUTH_TOKEN = uv run python -c 'import secrets; print(secrets.token_urlsafe(32))'
$env:DJANGO_DEBUG = 'true'

所有状态都保存在 Git 忽略的 .runtime/ 中。这些是本地主机开发设置。共享部署需要生产环境的 Django 设置、密钥、允许的主机、身份验证和数据库方案：请参阅部署、身份验证、数据库。原生开发默认使用 SQLite；Compose 会配置 Postgres。本次审查未测试 Docker、Pinokio 和桌面安装程序。

实用的模型与工具工作流

内置的 inventory_demo 根据虚构库存计算补货计划。其 stock_report 工具在本地计算数量和成本；模型调用该工具并解释结果。它不会下订单，也不需要 shell 访问权限。

uv run os-cli launch inventory_demo --message "What should we reorder, and what will it cost?"

预期结果：9 本笔记本（36 件）和 6 个文件夹（18 件），共 54 件。仅有看似合理的回答并不能证明工具确实执行过。工具完成后，WebUI 会显示 stock_report。蓝图源码。

os-cli 和 os 是同一条命令。不带参数运行会打开可选的 TUI（--extra tui）。os-api 会启动服务器。没有 os-webui 可执行文件：服务器会提供构建好的 React 应用。

API 和 WebUI

在同一个已配置的终端中：

uv run python -m django migrate --settings=swarm.settings --noinput
npm --prefix webui/frontend ci
npm --prefix webui/frontend run build
uv run os-api --host 127.0.0.1 --port 8000

打开 localhost:8000，选择 inventory_demo，然后提出补货问题。本地开发预览会建立浏览器会话；websocket 身份验证使用会话 cookie，而不是 HTTP bearer 标头。共享部署请参阅 AUTH.md。

在另一个具有相同 API_AUTH_TOKEN 的终端中：

curl -fsS http://127.0.0.1:8000/v1/models \
  -H "Authorization: Bearer $API_AUTH_TOKEN"
curl -fsS http://127.0.0.1:8000/v1/chat/completions \
  -H "Authorization: Bearer $API_AUTH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"model":"inventory_demo","messages":[{"role":"user","content":"What should we reorder, and what will it cost?"}]}'

model 选择的是 Swarm 配方／席位，而不是上游模型。Chat completions 支持使用 stream:true 进行 SSE 流式传输。/v1/responses 接受 model 和 input。这些是兼容接口，并不完全等同于 OpenAI API。未知模型会返回 404；格式错误的消息会返回 400。配置了令牌后，缺少或错误的 HTTP 凭据会被拒绝。使用 Ctrl+C 停止；重置演示时请保留运维数据。

集成限制

适配器需要单独安装、可访问且经过身份验证的服务。os-cli remotes 会列出已配置的实例。远程协议。健康检查、列表获取和推理完成属于不同的验证级别。

集成	审查结果
AnythingLLM、OpenMousBot、TrueForge	已配置的实例能够响应健康检查和列表请求。发送结果见报告。
Hermes	在 10 月 21 日的可选实时测试套件中，主实例通过了健康检查、发现和真实模型交互；次要实例未通过。此前主实例的一次交互超时。
Rakazo、Herdr、嵌套 Swarm	已配置的目标不可用；不声称其推理功能可用。
Open WebUI	服务正常运行；列表请求因凭据遭拒（401）。另一个实例已停止。
Flowise、n8n、Tencent Octop、OpenMuse	未对任何已配置的实例进行测试。测试／目录条目不能证明其可实时使用。
Letta	专用远程服务已移除。旧的本地配置中仍包含它；此处未验证 API 配置文件兼容性。

MCP 客户端／服务端模式、记忆后端、沙箱浏览器、桌面／托盘界面、TUI 交互、所有 CLI 提供方、跨类型上下文传输和安装程序均未全部经过测试。历史 GIF 和设计图表并非实时证据。请参阅 FEATURE_STATUS.md 和验证报告。

软件包和发布状态

来源	含义
此代码树：os-core 0.6.0a1	尚未发布的 Alpha 准备版本。克隆此代码库以使用本文演示的工作流／WebUI。
GitHub Release v0.5.4（2026 年 6 月 19 日）	历史标题：“django_chat resolves its LLM profile”；早于当前 UI 和架构。
PyPI open-swarm==0.5.4	历史软件包，Python >=3.10；并非当前的 os-core。
PyPI os-core	截至 2026 年 10 月 20 日检查时尚不可用。
packaging/open-swarm-alias	尚未发布的迁移别名；仅在其 os-core 依赖可用后发布。

Main 不再复用 0.5.4。发布工作流会识别此仓库名称，并检查标签与版本是否一致。上传到索引仍需发布者凭据或可信发布者配置，并且需要有意执行发布。Python wheel 不包含 React 构建产物：使用源码检出版本以运行 WebUI。合并 PR 不会发布到 PyPI。发布相关工作列于报告中。

开发

uv sync --locked --extra dev --extra test
uv run pytest tests/core/ tests/views/ -x -q
npm --prefix webui/frontend test
npm --prefix webui/frontend run type-check
npm --prefix webui/frontend run build

一些后端测试使用 Unix 可执行脚本；要运行完整检查，请使用 Linux/WSL。Windows 回归测试会单独覆盖配置隔离、进程锁、安全故障处理和 CLI 退出状态。AGENTS.md 和 CONTRIBUTING.md 定义了贡献要求。

可选的真实服务检查位于 tests/live。在开发主机上设置私有的 SWARM_LIVE_<INSTANCE>_URL 和凭据变量，然后运行 uv run pytest tests/live -m live_remote --no-cov -q --tb=no --show-capture=no。未配置的实例会跳过；已配置实例的检查失败则会导致测试失败。摘要会区分健康状态／发现与已完成的模型回答，并统计正常工作的集成。OMB、Rakazo 和 AnythingLLM 需要专用的测试目标。

可选的实体设备 UI 检查使用明确指定的设备浏览器 URL 变量，未配置时会跳过。已在真实手机上测试 Android Chrome；由于可用的 ADB 连接仅能访问其 Android 运行时，原生 ChromeOS 渲染仍未经验证。

更多参考资料：最简工作流配置、完整示例配置、配置指南、开发者指南和交接图示例。

历史分镜和 GIF 仍保留在 ANNOUNCE 和演示指南中。它们是历史媒体，并非当前集成验证。