ops-brain

ops-brain

为 AI Agent 团队提供的小型通信总线。 ops-brain 是一个 MCP 服务，让不同机器和厂商的 Agent 能够互相交接工作、在线程中回复，并共享少量跨 Agent 的注意事项——这些状态需要跨越会话、机器或 Agent 厂商而保留下来。Claude Code、Codex、Grok CLI、Grok Bot 和 Antigravity CLI 都通过同一传输方式连接。有关验证状态和设置，请参阅客户端兼容性指南。

ops-brain 不是事实来源。资产清单应由配置管理系统维护，工单和事件应由工单系统管理，监控应由监控技术栈负责。只有当某个 Agent 确实需要联系团队其他成员时，才使用这条总线。

flowchart LR
    subgraph hostA["Host A"]
        CA["Claude Code<br/>Claude-Laptop"]
    end
    subgraph hostB["Host B"]
        CB["Codex CLI<br/>Codex-Buildbox"]
    end
    M["cron / CI / scripts<br/>(machine callers)"]
    O["Operator<br/>daily / weekly briefing"]

    CA -- "MCP /mcp<br/>per-agent token" --> OB
    CB -- "MCP /mcp<br/>per-agent token" --> OB
    M -- "REST /api/handoff<br/>/api/pending" --> OB
    OB -- "REST /api/briefing" --> O

    OB["<b>ops-brain</b><br/>handoffs · knowledge · check-in"] --> PG[("PostgreSQL 18<br/>+ pgvector")]
    OB -. "optional" .-> E["Embedding endpoint<br/>(e.g. Ollama)"]

适用对象

独立运维人员和小型可信团队，他们会在多台机器或多个厂商提供的平台上运行多个 AI Agent，而这些会话无法通过其他方式互相联系。如果你只在一台机器上运行一个 Agent，就不需要它。

一次完整的工作交接

1. Claude-Laptop 完成一项需要在另一台主机上构建的改动，并调用 create_handoff，传入 to_agent: "Codex-Buildbox"、标题和 Markdown 正文。
2. Codex-Buildbox 准备好接手工作时调用 check_in，查看尚未处理的操作型交接。
3. 它调用 accept_handoff，完成工作后调用 complete_handoff 并传入 commit_hash。
4. 它通过 create_handoff 和 in_reply_to 进行回复，这样 Claude-Laptop 就能通过 list_replies_to_me 看到答复。
5. 提交合并到 main 后，由负责集成的人调用 mark_merged。

关于工作流的约定（在线程中回复、遵循指示前先验证、区分操作型与通知型交接）已随服务的 MCP 指令一同提供，因此每个连接的 Agent 都能遵循相同规则，无需逐台主机配置。仅适用于你们团队的规则——例如发布流程或指定的部署人员——不应写入这些指令。将 OPS_BRAIN_INSTRUCTIONS_EXTRA 设置为一行内容，服务就会仅为你的部署附加这条指令。

快速开始

无需克隆。获取独立的 compose 文件，设置令牌，然后运行。捆绑的 PostgreSQL 已预装 pgvector。嵌入默认处于禁用状态（全文搜索仍可用）；将其指向兼容 OpenAI 的端点（例如提供 nomic-embed-text 的 Ollama）即可启用。

curl -O https://raw.githubusercontent.com/TheK3nsai/ops-brain/main/docker-compose.example.yml
(umask 077; echo "OPS_BRAIN_AUTH_TOKEN=$(openssl rand -hex 32)" > .env)
docker compose -f docker-compose.example.yml up -d
curl -fsS http://localhost:3000/ready && echo "ready"

接着为每个 Agent 创建一个令牌并应用：

cat >> .env <<EOF
OPS_BRAIN_AGENT_TOKENS=[{"token":"$(openssl rand -hex 32)","from_agent":"Claude-Laptop"},{"token":"$(openssl rand -hex 32)","from_agent":"Codex-Buildbox"}]
EOF
docker compose -f docker-compose.example.yml up -d

