obsbotd

OBSBOT Tiny 系列摄像头的 Linux MCP 守护进程。一个守护进程独占摄像头；所有智能体——Claude Code、LibreChat、自定义框架，或任何能发送 JSON POST 请求的应用——均通过流式 HTTP 连接至该守护进程。

MCP clients (any framework, or bare curl)
        │  streamable-http  http://127.0.0.1:8626/mcp
        ▼
     obsbotd  ──►  V4L2/UVC ioctls (ctypes)   gimbal, zoom, focus, status
              ──►  vendor XU protocol         wake/sleep, AI tracking, exposure
              ──►  ffmpeg                     snapshots (validated), clips, preview

为何有此项目

上游的 obsbot-mcp npm 包完成了最困难的部分——逆向工程厂商协议和校准光学器件——但其架构（每个智能体会话运行一个 stdio MCP 服务器、一个预构建的原生辅助二进制文件、会话间的单所有者 IPC 选举）在多智能体 Linux 机器上造成了慢性运维问题：过时的所有者进程运行着数周前的代码、未经验证的截断帧，以及一个存在漏洞的封闭二进制文件。

obsbotd 保留了协议知识，并舍弃了该架构：

• 一个守护进程，多个客户端。 无需选举，无需每会话进程，没有过时的所有者。以 systemd 用户服务运行。

• 没有原生二进制文件。 V4L2/UVC 层约有 200 行 ctypes 代码；ioctl 编号根据结构体大小计算，布局错误会直接报错。

• 热插拔免费。 调用之间不持有任何设备句柄——每次工具调用都会重新发现 /dev/video*（毫秒级）。拔掉摄像头会产生正常的 {"ok": false, "camera_present": false} 结果；重新插入后的下一次调用即可正常工作。

• 帧经验证。 摄像头会间歇性地发送截断的 MJPEG 帧，在唤醒后尤为严重。每次快照都会流式复制原始帧，检查是否有完整的 SOI..EOI，最多重试 4 次，然后可选地进行缩小（默认 640 像素——快照像素就是 LLM 令牌）。

• 诚实的错误。 每个失败都是一个结构化的 {ok: false, error}，智能体可以据此采取行动——绝不是不透明的工具异常。拒绝消息会说明应执行的操作。

• 原子化的平移+俯仰。 两个轴通过一个 VIDIOC_S_EXT_CTRLS 操作完成——否则 uvcvideo 的每控制读写修改会取消一半的移动。

• 可测量的光学器件。 obsbot_aim_at_pixel / obsbot_zoom_to_fit 使用内参求解的视场角模型（67° 宽水平视场角，0.957 垂直校正，放大倍数 = 3·比例 − 2）和继承自上游校准工作的组合旋转瞄准，执行视觉伺服。

硬件支持

在 Linux（内核 uvcvideo）上的 OBSBOT Tiny 2 Lite 上开发和硬件验证。Tiny 2 共享相同的厂商协议，应该可以无改动运行；其他 OBSBOT 型号未经测试。每台主机支持单个摄像头。

已知内核限制：uvcvideo 会缓存 CT_PANTILT_ABSOLUTE，因此云台回读的是最后下达命令的姿势，而非实时姿态——相应工具已按此标注，预期工作流是通过视觉验证指向。

安装

需要 Python ≥ 3.12、ffmpeg（及用于预览窗口的 ffplay），以及对摄像头的 /dev/video* 节点（video 组）的读写权限。

git clone https://github.com/LumenPrima/obsbotd ~/obsbotd
cd ~/obsbotd
uv venv && uv pip install -e .        # or: python3 -m venv .venv && .venv/bin/pip install -e .
.venv/bin/python -m obsbotd.server    # listens on 127.0.0.1:8626

作为服务：

cp systemd/obsbotd.service ~/.config/systemd/user/
systemctl --user daemon-reload
systemctl --user enable --now obsbotd
loginctl enable-linger $USER          # optional: run without an active login

OBSBOTD_HOST / OBSBOTD_PORT 用于覆盖绑定地址。默认为仅本地回环，且无身份验证——除非你清楚知道任何能访问该端口的人都可以控制摄像头并拍照，否则不要将其绑定到可访问的接口。

连接智能体

MCP 原生配置（Claude Code、多数框架）：

{ "mcpServers": { "obsbot": { "type": "http", "url": "http://127.0.0.1:8626/mcp" } } }

没有 MCP 库？服务器会用纯 JSON 响应简单的 JSON-RPC POST 请求——一个简单的智能体可以用 curl 驱动它。docs/AGENT-GUIDE.md 提供了完整的集成指南、18 个工具的参考手册，以及交互规则（无需休眠、通过视觉验证移动、将拒绝视为指令）。

工具（18 个）

obsbot_snapshot · obsbot_status · obsbot_wake · obsbot_sleep · obsbot_gimbal_move · obsbot_gimbal_recenter · obsbot_gimbal_position · obsbot_zoom · obsbot_aim_at_pixel · obsbot_zoom_to_fit · obsbot_ai_track · obsbot_ai_track_speed · obsbot_focus · obsbot_exposure · obsbot_image_adjust · obsbot_image_mode · obsbot_record_clip · obsbot_preview

协议文档

docs/spec-*.md 是厂商有线协议的完整书面规范（60 字节 V3 帧、CRC-16/USB、操作码表、60 字节状态块、选择器映射）以及可测量的光学器件——从上游源代码中提取作为重新实现的参考，并且对任何驱动这些摄像头的人员本身也很有用。有线层已针对上游的精确帧字节进行黄金测试（tests/）。

测试

tests/ 无需硬件：.venv/bin/python -m pytest tests/ -q

致谢

厂商协议逆向工程、硬件异常目录和光学校准均来自 obsbot-mcp（MIT 许可，© 2026 Michael Jordan）。obsbotd 是围绕该知识对服务架构的独立 Linux 原生重新实现。

许可

MIT — 参见 LICENSE。