Onsense

onsense — 为 PC AI Agent 提供手机摄像头、传感器和文件

别描述，让 AI 亲眼看看。 onsense 是 PC 端的 MCP 中介服务，可与 onSense Android 应用配合使用：在 PC 上运行 uvx onsense pair，任何支持 MCP 的 AI——Claude Code、Claude Desktop、Codex 或你自己的 Agent——都能通过手机摄像头查看画面、读取传感器数据，并双向传输文件和剪贴板内容。无需云中继，无需 ADB。

Claude Code 在 PC 上运行，通过手机读取传感器数据并查看摄像头画面，实时作答，整个过程通过本地 Wi-Fi 完成。

……Codex 也可以做到同样的事。onSense 是标准的 MCP 服务，因此可与任何 MCP 客户端配合使用。

---

架构

Android phone (onSense app)           PC (this package)           AI client
  HTTP provider :8080        ←→    stdio MCP broker          Claude / Codex / …
  camera frames, photos,           onsense serve               natural-language or
  sensors, QR pairing              onsense clip :8770          /onsense tool calls

• 手机在 8080 端口运行 HTTP 提供程序。它提供摄像头画面、近期照片和传感器读数，所有访问均需通过配对令牌验证。
• PC 软件包（onsense）是一个 stdio MCP 中介服务。它将 AI 客户端发起的 MCP 工具调用转换为发往手机的 HTTP 请求。
• 设备发现使用 mDNS（_onsense._tcp.local.）。如果手机的 IP 地址发生变化，中介服务会自动重新发现，无需手动重新配置。
• 可选的 剪贴板桥接守护进程在 8770 端口运行，让手机将摄像头画面、文件和剪贴板内容推送到 PC（如果启用，还允许手机读取 PC 剪贴板内容）。

---

要求

• uv（提供 uvx；会自动下载并管理 Python，无需单独安装 Python）
• 手机已安装 onSense Android 应用，且与 PC 连接到同一局域网 Wi-Fi
• 兼容 MCP 的 AI 客户端，例如 Claude Code、Codex 或任何 stdio MCP 客户端

---

快速开始

0. 新 PC 尚未安装 uv？使用应用的设置助手（推荐）

在全新 PC 上，uvx 尚不存在，因此运行下面的命令会失败，并提示 “'uvx' is not recognized”。最简单的解决办法是：先安装 onSense 应用，点击 “Start PC setup helper”，然后在 PC 上打开显示的地址。应用会提供一条命令，一次性完成 uv 安装、设备配对和 MCP 服务注册；由于 PC 会主动连接手机，因此也完全避开了 Windows 防火墙。

想自行安装 uv？只需一条命令：

# Windows (PowerShell)
irm https://astral.sh/uv/install.ps1 | iex
$env:Path = "$env:USERPROFILE\.local\bin;$env:Path"   # make uvx visible in this same shell

# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh
export PATH="$HOME/.local/bin:$PATH"

1. 配对手机

运行一次即可。PC 会显示 QR 码；用 onSense 应用扫描（“Scan PC QR”）。手机会将自己的地址和令牌发送到 PC，PC 随即自动注册 MCP 服务。

uvx onsense pair

配对后，重启一次 AI 客户端，以便加载新的 onsense MCP 服务。

2. 开始使用

直接向 AI 客户端提出请求：

“拍一张手机前方景物的照片。” “当前的传感器读数是什么？” “显示手机上最近的 5 张照片。”

MCP 工具会自动调用。在 Claude Code 中，你还可以使用随附的 /onsense 斜杠命令（配对时安装）。

3. 排查问题

uvx onsense doctor           # checks Python, uv, MCP, Claude registration, mDNS, phone reachability
uvx onsense doctor --base http://192.168.1.5:8080 --token YOUR_PAIRING_TOKEN

Windows：扫描二维码超时？

首要原因是 Windows 防火墙阻止了手机的入站连接：

• 如果你的 Wi-Fi 网络配置文件是公用，入站流量会被严格阻止。请将其切换为专用（设置 → 网络 → 你的 Wi-Fi → 网络配置文件），或者直接使用应用的PC 设置助手，完全不需要入站端口。

• 在专用网络上，添加一条长期有效的允许规则（以管理员身份运行）：

  uvx onsense pair --fix-firewall
  

  首次运行时弹出的防火墙窗口按程序路径设置规则，而 uvx 的临时路径会导致该规则失效。上面的按端口设置的规则（TCP 8765–8774，专用）才会真正生效。

