Beyond Cortex + VOLTRA I 使用指南：从安装到完成第一组训练

编辑说明

本文由 r/BeyondPower 社区成员、Lifteccentric 的 u/ApprehensiveTone6707 撰写，经授权转载。感谢作者投入时间整理这份指南。

Beyond Power 推出了 Cortex——一款可以让你（以及你的 AI 助手）直接控制 VOLTRA 的命令行工具。它功能强大，也有一定的技术门槛。本文会说明 Cortex 是什么、每条命令有什么作用，以及不具备计算机专业背景的用户，如何从零开始完成第一组受控训练。

如果你希望借助 AI 使用 VOLTRA，但不想配置 Cortex CLI，也可以通过普通 App 使用 Eccentric：无需终端和本地安装，可通过手机或浏览器访问。

→ 使用 AI 规划、记录和优化训练

Beyond Power 将 Cortex 称为“VOLTRA 的 AI Agent Kit”。这个描述没有错，但如果你从未安装过开发者工具，它可能仍然不够直观。简单来说：

Cortex 是一个通过终端窗口输入命令来运行的程序。它通过蓝牙与 VOLTRA 通信，并通过互联网连接你的 Beyond+ 账户。输入 voltra set-weight 60 可以设置阻力；输入 voltra load 可以让缆绳加载阻力；输入 voltra workout list 则可以调取训练记录。

之所以采用命令行形式，是因为运行在电脑上的 AI 助手——例如 Claude Code、Codex、Cursor 等——很擅长调用命令行工具。把 Cortex 交给这样的 AI 助手，它就能读取你的训练记录、设计训练计划、创建阻力曲线，并为你配置设备。这正是 Cortex 的核心价值。

不过，有两点需要提前说明。

第一，使用 Cortex 要从终端开始。如果你从未接触过命令行，这份指南就是为你准备的。

第二，这里的关键前提是：AI 助手必须“运行在你的电脑上”。浏览器标签页中的 Claude 或 ChatGPT 无法访问 Cortex，手机 App 也无法访问。这是用户对 Cortex 最常见的误解，因此有必要在继续之前先说明清楚。

这是一份怎样的指南

本文根据 Cortex 当前 Beta 版本的官方文档编写。所有命令均原样引用自 Beyond Power 文档；但 Beta 软件仍会持续更新，如果实际情况与本文不一致，请以官方参考文档为准。

本文目录

1. 使用前需要了解的情况

2. 第 0 步：打开终端

3. 第 1 步：检查运行环境

4. 第 2 步：保存 API Key

5. 第 3 步：查找并连接设备

6. 第 4 步：确认物理风险

7. 第 5 步：完成第一组受控训练

8. 其他训练模式

9. 查看训练记录

10. Skills、更新与 AI

11. 常见问题排查

12. 或者：完全跳过终端

使用前需要了解的情况

开始安装之前，建议先了解以下四点。

Cortex 运行在电脑上，而不是手机上。目前提供适用于 Apple 芯片 Mac 的 macOS 安装程序、适用于 64 位 Linux 的安装程序，以及适用于 Windows 的 PowerShell 安装程序；暂不支持 Intel 芯片 Mac。由于设备通过蓝牙连接，运行 Cortex 的电脑必须位于 VOLTRA 附近。

AI 助手也必须运行在同一台电脑上。这一点最容易被忽略。Cortex 安装在你的电脑上，AI 助手只有获得在这台电脑上运行程序的权限，才能调用 Cortex。换句话说，你需要的是具备终端访问权限的本地 Agent。

申请 Beta 测试资格前，请先阅读

浏览器标签页中的 Claude 或 ChatGPT 无法访问 Cortex，它们的手机 App 同样无法访问。Cortex 目前也没有可供这些应用连接的托管端点。

这不是漏开了某项权限，也不是等待下个月更新就能解决的问题。网页或手机 App 无法直接运行你笔记本电脑上的程序，而运行本地程序是 Cortex 当前唯一的工作方式。

目前可以控制 Cortex 的包括：