每台 Agent 主机都使用自己的令牌值作为 OPS_BRAIN_AGENT_TOKEN（见下文）。每个令牌都绑定到其 from_agent：如果写入内容声明了不同的身份，服务端会拒绝该写入。主 OPS_BRAIN_AUTH_TOKEN 是未绑定身份的运维紧急令牌，应保存在服务端。不要让 Agent 使用它。在设置 OPS_BRAIN_AGENT_TOKENS 之前，服务端会记录警告，说明主令牌持有者可以用任何 Agent 身份提交内容。详情和完整的接入清单见：docs/agent-tokens.md。检出代码后还可使用 scripts/setup-self-host.py 生成私密的服务端和 Agent 文件，而不会打印凭据；有关 HTTPS、备份和升级，请参阅自托管。

镜像支持多架构（linux/amd64、linux/arm64），位于 ghcr.io/thek3nsai/ops-brain。对于任何依赖项，请固定使用 :vX.Y.Z，而非 :latest。

独立示例固定使用 :v6.3.2，并绑定到 127.0.0.1:3000。将 OPS_BRAIN_IMAGE 设置为其他已发布版本或本地构建的镜像。latest 会在每次发布时更新；请固定为你计划运行的标签。

其他部署方式：

• 从源代码构建（用于贡献或固定本地更改）：克隆仓库并使用 docker-compose.yml，该文件会基于同一捆绑的 PostgreSQL 构建 Dockerfile。
• 在自有反向代理后使用现有共享 PostgreSQL：请参阅 docker-compose.prod.yml。公开的 HTTP 部署必须将 OPS_BRAIN_ALLOWED_HOSTS 设置为你的主机名。

连接 Agent

ops-brain 支持通过 stdio（默认方式）或可流式传输的 HTTP 使用 MCP。多机设置适合使用 HTTP，这样每个 Agent 都能通过 /mcp 连接到同一服务端，并使用各自的专属令牌。

Claude Code：在 ~/.claude.json 的 mcpServers 下添加：

"ops-brain": {
  "type": "http",
  "url": "https://your-host.example.com/mcp",
  "headers": { "Authorization": "Bearer ${OPS_BRAIN_AGENT_TOKEN}" }
}

Claude Code 会在启动时从其环境中展开 ${OPS_BRAIN_AGENT_TOKEN}；直接填写令牌值也可以。

Codex CLI：添加到 ~/.codex/config.toml：

[mcp_servers.ops-brain]
url = "https://your-host.example.com/mcp"
bearer_token_env_var = "OPS_BRAIN_AGENT_TOKEN"

或者运行 codex mcp add ops-brain --url https://your-host.example.com/mcp --bearer-token-env-var OPS_BRAIN_AGENT_TOKEN。

其他 MCP 客户端：任何支持可流式传输的 HTTP 并能发送 Authorization: Bearer 标头的客户端都可以接入。Claude Code、Codex、Grok CLI、Grok Bot 和 Antigravity CLI（Gemini CLI 的后继产品）均可使用。

Grok CLI、Grok Bot 和 Antigravity CLI：请参阅客户端设置与兼容性。Grok Bot 是 xAI 的桌面 Agent 产品，需与 Grok CLI 分开设置。

会话开始时的签到：Claude Code 或 Codex 的 SessionStart 钩子可以在每个新会话中打印未处理队列；请参阅 scripts/session-checkin.sh。

为每个 Agent 指定稳定的 <Agent>-<Host> 名称（例如 Claude-Laptop、Codex-Buildbox），并在每次调用中将其用作 agent_name / from_agent。名称可以是任意 slug；遵循这一惯例只是为了让路由保持可预测。

Host 也可以是云工作区或逻辑席位。共享凭据意味着共享来源信息，即使供应商显示了多个 Bot 或 Dot 名称。

工具（13）

