跳到主要内容
版本：0.4.x

VibeKeys Max 遥控模式

在遥控模式下，VibeKeys Max 通过 MQTT broker 连接到你的电脑，让你用语音输入和物理按键控制 Claude Code 或 OpenAI Codex——无论你在哪里。电脑上无需暴露任何端口：两端都只是同一个 broker 的 MQTT 客户端。

两端都必须是 0.4.x

MQTT 协议是 0.4.0 新引入的，与之前的版本不兼容。设备需要 v0.4.0+ 固件，电脑需要 vibetty 0.4.x——旧固件无法连接或正常显示。如果设备还在 0.3.x，请通过页面顶部的版本下拉框切换到 0.3.x 版文档。

准备工作​

前置要求
  • 固件为 v0.4.0 或更新版本的 VibeKeys Max
  • 一台运行 macOS、Linux 或 Windows 10 (1809+) / Windows 11 且装有 vibetty 0.4.x 的电脑
  • Claude Code 2.1.0 或更新版本，或 OpenAI Codex
  • 一个 MQTT broker——用 vibetty 内置的 broker（零配置）或任意托管 MQTT 服务均可

第一步：使用 vibetty 启动编程 agent 服务​

vibetty 是 VibeKeys Max 和你的编程 agent（Claude Code 或 OpenAI Codex）之间的桥梁。它在你的电脑上以终端方式运行 agent，并通过 MQTT 共享该会话。

下载 vibetty 可执行文件​

从 vibetty releases 页面下载最新的预编译版本，选择对应平台的构建，或使用以下命令。

macOS（M 芯片）​

curl -LO https://github.com/second-state/vibetty/releases/latest/download/vibetty-macos-arm64
chmod +x vibetty-macos-arm64
sudo mv vibetty-macos-arm64 /usr/local/bin/vibetty

Windows​

Invoke-WebRequest -Uri "https://github.com/second-state/vibetty/releases/latest/download/vibetty-windows-x64.exe" -OutFile "vibetty.exe"
# 加入 PATH 或移动到 PATH 中的目录

Linux​

wget https://github.com/second-state/vibetty/releases/latest/download/vibetty-linux-x64
chmod +x vibetty-linux-x64
sudo mv vibetty-linux-x64 /usr/local/bin/vibetty

想自己编译？参见下方从源码构建。

配置 MQTT broker（一次性）​

VibeKeys 和 vibetty 之间从不直接通信。它们都连接到同一个 MQTT broker——一个消息中转站——所有内容（屏幕画面、按键）都经由它传递：

VibeKeys（键盘）──>  MQTT broker  <──  vibetty（你的电脑）

因为两端都只是主动向 broker 发起连接，你的电脑不需要做任何端口映射或防火墙配置。先运行一次 vibetty setup——它会打开一个交互式配置界面，并写入 ~/.vibetty/config.toml。然后从下面两种方案中选一种。

方案 A：内置 broker——最简单（设备和电脑在同一 WiFi 下）​

vibetty 可以自己运行 broker——无需外部服务，不用注册账号：

[mqtt]
enable = true
builtin_broker = true
builtin_port = 1883      # 内置 broker TCP 端口

设备直接连接你的电脑，所以在 setup 页面要填 mqtt://你电脑的局域网IP:1883（见第二步）。两者必须在同一网络下。

警告

内置 broker 没有鉴权，只适合本地网络使用——不要把它暴露到公网。

如果你先试过方案 B，切回来之前要把 broker 那一行清空。只要 broker 非空就优先生效，vibetty 会启动内置 broker，但客户端仍然连旧地址。

方案 B：云端 broker——设备随处可用​

想在离开电脑的地方使用设备（咖啡馆、酒店、手机热点），就让两端都连接一个各自能从公网访问的 broker。对单个用户来说，注册一个免费的 MQTT 云服务就够了——例如 EMQX 提供免费选项：

[mqtt]
enable = true
broker = "mqtts://user:pass@broker.emqx.io:8883"

之后在 setup 页面，把同一个 URL 填到设备上。

凭据写在 URL 里

没有单独的用户名/密码字段——直接写在 broker URL 中：mqtt://user:pass@host:port。broker 在公网上时建议使用 mqtts://（TLS）。