• 安装 Cortex 的电脑上，通过终端运行的 Claude Code、Codex、Cursor 或其他 Agent；
• 直接在终端中输入命令的你本人。

目前无法控制 Cortex 的包括：

• 浏览器标签页中的 Claude；
• 浏览器标签页中的 ChatGPT；
• Claude 手机 App；
• ChatGPT 手机 App；
• 运行在其他电脑上的任何 AI 助手，即使那台电脑并未连接你的 VOLTRA。

因此，正确的理解不是“我的 AI 现在可以控制 VOLTRA”，而是“当 AI 运行在 VOLTRA 旁边的这台电脑上时，它可以控制 VOLTRA”。这项能力真实且实用，但适用范围比“AI Agent Kit”这个名称可能带来的第一印象更窄。安装之前，最好先明确这一点。

Cortex 不能替代 Beyond+ App。官方文档对此说明得很直接：CLI 可以管理训练计划模板，但“不能执行训练计划”。实际的引导式训练仍需通过 iOS 版 Beyond+ App 完成。Cortex 可以控制硬件并读取数据，但它不是训练操作界面。

Cortex 仍处于 Beta 阶段，且需要申请权限。请将 Beyond+ 手机 App 更新至最新版本，找到 Beyond Cortex 横幅并申请访问权限，再按照 App 内的说明在电脑上完成安装。目前没有公开下载链接。

第 0 步：打开终端

如果你平时已经习惯使用终端，可以跳过这一节。

• Mac：按下 ⌘ + Space，输入“Terminal”，然后按 Enter。
• Windows：打开“开始”菜单，输入“PowerShell”，然后按 Enter。
• Linux：打开你常用的终端。

屏幕上会出现一个带闪烁光标的窗口。下文中的命令需要逐行输入，每输入一行后按 Enter。只复制和运行你理解的命令：终端和其他功能强大的工具一样，可以修改或删除文件。对于会让缆绳产生实际阻力的 Cortex 命令，本文会在后文明确标出。

安装程序会将程序安装到 ~/.voltra/bin/voltra，并把该文件夹添加到 PATH。这样，你在任何位置输入 voltra 即可运行程序，无需输入完整路径。如果安装后立即出现“command not found”，通常只需关闭当前终端窗口，再打开一个新窗口。PATH 的变更只会在新窗口中生效。

第 1 步：检查运行环境

voltra doctor

这条命令用于检查当前环境中是否存在明显问题。首次使用时先运行一次；以后遇到异常，也可以再次运行。它会检查权限、蓝牙和安装状态等项目，让你在配置训练之前就发现权限缺失等问题。

第 2 步：保存 API Key

API Key 用于让 Cortex 验证你的身份。你可以在 Beyond+ 的 Cortex 配置流程中获取；该密钥与你的个人账户绑定。

voltra config set-api-key <YOUR_KEY>

请将 <YOUR_KEY> 替换为实际密钥，不要保留尖括号。保存前，Cortex 会通过 Beyond Power 的服务器验证密钥。–force 可以跳过验证，但通常不建议这样做。

确认密钥是否保存成功：

voltra config show

voltra whoami

config show 会显示密钥已保存，并以隐藏部分字符的形式呈现。whoami 会向服务器发起请求并返回账户信息，这是确认密钥有效的直接方式；同时还会刷新 ~/.voltra/user-preferences.json 中的用户偏好文件。

如果需要解除电脑与账户的关联，例如准备出售或转交电脑，可运行：

voltra config clear-api-key

像保护密码一样保护 API Key

API Key 以普通文件形式保存在主目录的 ~/.voltra/ 文件夹中。任何获得该密钥的人，都可能读取你的训练记录并控制你的设备。请勿将密钥粘贴到聊天窗口、截图或公开代码仓库中。

workout、actions、session 和 custom-curve 等云端命令支持通过 –api-key <key> 临时指定密钥；设备与训练命令则必须使用已保存的密钥。相关命令还支持 –json，以机器可读格式输出结果，而不是便于人类阅读的排版。正是这个 –json 参数，让 AI 助手能够更顺畅地使用 Cortex。