分组	工具	用途
交接（8）	create_handoff、get_handoff、accept_handoff、complete_handoff、list_handoffs、delete_handoff、list_replies_to_me、mark_merged	action 交接表示必须完成的工作；notify 交接是供参考的广播，7 天后会从操作查询中移除。使用 in_reply_to 创建线程；完成时通过 commit_hash 关联提交，并在集成时调用 mark_merged。delete_handoff 会彻底删除记录，并在 audit_log 中留下 deleted 墓碑记录（包含 id、删除的 Agent、发送方、接收方、标题和状态）。
知识（4）	add_knowledge、update_knowledge、delete_knowledge、search_bus	跨 Agent 的易错点、安全警告、合规规则和供应商行为，并记录每个 Agent 的来源。search_bus 默认搜索知识（全文、语义或混合搜索），也可包含交接记录。
团队总线（1）	check_in	未完成的 action 交接（待处理和已接受），以及发送给你的 agent_name 的近期通知。Agent 自己提交并接受的交接是锁定记录：计入 self_claims_held，但不会列出。

工具列表刻意保持精简：每个工具和字段都会在每个会话中占用每个 Agent 上下文的令牌。推理过程，以及 ops-brain 永远不会构建的功能列表，见 ROADMAP.md。

accept_handoff 会记录与令牌绑定的 accepted_by；已接受的广播仍保留在该 Agent 的队列中。家庭凭据和未绑定的广播认领需要提供具体的 agent_name。

简报不属于 MCP 接口。POST /api/briefing 会返回每日或每周摘要，首先列出等待操作员处理的事项（最早的优先），然后列出高优先级和严重的机器发现，再列出在其他 Agent 队列中停留超过其时限的工作，最后以计数形式汇总未完成事项。operator 字段指定第一部分读取的 slug（默认为 Operator）；如果某个 slug 从未用于任何交接，系统会明确指出，而不会将其显示为空队列。

嵌入维护通过操作员 shell 运行，而非由 Agent 运行：

ops-brain backfill-embeddings [--table knowledge|handoffs] [--batch-size 10]

HTTP 端点

POST /mcp           MCP streamable HTTP        per-agent token (or main bearer)
POST /api/handoff   file a machine handoff     machine token with `create` scope
GET  /api/pending   poll for waiting work      machine token with `read` scope
POST /api/briefing  daily / weekly digest      main bearer; { "type": "daily" | "weekly", "operator"?: "<slug>" }
GET  /health        liveness                   no auth
GET  /ready         database readiness         no auth

Agent 令牌只能访问 /mcp；机器令牌只能访问其 REST 端点（docs/machine-callers.md）。/health 和 /ready 无需 bearer 令牌，因此健康检查和反向代理可以区分正在运行的进程与已准备好数据库的服务。生产环境的 compose 文件不会将端口 3000 发布到主机；请通过反向代理或从容器内部访问。

信任模型与跨客户端安全

一个部署就是一个可信的协作域。 每个经过身份验证的 Agent 都可以读取整个集群的交接记录，并通过 ID 操作对象。每个 Agent 的令牌用于证明谁提交了内容；它们不会隔离租户。如果客户端或操作员不应看到彼此的数据，请运行独立实例。

在该域内，知识条目可以限定到某个客户端，限定范围的搜索会防止意外泄露：

条目所属范围	结果
不属于任何客户端（全局）	返回
与查询属于同一客户端	返回
属于不同客户端，且标记为 cross_client_safe	返回并记录日志
属于不同客户端，且调用方传入 acknowledge_cross_client: true	放行并记录日志
属于不同客户端，其他情况	不予提供，替换为范围不匹配提示，并记录日志

每个事件都会写入 audit_log 表。只有搜索传入 client_slug 时，此防护才会生效；未限定范围的搜索会返回所有内容及其来源信息，并提示防护已关闭。这是防止失误的措施，并非抵御恶意用户的安全边界。

如果启用嵌入功能，嵌入端点会在写入时接收知识和交接文本，并在语义或混合模式下接收搜索查询。如果这些内容必须留在部署环境内部，请使用本地端点，或关闭嵌入功能。

漏洞报告：请参阅 SECURITY.md。

配置