运行共享会话​

在 -- 后面传入你的编程 agent——Claude Code 用 claude，OpenAI Codex 用 codex：

cd path/to/workspace/
vibetty -- claude   # Claude Code
vibetty -- codex    # OpenAI Codex

Windows 上在 PowerShell 或命令提示符中使用 .exe：

cd path\to\workspace\
vibetty.exe -- claude

vibetty 界面顶部的 MQTT 按钮显示 conn 时，表示已连上 broker 并开始共享。

可以附加任意 claude 参数：

# YOLO
vibetty -- claude --dangerously-skip-permissions

# 恢复此工作区的上次会话
vibetty -- claude -c --dangerously-skip-permissions
让 agent 自己开会话

vibetty skill install --claude --codex 会为 Claude Code / Codex 安装 run-vibetty skill，让你的 agent 知道如何自己启动一个可共享的后台会话。

想让会话在后台运行、不占用终端：

tmux new-session -d -s vibetty -c "$HOME/workspace" 'vibetty -- claude'

从源码构建​

如果想从头构建，请查看 vibetty GitHub 仓库并按其构建说明操作。

第二步：把 VibeKeys Max 连到 broker​

  1. 给 VibeKeys Max 开机，在启动菜单中选择 Keyboard——配置服务只在键盘模式下广播。
  2. 用 Chrome 或 Edge 打开 VibeKeys setup 页面（Web Bluetooth 需要这些浏览器，且必须是 HTTPS）。
  3. 点击 Connect，在列表中选择你的 VibeKeys Max。
    • 找不到设备？设备一旦作为蓝牙键盘连上了某个主机，就会停止广播。在设备上按 ACCEPT 键重新开始广播，然后再试。
  4. 添加 WiFi 网络——最多 8 个。列表顺序就是优先级顺序：开机时设备会扫描并连接范围内排在最前面的网络，所以把你常用的网络（办公室、咖啡馆、家）一次性都加上，设备走到哪都能自动连上。网络必须是 2.4GHz（VibeKeys Max 不支持 5GHz）。
  5. 填写 MQTT broker 地址——与你在 vibetty 里配置的 broker 一致：
    • 方案 A（内置 broker）：mqtt://你电脑的局域网IP:1883
    • 方案 B（云端 broker）：与你在 vibetty setup 中填写的 mqtts://user:pass@... URL 完全相同。
  6. 填写 ASR 语音识别字段（见语音输入），然后点击 Save Changes。

设备会把配置保存在本地，断电重启后自动重连——只要你保存过的任一 WiFi 网络在范围内。

第三步：开始 vibe coding​

  1. 开机，在启动菜单中选择 Remote。设备连上 broker 后打开会话选择器，列出你正在运行的所有 vibetty 会话。
  2. 选择会话：NEXT 移动焦点，ACCEPT 选中。每一行标签的颜色反映 agent 的实时状态——白色 = working（工作中），橙色 = stopped / waiting（停止/等待）；焦点行有蓝色背景。
  3. 在远程终端中操作会话：
按键功能
旋钮上 / 下滚动终端输出
ACCEPT发送 Enter
ESC发送 ESC
NEXT发送 ↓
BACKSPACE发送 Backspace
CUSTOM输入 /compact
YOLOShift + Tab（允许所有编辑）
按下旋钮（重新）打开会话选择器，切换会话
MIC语音输入——见语音输入
  1. 同时运行多个 agent，随时用旋钮在它们之间切换——无需重新连接。

以 Herdr 插件方式运行 vibetty​

如果你使用 Herdr，vibetty 可以作为插件运行，而不需要单独的命令：

herdr plugin install second-state/vibetty

然后在 Herdr 命令面板中触发 share 动作（或绑定快捷键）即可共享当前 agent 面板——vibetty 状态栏会实时显示 MQTT 连接状态。详见 vibetty README。

没有硬件也能试​

vibetty 的 HTTP 服务（在其界面中按 HTTP 按钮开启）提供 /mqtt_ws，一个基于浏览器的 MQTT 查看页，带终端视图、键盘输入和会话列表。设备配置好之前，可以用手机或笔记本先测试 broker 是否通。

相关文档​