OverClaw Bridge (nanobot-overstory)

OverClaw 堆栈中的关键集成层。通过 OverClaw HTTP 网关（端口 18800），将 nanobot（基于 Ollama Mistral 的轻量级 AI 后端）连接到 overstory（Claude Code 代理集群系统）。nanobot 负责任务接收与编排；overstory 负责所有子代理的创建、协调、工作树管理和执行。

架构

┌─────────────────────────────────────────────────────────────┐
│ nanobot │
│ (Ollama Mistral 编排器 — 任务接收与路由) │
└──────────────────────┬──────────────────────────────────────┘
│ task_router.py
│ (分类 → 能力 → overstory 格式)
▼
┌─────────────────────────────────────────────────────────────┐
│ nanobot-overstory 桥接层 │
│ │
│ ┌──────────────┐ ┌────────────────┐ ┌────────────────┐ │
│ │ taskrouter │ │ sessionbridge │ │ memory_sync │ │
│ │ .py │ │ .py │ │ .py │ │
│ │ │ │ │ │ │ │
│ │ routetask() │ │ createmapping │ │ synctoover() │ │
│ │ translate() │ │ getagent() │ │ syncfrom() │ │
│ │ capability() │ │ cleanup() │ │ prune() │ │
│ └──────┬───────┘ └───────┬────────┘ └───────┬────────┘ │
│ │ │ │ │
│ └──────────┬───────┴────────────────────┘ │
│ │ │
│ overstory_client.py │
│ (overstory CLI 的子进程封装) │
└────────────────────┬────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ overstory │
│ (Claude Code 代理集群 — 子代理生命周期与执行) │
│ │
│ 协调器 → 监督器 → 代理 (工作树) │
│ 邮件系统, 合并, 检查, 状态 │
└─────────────────────────────────────────────────────────────┘

组件

overstory_client.py

overstory CLI 二进制文件的 Python 封装。提供清晰的 OverstoryClient 类，包含所有 overstory 操作的方法：sling、status、inspect、mailsend、mailread、coordinatorstart、supervisorstart、merge 和 list_agents。

task_router.py

将 nanobot 任务描述转换为 overstory 兼容格式。将任务意图映射到 overstory 能力：

任务模式	能力
研究、趋势、分析	researcher
社交媒体、发帖、推文

social-media-manager |
| 博客、文章、内容 | blogger |
| 代码、构建、修复、实现 | builder |
| 探索、查找、搜索 | scout |
| 日志、记忆、笔记 | scribe |
| 审查、合并 | reviewer |

session_bridge.py

维护 nanobot 会话 ID 与 overstory 代理名称之间的持久映射。使用位于 ~/.nanobot/session_bridge.db 的 SQLite 数据库，实现线程安全的持久化存储。支持过期映射清理。

memory_sync.py

双向记忆同步。在任务执行前将 nanobot 的 MEMORY.md 上下文推送到 overstory 代理，并在任务完成后将代理洞察拉回 nanobot 的记忆中。

使用方法

从 Python 调用

python
from overstory_client import OverstoryClient
from task_router import TaskRouter
from session_bridge import SessionBridge
from memory_sync import MemorySync

client = OverstoryClient()
router = TaskRouter(client)
bridge = SessionBridge()
memory = MemorySync()

将任务从 nanobot 路由到 overstory

result = router.route_task(研究本周热门的 AI 论文)

result: {capability: researcher, agent_name: researcher-abc123, ...}

检查代理状态

status = client.status(researcher-abc123)

发送代理间邮件

client.mail_send(coordinator, researcher-abc123, 需要优先级更新)

同步记忆（执行前后）

memory.synctooverstory() memory.syncfromoverstory({insight: 找到了 3 篇关于推理的关键论文})

从 CLI 调用

bash

路由任务

python3 scripts/task_router.py route --task 为仪表板构建 REST API --json

检查 overstory 状态

python3 scripts/overstory_client.py status --json python3 scripts/overstory_client.py status --agent researcher-abc123 --json

生成代理

python3 scripts/overstory_client.py sling \ --capability builder \ --name api-builder \ --description 为仪表板构建 REST API --json

同步记忆

python3 scripts/memorysync.py sync --direction tooverstory --json python3 scripts/memorysync.py sync --direction fromoverstory --json

列出会话映射

python3 scripts/session_bridge.py list --json

清理过期映射

python3 scripts/session_bridge.py cleanup --max-age 24 --json

要求

• - Python 3.9+
• 已安装 overstory CLI 并在 PATH 中（或设置 OVERSTORY_BIN 环境变量）
• OverClaw 网关运行在端口 18800（scripts/start-overclaw.sh）
• 带有 Mistral 模型的 Ollama
• SQLite3（随 Python 捆绑）

环境变量

变量	默认值	描述
NANOBOTGATEWAYURL	http://localhost:18800	OverClaw 网关 URL
OVERCLAW_PORT

18800 | OverClaw 网关端口 | | OVERSTORY_BIN | overstory | overstory 二进制文件路径 | | NANOBOT_WORKSPACE | /Users/ghost/.openclaw/workspace | 工作区根目录 | | NANOBOTSKILLSDIR | /skills | 技能目录 | | NANOBOTMEMORYPATH | /MEMORY.md | MEMORY.md 文件路径 | | SESSIONBRIDGEDB | ~/.nanobot/session_bridge.db | 会话映射数据库 | | BRIDGELOGLEVEL | INFO | 日志详细程度 |

现有 nanobot/OpenClaw 用户请注意： OverClaw 运行在端口 18800，与旧版 OpenClaw 网关（18789）和 nanobot 默认端口（18790）分离，不会产生冲突。

集成流程

1. 1. nanobot 接收任务（通过 TUI/API 来自用户）
2. taskrouter 对任务进行分类并确定 overstory 能力
3. sessionbridge 创建 nanobot 会话与即将生成的 overstory 代理之间的映射
4. memorysync 将相关上下文推送到 overstory
5. overstoryclient 通过 overstory sling 生成代理
6. overstory 管理代理生命周期（工作树、执行、邮件）
7. 完成后，overstoryclient 通过 inspect/status 检索结果
8. memorysync 将洞察拉回 nanobot 记忆
9. session_bridge 将映射标记为已完成
10. nanobot 将结果交付给用户