第 3 步：查找并连接设备

唤醒 VOLTRA，然后运行：

voltra scan

该命令会列出附近的 VOLTRA。默认情况下，它只显示能够识别的设备；添加 –all 可以查看扫描到的全部设备。如果没有找到设备，可通过 –《时代》周刊out-ms 增加扫描时间，同时确认蓝牙已开启，并检查 VOLTRA 是否仍被手机上的 Beyond+ App 占用。

随后连接设备：

voltra connect <DEVICE_ID>

你可以输入设备 ID、完整设备名称，或者直接输入扫描列表中的序号，例如 voltra connect 1。连接时，Cortex 会与设备完成握手、记住该设备，并启动后台会话，使连接在不同命令之间保持有效。

随时运行以下命令查看状态：

voltra status

它会显示设备是否已连接、电池电量、当前模式和当前阻力。

第 4 步：确认物理风险

每台电脑只需完成一次确认，但这一步不可省略。

voltra config accept-physical-risk

Beyond Power 文档将其描述为：“在 load 命令施加力之前，必须完成的一次性确认。”这里需要按字面理解：load 会启动电机，让缆绳产生实际阻力。如果你正握住手柄，会立即感受到阻力；如果缆绳处于伸出状态而你没有握住手柄，缆绳会回收。

从第一天起，建议养成两个习惯：

1. 开始前先确认如何停止。voltra unload 可以在任何模式下释放阻力。在输入 load 之前，先准备好这条命令。

2. 先设置阻力，再加载阻力。先完成阻力配置，再启动电机；不要颠倒顺序。

第 5 步：完成第一组受控训练

以下是官方文档中的力量训练流程，并附有中文说明：

voltra set-mode weight-training       # 设置训练模式

voltra set-weight 20 --unit lbs       # 设置基础阻力

voltra set-chains 5                   # 可选：缆绳伸出时逐渐增加阻力

voltra set-eccentric 5                # 可选：增加离心阶段阻力

voltra load                           # 加载阻力；执行前请先就位

voltra status                         # 检查实际应用的设置

voltra unload                         # 释放阻力

voltra finish-training                # 结束本次训练

voltra disconnect                     # 断开设备连接

请选择 –unit lbs 或 –unit kg 中的一种单位并保持一致。混用单位可能导致实际阻力与预期不符。

另一个容易忽略的规则是：切换模式前，设备必须处于未加载状态。如果 set-mode 无法执行，请先运行 unload。

阻力调节命令

这是 VOLTRA 最有特点的部分之一，Cortex 提供了相应的控制命令。

命令	实际作用
voltra set-weight <n>	设置基础阻力。
voltra set-eccentric <n>	设置离心阶段的额外阻力。允许使用负值，使离心阶段的阻力低于向心阶段。
voltra set-chains <n>	随缆绳伸出逐渐增加阻力，类似铁链逐渐离地时的阻力变化。
`voltra set-inverse-chains <on\	off>`	反转阻力曲线：起始位置阻力最大，随缆绳伸出逐渐降低。
voltra set-auto-unload <s> <r>	安全保护设置：保持静止 <s> 秒或完成 <r> 次重复后，自动降低阻力。

如果你独自训练，建议尽早配置 set-auto-unload。这样可以在完成一组训练后自动降低阻力，无需一边控制动作，一边寻找电脑执行命令。

其他训练模式

力量训练是 Cortex 当前提供的八类训练之一。大多数阻力训练模式都遵循相同流程：连接设备、完成配置、运行 load、运行 unload，最后通过 finish-training 结束训练。划船和滑雪模式有所不同：相应的 *-start 命令会直接开始距离训练，再通过 finish-training 结束。