• 如果端口 8765 已被占用，pair 会自动回退到下一个空闲端口（最高到 8774），二维码中也会显示实际端口——无需任何操作。

---

子命令

命令	功能
uvx onsense pair	在 PC 上显示二维码；手机扫描后会推送 {base, token}；并自动注册 MCP
uvx onsense pair "onsense://pair?base=...&token=..."	直接解析配对 URI（手机显示二维码 → 手动复制）
uvx onsense pair --img screenshot.png	从截图文件中解码配对二维码（需要 opencv）
uvx onsense serve	运行 MCP 服务（stdio）。除非传入 --no-clip，否则也会自动启动剪贴板守护进程
uvx onsense serve --no-clip	仅运行 MCP 服务，不启动剪贴板守护进程
uvx onsense clip	独立运行剪贴板桥接守护进程（端口 8770）
uvx onsense clip --allow-pull	启用手机→拉取：手机可以 GET /clip 来获取 PC 剪贴板内容
uvx onsense clip --set-clipboard	自动将收到的内容注入 PC 操作系统剪贴板（默认关闭）
uvx onsense pair --fix-firewall	（Windows，管理员）添加长期有效的按端口设置的防火墙规则，然后像往常一样配对
uvx onsense doctor	诊断安装、连接和手机可访问性
uvx onsense stats	显示仅存储在本地的激活统计信息（--json、--reset）。不会自动上传任何内容

---

其他 MCP 客户端（Claude Desktop、Codex 等）

uvx onsense pair 会自动将服务注册到 Claude Code（通过 claude mcp add）——这一行命令自动设置的方式仅适用于 Claude Code。MCP 服务本身是标准的 stdio MCP，因此添加手动配置后，任何兼容 MCP 的客户端都可以使用。请先运行一次 uvx onsense pair：它会将手机的地址和令牌保存到 ~/.onsense/pair.json，服务会在收到请求时读取该文件——因此无需在每个客户端的配置中填写令牌，而且手机的 IP 会通过 mDNS 自动跟踪。

Claude Desktop——添加到 claude_desktop_config.json：

{ "mcpServers": { "onsense": { "command": "uvx", "args": ["onsense", "serve"] } } }

Codex——通过 CLI 注册（已在 Codex CLI 0.142.5 中验证）：

codex mcp add onsense -- uvx onsense serve

**Codex 沙盒提示：**Codex 的默认沙盒会阻止网络访问，因此 MCP 服务无法连接手机，工具调用也会静默失败。请启用网络访问后运行 Codex（例如使用 --sandbox danger-full-access，或采用允许网络访问的沙盒策略），这样 onsense 才能通过局域网连接手机。

或者添加到 ~/.codex/config.toml：

[mcp_servers.onsense]
command = "uvx"
args = ["onsense", "serve"]

添加服务后，重启一次客户端。其他任何 stdio MCP 客户端也都采用相同方式——将其指向 uvx onsense serve。

---

MCP 工具

配对后，这些工具会向你的 AI 客户端开放：

工具	描述
get_live_frame()	从手机拍摄当前相机画面（返回 JPEG 图像）
read_sensors()	以 JSON 格式返回手机传感器读数：电池电量／充电状态、环境光照（lux）、加速度计（x/y/z）
recent_photos(limit=10)	列出手机上的近期照片：id、name、date_added、size、width、height
get_photo(id, max_width=1024, save_original=False)	按 id 获取指定照片（缩小至 max_width）；请使用 recent_photos 中的 id。此外还会将照片保存到与 get_reference 相同的 Downloads 文件夹，并返回路径，以便图像在对话结束后仍然保留。save_original=True 会存档原始分辨率的照片，而非缩小后的副本
rename_photo(path, name)	重命名已获取的文件，以描述图像实际呈现的内容（photo_1000024531.jpg → whiteboard_sprint_plan.jpg）。AI 会在查看图像后立即调用此工具，因此不会额外消耗令牌
get_reference()	获取手机指定的参考来源——实时相机画面、拍摄的照片或任意文件（包括非图像文件）——并将其保存到磁盘，同时返回路径和元数据。这是文件／采集桥接的核心
get_cam_fps()	读取手机当前的相机 FPS 设置（15 = 高性能，2 = 平衡，0 = 按需）
set_cam_fps(fps)	设置手机的相机 FPS：15（高性能）、2（平衡，推荐）或 0（省电／按需）

如果手机的 IP 地址发生变化，broker 会先通过 mDNS 自动发现重试，然后再报告错误。

---

