harald

安装  /  工作原理  /  设备  /  经典蓝牙  /  添加设备

图 1 · claude + harald 通过经典蓝牙找到 sony wh-1000xm5 的控制通道，等待你启用耳机，然后开启降噪。真实硬件，视频已加速。

一 工作原理

harald 是一个 MCP 服务、命令行工具和编码 Agent 操作手册。它为 Agent 提供蓝牙低功耗和经典蓝牙的“手”和“耳朵”，让它能够推断你拥有的设备所使用的协议。之后，你可以用自己的代码控制该设备，而不必使用厂商的应用。

监听	解码	通信
harald 从手机的蓝牙日志中读取厂商应用发给设备的内容。	你的 Agent 通过对比数据载荷、测试密钥并搜索厂商的 Android 应用，推断通信语言，包括密钥和校验和。	最终得到文档化的协议和一个自带小型命令行工具的独立驱动脚本。无需厂商应用。

二 安装

你需要 uv。然后：

uv tool install harald

这会将 harald 添加到你的路径中，供下方命令使用。如果你的 shell 找不到它，请运行 uv tool update-shell。若想不安装直接试用 harald，请运行 uvx harald --help：uvx 会获取 harald 并运行一次。已在 mac 上测试。

harald 首次扫描时，macos 会询问是否允许你的终端应用使用蓝牙。请允许。如果错过了提示，可前往“系统设置 › 隐私与安全性 › 蓝牙”开启权限。

以下两个可选工具适用于需要它们的步骤：

• brew install jadx 可让 harald 读取厂商的 Android 应用。
• brew install libimobiledevice 可从终端记录 iPhone 的蓝牙日志。

harald 也可以在没有 Agent 的情况下使用：

harald scan                          list bluetooth le devices nearby
harald connect <address>             list a device's services and characteristics
harald read <address> <char>         read a characteristic once
harald write <address> <char> <hex>  write bytes, once you have armed the device
harald capture open <file>           show a phone capture as a timeline
harald apk <file>                    search a vendor android app for uuids and keys
harald devices                       list the device library
harald drive <slug> <command>        run a library device's driver

harald --help 会列出其余命令；经典蓝牙一节介绍了控制经典蓝牙设备的命令。

三 设备

设备	harald 的发现	状态
sony wh-1000xm5 耳机	通过经典蓝牙控制降噪、环境音和电量	已解码
你的设备	提交包含 device.toml、protocol.md 和 driver.py 的拉取请求	征集中

每个已解码的设备都存放在 devices/ 中，其中记录了协议，并附有独立驱动。harald devices 会列出这些设备，harald drive <slug> <command> 则可运行对应驱动，例如 harald drive <slug> on。

四 Agent 设置

将 MCP 服务添加到你的 Agent，然后安装 playbook：Agent 用来破解设备的分步方法。

claude code，在你的项目文件夹中：

claude mcp add harald -- uvx harald mcp
harald playbook install claude-code --dest .claude/skills/harald

使用 --dest ~/.claude/skills/harald，即可在每个项目中使用此技能。

codex

将以下内容添加到 ~/.codex/config.toml，或运行 codex mcp add harald -- uvx harald mcp：

[mcp_servers.harald]
command = "uvx"
args = ["harald", "mcp"]

然后，在你的项目文件夹中：

harald playbook install codex

这会写入 AGENTS.md。如果你的项目中已有该文件，harald 会保留原样；使用 --dest ~/.codex，即可为每个项目安装。

cursor

将以下内容添加到项目中的 .cursor/mcp.json，或添加到 ~/.cursor/mcp.json，以供每个 项目使用：

{
  "mcpServers": {
    "harald": {
      "command": "uvx",
      "args": ["harald", "mcp"]
    }
  }
}

cursor 没有 playbook；它会直接使用 harald 的工具。

然后，让你的 Agent 使用 harald 研究你的设备。它只会要求你做两件只有你才能做的事。

录制手机与设备之间的通信。 计算机若没有额外硬件，就无法监听手机与设备之间的通信，因此日志需要由你自己的 iPhone 生成。Bluetooth Classic 设备的日志则需要由 Android 手机生成；请参阅 Bluetooth Classic。

1. 在 iPhone 上安装 Apple 的蓝牙日志配置描述文件：前往 Apple 的 配置描述文件和日志 页面，下载“bluetooth for ios/ipados”。该配置描述文件免费。
2. 用线缆将 iPhone 连接到 Mac。打开 Apple 的 Xcode 附加工具中的 PacketLogger，然后选择 File › New iOS Trace。或者，在终端中运行：idevicebtlogger capture.pklg，该命令会持续录制，直到你按下 Ctrl-C。
3. 在厂商应用中，按照 Agent 的要求，每次只执行一项操作，操作之间间隔几秒。
4. 停止录制，保存 .pklg 文件，并将文件路径提供给 Agent。若要自行查看： harald capture open capture.pklg。

如果 PacketLogger 没有记录到任何内容，请移除日志配置描述文件，然后重新安装。

获取厂商的 Android 应用。 如果命令看起来经过了加密，Agent 会要求你提供正在使用的厂商应用 APK。你不需要 Android 手机，harald 也不会下载应用：请自行从 apkmirror 下载，该网站会验证每个应用的签名；也可以使用 apkeep（apkeep -a <package name> .）下载。包名就是应用 Play 商店地址中 id= 部分的内容。

五 Bluetooth Classic

一些小工具（通常是耳机和扬声器）通过 Bluetooth Classic 而非 Bluetooth LE 控制：厂商应用会与 RFCOMM 通道通信，该通道是普通字节流。Harald 目前也能连接这些设备，但仅限 Mac；Bluetooth LE 的使用方式保持不变。