模式	设置命令	后续配置
力量训练模式	set-mode weight-training	set-weight，以及上文列出的阻力调节命令
弹力带模式	set-mode resistance-band	set-resistance-band 15 –unit lbs
阻尼模式	set-mode damper	set-damper 5
等速模式	set-mode isokinetic	set-isokinetic-speed 0.5
等长模式	set-mode isometric	先运行 check-cable-zero，再运行 load
自定义阻力曲线	custom-curve apply <id>	见下文说明
划船模式	rowing-start <metres>	–resistance 1..10、–wear-level 1..10
滑雪模式	skiing-start <metres>	–resistance 1..10

其中几种模式需要额外说明：

使用等长模式前，需要先运行 voltra check-cable-zero，确认缆绳已完全回收到零位，然后才能对缆绳施力。官方文档明确指出，目前 CLI 对这项模式的支持尚不完整：CLI 可以启动测试，但测试结果会显示在设备和 App 中，不会显示在终端中。

划船模式有三种启动方式：一步启动，例如 voltra rowing-start 500 –resistance 5 –wear-level 3，同时设置模式和距离；两步启动，先设置模式及参数，再启动距离训练；或者不限距离地开始训练，例如 voltra rowing-start just-row –resistance 5。

自定义阻力曲线属于 Professional 版本功能，可用于设定整个动作幅度中的阻力变化。大多数相关命令——list、validate、encode、create、update 和 delete——通过云端执行，不需要连接设备。只有 voltra custom-curve apply <id> 会直接作用于 VOLTRA；应用曲线后，设备会进入 Professional 模式。

查看训练记录

这部分功能不依赖蓝牙，也是许多用户使用 Cortex 的主要目的。

voltra workout list                              # 查看训练记录，按时间从新到旧排列

voltra workout sets <workout-id>                # 查看某次训练中的所有组

voltra workout reps <workout-id> <set-id>       # 查看某一组中的每次重复

voltra workout aggregate-sets                   # 查看按组汇总的数据

voltra workout aggregate-reps                   # 查看按次数汇总的数据

查询时，将上一层级返回的 ID 传入下一条命令，即可逐层查看数据。次数层级包含速度衰减、峰值功率及单次做功等指标，可用于分析一组训练中的输出变化。

编写查询前，请记住以下四项限制，以免返回的数据不完整：

• 每页最多返回 50 次训练；
• 每次请求的日期跨度最长为 365 天；
• 日期必须采用 ISO 8601 格式，例如 2026-07-30T00:00:00，并以 UTC 表示；
• 时间戳默认以 UTC 返回；添加 –local-《时代》周刊 后可转换为本地时间。

最后一点尤其容易造成日期偏差。在 UTC 负时区，深夜完成的训练可能会显示在下一个日历日，除非查询时指定本地时间。

如果只想检查 API Key 是否仍然有效，而不读取训练数据，可以运行：

voltra workout auth-check

Actions 与 Sessions

这两个辅助目录可以帮助你理解训练数据中的编号。

Actions 是动作目录。每个动作都有一个数字形式的 actionId，并会出现在训练计划模板和训练记录中。例如，JSON 中的 actionId 33 代表“Free Exercises”。可以通过 voltra actions list、voltra actions types（身体部位分类）、voltra actions groups 或 voltra actions get <id> 浏览动作。使用 voltra actions create 还可以创建自定义动作，每个账户最多可创建 200 个。

Sessions 是保存在 Beyond+ 账户中的训练计划模板。相关命令包括：voltra session list、session detail <id>、session create –from <file.json>、session update、session rename 和 session delete <id> –yes。创建模板需要编写 JSON 文件——这类结构化工作正适合交给 AI 助手处理。

需要再次强调：这里管理的只是模板。实际执行训练计划仍需使用 Beyond+ App。

Skills、更新与 AI

“AI Agent Kit”中的“Agent Kit”是一组 Skills，也就是用于指导 AI 助手正确使用 VOLTRA CLI 的封装式说明。安装程序内置了多项 Skill，涵盖入门、设备状态、设备训练、训练模式、训练数据及 CLI 故障排查等内容。

voltra skills list

voltra skills add

voltra skills remove

voltra skills update

Skills 会安装到指定的 Agent 环境。文档列出了 claude、pi、openclaw 和 hermes，官网还提到 Codex、Gemini 和 Cursor。