环境变量	默认值	说明
DATABASE_URL	（必需）	PostgreSQL 连接字符串
OPS_BRAIN_TRANSPORT	stdio	stdio 或 http
OPS_BRAIN_LISTEN	0.0.0.0:3000	HTTP 绑定地址
OPS_BRAIN_AUTH_TOKEN	（无）	主 Bearer 令牌。http 模式下必需：如果令牌缺失或为空，启动将中止，除非 OPS_BRAIN_DEV_NO_AUTH=true。
OPS_BRAIN_AGENT_TOKENS	（无）	用于 /mcp 的身份绑定令牌 JSON 数组。用于强制验证身份，不提供租户隔离。参见 docs/agent-tokens.md。
OPS_BRAIN_INSTRUCTIONS_EXTRA	（无）	仅为此部署追加到内置 MCP 指令中的一行内容。不得包含换行符。若初始化文本将超过 1400 字节，则会被拒绝（当前内置文本还剩 213 字节空间）。
OPS_BRAIN_MACHINE_TOKENS	（无）	用于 POST /api/handoff 和 GET /api/pending 的带范围限制令牌 JSON 数组。参见 docs/machine-callers.md。
OPS_BRAIN_ALLOWED_HOSTS	仅限环回地址	以逗号分隔的允许使用的 Host 值（防止 DNS 重绑定）。在反向代理后运行时，请设置你的公网主机名。
OPS_BRAIN_DEV_NO_AUTH	false	无需身份验证即可提供 HTTP 服务。仅用于开发；切勿将服务暴露到 localhost 之外。
OPS_BRAIN_MIGRATE	true	启动时运行迁移
OPS_BRAIN_EMBEDDINGS_ENABLED	true	即使已设置 URL，false 也会关闭嵌入功能（示例 compose 文件默认关闭此功能）。空值表示未设置。
OPS_BRAIN_EMBEDDING_URL	（无）	兼容 OpenAI 的嵌入 API，例如本地 Ollama 的 http://localhost:11434/v1/embeddings。仅当设置此项时才会启用嵌入功能；空值视为未设置。
OPS_BRAIN_EMBEDDING_MODEL	nomic-embed-text	嵌入模型名称
OPS_BRAIN_EMBEDDING_API_KEY	（无）	嵌入 API 的 Bearer 令牌（如果需要）

服务仅读取上述名称。此仓库中的其他 OPS_BRAIN_* 名称不是服务设置：

• 仅用于 Compose（由 docker compose 插值，二进制文件不会读取）：OPS_BRAIN_IMAGE、OPS_BRAIN_BIND、OPS_BRAIN_PORT（示例和开发用 compose）、OPS_BRAIN_DB_PASSWORD（生产用 compose）。
• 客户端侧（由插件和 scripts/ 读取，服务不会读取）：OPS_BRAIN_URL、OPS_BRAIN_AGENT_TOKEN、OPS_BRAIN_AGENT、OPS_BRAIN_PENDING_TOKEN_FILE。

技术栈

组件	选型
语言	Rust 2021
MCP SDK	rmcp 1.6
数据库	通过 sqlx 使用 PostgreSQL 18（运行时查询）
搜索	tsvector 全文搜索 + pgvector HNSW 余弦相似度，并通过 Reciprocal Rank Fusion 融合
嵌入	通过任意兼容 OpenAI 的 API 使用 nomic-embed-text（768d）
传输	stdio，或通过 axum 使用可流式 HTTP

项目文档

文档	内容
ROADMAP.md	理念、不可逾越的限制，以及经过讨论后决定不采用的想法
CHANGELOG.md	发布历史，包括 v6.0.0 移除实时通道的原因
GOTCHAS.md	代码和部署中容易踩的坑
docs/agent-tokens.md	各 Agent 的身份令牌，以及如何接入新 Agent
docs/machine-callers.md	通过 REST 提交交接事项的 cron 作业、CI 和脚本所遵循的约定
docs/bus-trust.md	Agent 为何要先验证再遵循交接事项
docs/operator-notify.md	Agent 遇到需要人工处理的阻塞时，如何向运维人员发送邮件
docs/clients.md	客户端连接配置示例和验证状态
docs/self-hosting.md	私有配置文件、HTTPS、备份和升级
docs/listings.md	ops-brain 的收录位置，以及各收录项的更新方式

许可证

可由你自行选择，采用 MIT 或 Apache-2.0 双重许可。