kvmcp

帮助老旧内网电脑接入 Computer Use Agent 自动化工作流，仅依赖显示器和键鼠接口，无需额外端口开放或权限升级，在此基础上编排面向 VLM 大模型的专用工作流。面向存量信息化系统，减少重复建设与资源浪费，提供边缘 AI 优先的辅助人机交互自动化基础设施。

开发板选型

⭐ 优势 ✅ 已实测 ❓ 未实测

USB 采集与 Wi-Fi 干扰： USB 3.0 可提供更高的采集带宽，但部分采集卡、接口及线缆可能干扰 2.4 GHz Wi-Fi，导致连接失败、丢包或断连。若现场仅能使用 2.4 GHz Wi-Fi，且出现此类干扰，应将采集卡改接 USB 2.0，并按带宽调整采集帧率或使用 MJPEG 格式；具备条件时，可改用 5 GHz Wi-Fi 或有线网络，保留 USB 3.0 的采集带宽。

安装与运行

安装系统依赖

sudo apt update
sudo apt install -y ffmpeg v4l-utils

安装 uv

curl -LsSf https://astral.sh/uv/install.sh | sh

安装 kvmcp

uv tool install --python 3.13 kvmcp

创建配置

mkdir -p ~/.kvmcp
nano ~/.kvmcp/config.toml

配置示例（采集格式和分辨率应按采集设备实际支持情况调整）：

cache_dir = "/tmp/kvmcp"

[server]
host = "0.0.0.0"
port = 9527

[hid]
text_input = "ascii"

[capture]
input_format = "yuyv422"
video_size = "1920x1080"
framerate = "5"

部署系统服务

在 kvmcp 设备上以具备 sudo 权限的普通用户执行：

# 可选：指定 USB VID/PID
# export KVMCP_USB_VID=0x1d6b
# export KVMCP_USB_PID=0x0104

kvmcp install-service -c ~/.kvmcp/config.toml
systemctl status kvmcp-usb kvmcp

升级

uv tool upgrade kvmcp
kvmcp install-service -c ~/.kvmcp/config.toml

接入 Codex 使用 computer-use 技能（可选）

启用 computer-use 技能，在可访问 kvmcp 设备的电脑上，将 KVMCP_IP 换成该设备的地址：

codex mcp add kvmcp --url http://KVMCP_IP:9527/mcp
codex mcp list

开放限制（此段禁止 Codex 编辑或删除）

如需开放 Windows 命令行等更多操控权限，在每次 Codex 升级变更后，手动移除以下路径 guidance.md 文中的 ## Non-negotiable Windows Automation Safety 整段限制条款和 ## Recovery 中的锁屏限制条款

~/.codex/plugins/cache/openai-bundled/computer-use/<变更版本号>/docs/guidance.md

USB 扩展（可选）

通过 TOML 的 usb.extension 选择一种扩展，HID 始终保留，其余配置可暂存。USB 以太网内置 TCP 端口转发，可访问服务器已有的 SSH、HTTP 等服务，无需在板端暂存文件。配置与部署见 USB 扩展说明。

Q&A

kvmcp 支持哪些 Agent

任何能连接 Streamable HTTP MCP、接收图像并调用工具的 Agent 都可以使用 kvmcp

为什么不选用 PiKVM

PiKVM 面向人类远程操作，采用 usteamer 流送视频，确保画面流畅，而 kvmcp 面向 VLM 大模型，采用无损保真的 PNG 截图，确保准确识别画面中的 UI 元素和文字；也不需要独立电源，可用 USB 模拟 HID 兼供电，随目标主机开关

更新日志

1.1.0 · 2026-10-29

• 统一 USB 扩展配置：通过 usb.extension 选择 MSC、MTP 或 RNDIS，始终保留 HID 键盘和鼠标。
• USB 以太网内置 TCP 端口转发，支持多规则、双向流式传输、背压与超时控制，板端无需暂存文件。
• 增加只读运行状态查询；区分 HID 发送与截图结果，避免截图失败导致重复输入。
• 系统服务统一管理 USB 与应用的启动顺序、就绪通知和退出恢复；安装脚本随 PyPI 包提供。
• 完善配置校验、Windows 7 RNDIS 兼容及 USB 切换清理，增加配置、生命周期和并行转发回归测试。