这些工具有一个共同点：它们都运行在你的电脑上，并有权调用其他本地程序。这并非巧合，而是使用 Cortex 的必要条件。voltra skills add 会把说明文件复制到电脑上的特定文件夹，供本地 Agent 读取；网页端没有可以安装这些文件的位置。

这也从另一个角度说明了本文开头提到的限制：Skill 是保存在本地硬盘上的文件，只有能够读取本地文件的工具才能使用。浏览器标签页和手机 App 无法读取。如果你的 AI 助手只运行在这些环境中，可以直接跳到本文最后一节。

保持 Cortex 为最新版本：

voltra update

该命令会检查是否有新版 CLI 和 Skills，通过 SHA-256 校验和验证下载文件，停止正在运行的相关进程，然后替换可执行文件。Cortex 大约每天还会在后台检查一次更新。Beta 阶段建议主动定期运行此命令。

常见问题排查

可按以下顺序排查常见问题：

• 出现 voltra: command not found：关闭终端并重新打开。如果仍然无效，可在 ~/.voltra/bin/voltra 查找可执行文件。
• scan 找不到设备：检查蓝牙是否关闭、VOLTRA 是否处于休眠状态，或 Beyond+ App 是否仍占用连接。VOLTRA 同一时间只能连接一个设备。
• set-mode 无法执行：先运行 voltra unload。设备加载阻力时不能切换模式。
• load 无法执行：查看错误信息。常见原因包括尚未确认物理风险、尚未选择训练模式，或缆绳没有完全回收。
• 命令提示 API Key 无效：运行 voltra whoami 检查，再通过 voltra config set-api-key 重新保存。
• 其他问题：先运行 voltra doctor，再运行 voltra update。

或者：完全跳过终端

如果你习惯使用命令行，Cortex 可以提供直接的硬件控制、次数级训练数据，并通过各命令的 –json 参数让 AI 助手调用这些功能。

但很多人在问“如何使用 Cortex”时，真正想解决的是两个问题之一：如何把 VOLTRA 数据放到便于使用的地方，或者如何让 AI 参与训练。按照本文作者的介绍，这两件事也可以通过 Eccentric App 完成，无需使用终端。

• 一次连接，无需 CLI。在“Settings → Beyond Power”中粘贴原本提供给 Cortex 命令行的 API Key，即可完成设置。之后，VOLTRA 训练记录会自动同步，无需运行 workout list、处理 JSON 或手动设置日期格式。
• 使用托管 MCP 服务器，而非本地服务器。Eccentric 负责运行 MCP 服务器，AI 助手连接的是托管服务，而不是硬盘上的本地程序。因此，浏览器中的 Claude、Claude 和 ChatGPT 手机 App，以及其他电脑都可以访问。无需安装终端工具，也不受 VOLTRA 蓝牙距离限制。
• 权限限定在你的账户内，并可随时撤销。连接权限仅限于你的账户及 App 中本来就能执行的操作。AI 可以读取此前训练并提出后续计划调整建议；相关修改会以建议形式逐项呈现，由你决定接受或拒绝。
• 将 VOLTRA 数据与其他训练放在一起。除 VOLTRA 训练外，Eccentric 还可以集中记录杠铃、哑铃和自重训练，便于在同一份历史记录中综合查看。
• 训练计划也可以反向同步。你可以在 Eccentric 中编写训练计划，再发送到 Beyond+，到达设备旁时即可调用。

作者在《如何将 Eccentric 与 VOLTRA 配合使用》中介绍了完整流程；《使用 AI 规划、记录和优化训练》则展示了其日常使用的“计划—反馈—调整”过程。

如果你希望直接控制硬件、习惯使用终端，并且 AI 助手就运行在 VOLTRA 旁边的电脑上，可以选择 Cortex。如果你更希望通过手机、浏览器或其他电脑随时调用训练数据和 AI 助手，则可以了解 Eccentric。两者读取的是同一台设备，也使用同一个 API Key。