剪贴板桥接（手机 ↔ PC 文件与剪贴板）

onsense serve 会自动在 端口 8770 上启动剪贴板守护进程。你也可以通过 onsense clip 单独运行。

手机 → PC 推送（POST /clip）

onSense Android 应用可以向 PC 推送内容：

• 图像会以 latest.jpg 为文件名保存到磁盘（位于 ONSENSE_CLIP_DIR，默认值为 <tempdir>/onsense/）。
• 文本文件会保存到磁盘。
• 其他文件（视频、PDF 等）会按文件名保存到磁盘。
• 如果启用了 --set-clipboard，图像和文本也会写入 PC 操作系统剪贴板，因此你可以立即按 Ctrl+V 粘贴。

默认情况下，--set-clipboard 为关闭状态——文件会保存到磁盘，但不会修改剪贴板。

PC → 手机拉取（GET /clip）

默认关闭。启用方式：

uvx onsense clip --allow-pull

启用后，手机可以通过 GET /clip 获取当前 PC 剪贴板内容（优先返回复制的文件，其次是图像，最后是文本）。剪贴板为空时返回 204。

端口和环境变量

变量	默认值	用途
PHONE_BASE	（来自配对）	手机 HTTP 基础 URL，例如 http://192.168.1.5:8080
PHONE_TOKEN	（来自配对）	配对身份验证令牌
ONSENSE_CLIP_DIR	<tempdir>/onsense	推送文件的保存目录
ONSENSE_CLIP_MAX_MB	200	接收文件的最大大小，单位为 MB（0 = 不限）
ONSENSE_CLIP_ALLOW_PULL	0	设为 1，即可在不使用 CLI 标志的情况下启用 PC → 手机拉取
ONSENSE_CLIP_SET_CLIPBOARD	0	设为 1，即可在不使用 CLI 标志的情况下自动写入操作系统剪贴板
ONSENSE_TEST_FRAME	（未设置）	手机不可达时，get_live_frame 返回的本地 JPEG 路径

---

安全

仅限本地网络。 PC 端服务会绑定到所有网络接口，但会在应用层拒绝来自非私有 IP 地址的连接。它们并非用于暴露到互联网。

HMAC 请求签名。 配对令牌绝不会以明文形式发送。每个经过身份验证的请求都会使用 HMAC-SHA256 签名，签名内容为 METHOD\npath\ntimestamp\nnonce\nalgorithm，密钥是通过 HKDF-SHA256 从配对令牌派生的签名密钥（与加密密钥分开），并携带 X-Ts / X-Nonce / X-Sig / X-Enc 请求头。服务端会以恒定时间进行验证，拒绝时间戳超出 ±300 s 范围的请求，并拒绝重复使用的随机数，因此即使请求被嗅探，也无法重放，令牌也无法通过网络被窃取。新安装的 Android 会生成一个 128 位随机令牌；配对后，该令牌会存储在手机上以及 ~/.onsense/pair.json（chmod 600）中。（/health 端点无需身份验证。）确切的线上格式请参见 PROTOCOL.md。

默认关闭拉取和剪贴板注入。 除非明确传入 --allow-pull 或 --set-clipboard，否则会禁用 GET /clip（手机拉取 PC 剪贴板）和 OS 剪贴板自动注入（手机推送 → Ctrl+V）。

加密消息正文（AES-256-GCM）。 敏感负载——相机画面、照片、传感器数据、文件和剪贴板内容——会使用 AES-256-GCM 在手机和 PC 之间加密传输（中间没有云服务，因此不存在能够解密数据的第三方）。密钥通过 HKDF-SHA256 从配对令牌派生（与签名密钥分开）；每条消息都会使用一个新的 96 位随机数，GCM 标签会对消息正文进行身份验证，并将其绑定到对应请求（因此篡改或替换响应都会被拒绝）。同一 Wi-Fi 网络上的被动嗅探者只能看到密文。低敏感度元数据仍以明文传输：开放的 /version 和 /health 端点、HTTP 错误响应，以及推送后返回的已保存文件路径。（注意：目前在加密或解密大型传输内容时，会将消息正文缓冲在内存中；未来会为超大文件加入分块流式处理。传输层 TLS 也可能作为未来的强化措施。）

文件大小上限。 如果传入的推送内容超过 ONSENSE_CLIP_MAX_MB（默认 200 MB），将被拒绝。设为 0 可移除上限。

报告漏洞。 请私下报告安全问题——参见 SECURITY.md。请勿公开提交安全问题报告。

---

许可证

MIT。参见 LICENSE。