请先在系统设置 > Bluetooth 中配对小工具，并让它保持连接。Harald 不会搜索或配对 Classic 小工具，harald scan 也只能发现 Bluetooth LE 设备。Classic 地址的格式类似 aa:bb:cc:11:22:33。

harald classic devices                         list the gadgets paired with this mac
harald classic services <address>              list a gadget's rfcomm services
harald classic send <address> <service> <hex>  send messages, once you have armed it
harald classic listen <address> <service>      show what a channel says, sending nothing
harald capture open <file> --channel n         show one rfcomm channel of a capture

<service> 是来自 harald classic services 的服务 UUID 或通道号；如果列表看起来已经过期，可在该命令中添加 --refresh。harald classic send 接受一条或多条消息，并按顺序发送，每条消息发送后都会监听回复（--listen s，默认为 2 秒）。如果授权额度用完或连接中途失败，它会打印已发送和已接收的内容，在标准错误中说明原因，并以状态码 1 退出。harald classic listen 不发送任何内容，只监听 --seconds s 指定的时长（默认为 5 秒）。两种监听每次最长均为 30 秒。

和 harald write 一样，harald classic send 需要先运行 harald arm <address>；每条消息都会消耗授权额度中的一次写入机会，查询也不例外。Harald 绝不会打开免提或文件传输等受保护配置文件的通道；请参阅安全。你的 Agent 可以使用同样的四种 MCP 工具：classic_devices、classic_services、classic_send 和 classic_listen。它们都不会进行授权。

Classic 捕获数据需使用 Android 设备获取。 iPhone 对 Classic 小工具的捕获数据只会显示 Apple 的 iAP2 封装，Harald 目前还无法解开。因此，请从 Android 手机的 Bluetooth 日志中记录厂商应用的操作：

1. 开启开发者选项（在手机的“关于”页面中连续点按版本号七次），然后在其中开启 Bluetooth HCI snoop 日志；如果系统询问，请选择“已启用”，而不是“已过滤”。
2. 关闭厂商应用，然后关闭并重新开启手机的 Bluetooth，以便在应用打开通道前启动日志记录。
3. 在厂商应用中，按照 Agent 的要求，每次只执行一项操作，每项操作间隔几秒。
4. 开启 USB 调试后，运行 adb bugreport。生成的 ZIP 文件中包含 btsnoop_hci.log；将该文件的路径提供给 Agent，或者使用 harald capture open btsnoop_hci.log 自行查看。

harald apk 会标记厂商 Android 应用中的 RFCOMM 套接字和 UUID，以及该应用的 Bluetooth LE 调用。

六、安全

harald 仅用于你拥有的设备：互操作性研究。不要在他人的设备上使用。

• 写入需要你亲自授权。 在你自己的终端中运行以下命令前，harald 会拒绝所有写入：

  harald arm <address> --writes n --minutes m
  

  这会授予在 m 分钟内执行 n 次写入的额度（如果省略标志，则为 50 次和 30 分钟），每次写入都会消耗一次额度。它会显示授权内容，并等待你输入 arm；没有终端时则会拒绝运行。harald status 会显示当前已授权的内容，harald disarm <address> 会撤销授权。没有用于授权的 MCP 工具。

• 授权门禁有其局限。 harald arm 可以阻止 Agent 随意或意外授权，但它不是沙箱。授权信息保存在文件 ~/.harald/arm.json 中；任何能在你的机器上运行任意命令或写入文件的 Agent 都可以绕过门禁。协作型 Agent 不会越界，是因为 playbook 规定：它绝不会在自己的 shell 中运行 harald arm、harald write、harald drive、harald classic send 或驱动程序；这些操作由你执行。它只通过 classic_send 工具发送 classic 消息。

• 固件更新会被阻止。 即使设备已授权，写入固件更新（dfu）服务仍会遭到拒绝，因此意外写入无法启动固件更新。只有在 harald arm 中使用 --allow-dfu 才能解除此限制，而研究协议并不需要这样做。harald 也会以相同方式阻止它所识别的 classic 固件更新通道，目前包括 airoha 的工具通道，除非你使用 --allow-dfu 授权。不过，许多 classic 设备会通过普通控制通道接收固件，harald 无法区分更新消息与其他消息，因此你的 Agent 绝不能发送用途不明的消息。

• classic 通道受到限制。 如果设备的服务记录列出了免提、耳机、拨号网络、obex 对象推送和文件传输、电话簿、消息、SIM 访问或 apple iap2，harald 就不会打开该通道。串行端口配置文件不受此限制，因为许多设备的控制通道会使用它。harald 也会拒绝设备服务列表中未列出的通道。使用 harald classic send 时，每条消息都会消耗一次写入额度，查询也不例外。

• 库中的驱动程序无需授权。 harald drive 会运行 devices/ 条目中的独立驱动程序；该程序由你亲自启动，因此不受门禁限制。运行前请先阅读驱动程序，就像对待任何脚本一样。

• 只共享应用级密钥。 devices/ 条目中只有在每台设备上都相同、且随厂商应用一同发布的密钥才可收录。每台设备专属的密钥和配对密钥不得放入库中；它们应留在你自己的 harald-work/ 文件夹中。

七、贡献设备

破解了某个设备？你的 Agent 的工作成果位于 harald-work/<slug>/。将其整理为包含 device.toml、protocol.md 和 driver.py 的 devices/<slug>/，然后提交拉取请求。 贡献指南中有详细说明，包括密钥规则。

_{MIT 许可证。harald 的名称来自丹麦国王 Harald “Bluetooth”，蓝牙也因此得名；ᚼᛅᚱᛅᛚᛏᚱ 是刻在耶灵石上的他的名字。}