此页面由 AI 自动翻译。查看英文原版
最后更新

本页目录

  • 安装
  • 更新
  • USB 互联网共享
  • 启用
  • 禁用
  • 用法
  • 连接到设备
  • 查找设备
  • 应用程序开发
  • 检查正在运行的应用程序
  • 应用程序管理
  • Hub 连接
  • 设备管理
  • oak-agent
  • 容器
  • oakctl 和 oak-agent 的发布说明
  • oakctl v0.30.1 (2026 年 9 月 3 日)
  • agent v0.27.1 (2026 年 9 月 3 日)
  • oakctl v0.29.1 (2026 年 8 月 26 日)
  • oakctl v0.29.0 (2026 年 8 月 25 日)
  • oakctl v0.28.0 (2026 年 8 月 20 日)
  • oakctl v0.27.3 (2026 年 8 月 12 日)
  • oakctl v0.27.2 (2026 年 8 月 11 日)
  • oakctl v0.27.1 (2026 年 8 月 3 日)
  • oakctl v0.27.0 (2026 年 7 月 30 日)
  • agent v0.25.0 (2026 年 7 月 15 日)
  • agent v0.23.0 (2026 年 6 月 17 日)
  • agent v0.22.1 (2026 年 6 月 2 日)
  • oakctl v0.23.0 (2026 年 5 月 29 日)
  • oakctl v0.22.0 (2026 年 5 月 21 日)
  • agent v0.20.0 (2026 年 5 月 7 日)
  • agent v0.19.1, oakctl v0.20.0 (2026 年 5 月 5 日)
  • agent v0.18.6, oakctl v0.18.6 (2026 年 4 月 8 日)
  • agent v0.18.3, oakctl v0.18.2 (2026 年 2 月 17 日)
  • agent v0.17.4, oakctl v0.17.4 (2026 年 1 月 15 日)
  • oakctl v0.16.5 (2025 年 12 月 15 日)
Claude CodeCodexCursor
Luxonis 智能体工具包为你常用的编程智能体加载 Luxonis 上下文与技能,更快地基于 OAK 开发应用。
安装工具包

oakctl 工具

最后更新
oakctl 是一个命令行工具,允许您与 OAK4 摄像头交互。它可用于创建、部署和管理运行 oak-agent 服务并位于本地网络中的应用程序和设备。
请注意,oak-agent 已预装在 OAK4 设备上(它内置于 Luxonis OS 中),因此您可以立即开始使用 oakctl。

安装

Linux/MacOS

在 64 位系统上,运行:
Command Line
1bash -c "$(curl -fsSL https://oakctl-releases.luxonis.com/oakctl-installer.sh)"

Windows

使用 Windows 安装程序 下载并安装。

更新

您可以稍后像这样更新 oakctl 工具:
Command Line
1oakctl self-update

USB 互联网共享

如果您的 OAK4 通过 USB 连接并需要访问互联网,您可以使用 oakctl usbd 将主机计算机的互联网连接共享给设备。这对于 oakctl app run、oakctl app build、使用 hub、更新设备操作系统以及任何其他需要互联网连接的工作流都很有用。启用后,oakctl-usbd 后台服务会监视受支持的 OAK USB 以太网接口,并自动配置主机端网络,包括接口寻址、IP 转发和 NAT。在 Linux 上,它还会安装一个 udev 规则,以便 NetworkManager 和 systemd-networkd 不会控制 OAK4 USB 以太网接口。oakctl usbd 是可选的,默认禁用。

启用 oakctl usbd

Command Line
1oakctl usbd enable
这会在需要时安装服务,启用并启动它。该命令需要提升的权限,因此 oakctl 可能会提示管理员或 root 访问权限。您可以检查服务是否已启用并查看连接设备的共享状态:
Command Line
1oakctl usbd status

禁用 oakctl usbd

Command Line
1oakctl usbd disable
这会停止服务并禁用它。

用法

连接到设备

如果网络中只有一个设备可用,您可以使用以下命令连接到它:
Command Line
1oakctl connect
如果您有多个设备或设备不在与您的 PC 相同的网络中,您可以指定设备的 IPv4 地址来连接到它:
Command Line
1oakctl connect 10.0.1.24
或者,您可以使用 --with-password 标志存储设备的密码。这将防止您在会话过期时每次都输入密码。可以使用 oakctl device connection get 检查设备连接,或使用 oakctl device connection unset 清除连接。

查找设备

oakctl 允许您与安装了 oak-agent 的设备进行交互。您可以使用以下命令列出所有可用设备(在您的网络中找到):
Command Line
1oakctl list
2+---+---------------+---------------+------------+----------------+---------------+-------+
3| # | Serial Number | Device        | Connection | OS             | Agent Version | Setup |
4+=========================================================================================+
5| 1 | 1623452492    | Luxonis, Inc. | 10.0.1.24  | OS RVC4 1.18.0 | 0.13.7        | OK    |
6|   |               |  OAK4-D R7    |            |                |               |       |
7+---+---------------+---------------+------------+----------------+---------------+-------+

应用程序开发

您可以使用以下命令运行应用程序:
Command Line
1oakctl app run /app/path/to/source
默认情况下,oakctl app run 使用提供的应用程序目录中的 oakapp.toml。使用 --oakapp-file 选择备用配置文件(例如 oakapp.dev.toml 或 oakapp.prod.toml),只要该文件位于同一应用程序目录树中即可。

可选标志:

标志描述
-b, --detach在分离模式下运行应用程序。您可以使用 oakctl app stop <APP_ID> 停止它。
-d, --device [<DEVICE>]使用 IP、IP:PORT、索引或 oakctl list 中的序列号指定设备。
-i, --invalidate使缓存失效并强制重新构建。
-e, --env <KEY=VALUE>将运行时环境变量导出到应用程序(可多次提供)。
--env-file <FILE>从 .env 文件导出运行时环境变量。
--oakapp-file [<PATH>]使用提供的应用程序目录树中的备用 oakapp.toml 文件(例如 dev/prod 变体)。
--preserve-line-endings在将文件上传到设备之前禁用自动 CRLF 到 LF 转换。

示例应用程序

我们准备了 示例应用程序,您可以在 OAK4 设备上运行它们。下面我们将使用 人体姿态检测 示例,其中还包含 oakapp.toml:
Command Line
1git clone https://github.com/luxonis/oak-examples.git
2cd oak-examples
3# 运行一个应用程序
4oakctl app run ./neural-networks/pose-estimation/human-pose # 或其他示例

环境变量

您可以使用 -e, --env 标志或 --env-file 标志将环境变量传递给应用程序。这些变量将在应用程序的运行时环境中可用,可用于配置应用程序而无需更改代码。
Command Line
1oakctl app run ./app/path --env KEY1=VALUE1 --env KEY2=VALUE2
某些应用程序可能需要在构建时设置特定的环境变量(例如 API 密钥、模型下载链接等)。在这种情况下,您可以使用 build_env 字段在 oakapp.toml 文件中设置这些变量,或者在构建时使用 --build-arg 标志传递它们:
Command Line
1oakctl app build ./app/path --build-arg KEY1=VALUE1 --build-arg KEY2=VALUE
默认情况下,每个应用程序中都会设置一些环境变量:
变量描述
OAKAGENT_APP_ID唯一的应用程序 ID。
OAKAGENT_CONTAINER_ID容器 ID(如果应用程序已更新,可能与应用程序 ID 不同)。
OAKAGENT_APP_IDENTIFIERoakapp.toml 中的应用程序标识符。
OAKAGENT_APP_VERSIONoakapp.toml 中的应用程序版本。
DEPTHAI_CACHE_DIRDepthAI 缓存目录的路径;最好不要手动修改。
DEPTHAI_ZOO_MODELS_PATHDepthAI Zoo 模型目录的路径;根据 oakapp.toml 中的 depthai_models 字段设置;最好不要手动修改。
DEPTHAI_ZOO_CACHE_PATHDepthAI Zoo 缓存目录的路径;用于缓存下载的模型;最好不要手动修改。
DEPTHAI_ZOO_INTERNET_CHECK启用模型下载的互联网连接检查;根据 oakapp.toml 中的 depthai_models 字段设置;最好不要手动修改。
DEPTHAI_DEVICE_NAME_LIST在所有 RVC4 设备上设置为 127.0.0.1,以确保独立应用程序仅使用它们正在运行的设备,即使同一网络中有多个设备。
OAKAPP_STATIC_FRONTEND_PATH应用程序静态前端文件的路径。
OAKAPP_STATIC_FRONTEND_PORT用于提供静态前端文件的端口。它设置为 9000-9128 范围,以避免与代理或其他应用程序使用的端口冲突。
OAKAGENT_STORAGE_APP应用程序特定的持久存储路径。
OAKAGENT_STORAGE_SHARED具有相同标识符的应用程序之间可访问的共享存储路径。
OAKAGENT_STORAGE_GLOBAL设备上的全局存储路径。

检查正在运行的应用程序

oakctl inspect 连接到正在运行的应用程序公开的 DepthAI RemoteConnection。它提供了一种快速方法来了解实时管道、检查其主题并捕获数据。
命令描述
oakctl inspect topics以 JSON 格式列出已发布的主题。
oakctl inspect pipeline以 JSON 格式打印完整的管道图。
oakctl inspect frames <topic> --count <count> --out <dir>将解码的图像帧保存为 PNG 文件。
oakctl inspect dump <topic> --count <count>以 JSONL 格式流式传输解码的主题消息。使用 --seconds <duration> 代替 --count 以捕获固定时间。
oakctl inspect snapshot --out <dir>捕获从每个已发布主题接收到的第一个样本。
使用 -d <device> 检查 OAK 设备上的应用程序:
Command Line
1oakctl inspect topics -d 1
如果没有 -d 或 --url,oakctl inspect 将连接到 ws://127.0.0.1:8765。只有在应用程序在该主题上发布其第一条消息后,才会发布主题。默认情况下,发现等待长达 10 秒;使用 --timeout <duration> 更改此设置。

应用程序管理

您可以在设备上安装多个应用程序。如果您正在开发应用程序,您可以与团队中的其他人共享编译后的应用程序。请确保一次只运行一个 DepthAI 应用程序。大多数应用程序管理命令都有可选标志 -d, --device <DEVICE> 来指定要运行命令的设备(IP 地址或 oakctl list 中的索引)。

列出已安装的应用程序

如果您已设置设备并在 Hub 中采用,您可能已安装一个应用程序 (com.luxonis.default)。
Command Line
1$ oakctl app list
2+---+--------+---------------------------+---------+-------------------+
3| E | App Id | Identifier                | Status  | Frontend URL      |
4+====================================================================================================+
5| * | f8da5  | com.luxonis.default:1.3.8 | running | 10.0.1.24:9000    |
6+---+--------+---------------------------+---------+-------------------+
如果应用程序已启用,则第一列 (E) 带有星号。任何应用程序都可以处于以下状态之一:installing、building、ready、starting、running、stopping、stopped、deleting、deleted、unknown。Ready 表示应用程序已安装并准备运行,但自代理启动以来尚未启动,而 stopped 表示应用程序已安装但未运行,它已被用户停止。

应用程序控制流程

控制应用程序的基本命令是 start、stop 和 uninstall。首先,让我们启动应用程序:
Command Line
1$ oakctl app start 612a745c-8d68-4264-a3d6-d06d14275ef5
2Starting app 612a745c-8d68-4264-a3d6-d06d14275ef5 ...
3  App has been started!
您还可以使用唯一的应用程序 ID 前缀:
Command Line
1$ oakctl app start 612a745c
现在,让我们读取应用程序日志 - 此命令将读取应用程序的日志并将其打印到控制台,因为它们已收到:
Command Line
1$ oakctl app logs <app-id>
2Reading logs ...
3  Press Ctrl+C to stop reading logs.
4  App output:
5    [2025-02-12T14:37:54Z] Hello cli 1 / Wed Feb 12 14:37:54 UTC 2025
或者,您可以使用 -n 标志指定要读取的先前行数:
Command Line
1oakctl app logs <app-id> -n 10
如果您只想要历史日志而不附加到实时输出,请使用:
Command Line
1oakctl app logs <app-id> --no-follow
现在您可以停止应用程序:
Command Line
1$ oakctl app stop 612a745c-8d68-4264-a3d6-d06d14275ef5
2Stopping app 612a745c-8d68-4264-a3d6-d06d14275ef5 ...
3  App has been stopped!
以下是您删除应用程序的方法:
Command Line
1$ oakctl app uninstall 612a745c-8d68-4264-a3d6-d06d14275ef5
2Deleting app 612a745c-8d68-4264-a3d6-d06d14275ef5 ...
3  App has been deleted!
任何应用程序都可以启用或禁用。如果应用程序已启用,它将在设备启动时自动启动。
Command Line
1oakctl app enable <app-id>
您还可以使用 disable 命令禁用应用程序:
Command Line
1oakctl app disable <app-id>
请注意,某些应用程序命令(例如 start、restart、stop、uninstall、enable 和 disable)支持 --all 标志(或简称 -a)而不是特定的应用程序 ID,以对设备上安装的所有应用程序执行其操作。要交互式地连接到设备上已运行的应用程序,请使用 exec 命令:
Command Line
1oakctl app exec <app-id> -i /bin/bash
这将在应用程序的容器内打开一个交互式 bash shell,允许您检查文件、进程和环境变量。

安装应用程序

应用程序可以在 Hub 的 OAK4 Apps 部分找到。 有些应用程序与团队共享,有些应用程序与您的团队或公共应用程序共享。默认情况下,新安装的应用程序会停止所有其他应用程序并启用并运行。您可以通过使用 --enable=false 或 --keep-others 标志来修改此行为。应用程序安装通过以下命令完成:
Command Line
1$ oakctl app install com-example-emotion_recognition_1-0-1.oakapp
2Sending data to agent ...
3  Data sent successfully!
4
5✔ Oakapp package built successfully.
6Installed app has ID: ddb8a884-d9e1-4779-a88b-c30d5d1e265f
7
8Start the app:  oakctl app start ddb8a884-d9e1-4779-a88b-c30d5d1e265f
应用程序可以从 *.oakapp 文件、从 Hub(通过标识符)或从 URL 安装。如果您想从 Hub 安装应用程序,请执行以下操作:
Command Line
1# 通过标识符安装应用程序
2oakctl app install -i com.example.app
如果应用程序在互联网上的某个位置,也可以通过 URL 安装应用程序:
Command Line
1# 通过 URL 安装应用程序
2oakctl app install -u https://example.com/app.oakapp

更新应用程序

应用程序更新可以使用 oakctl app install 命令执行。默认情况下,oakctl app install 尝试更新具有相同标识符的现有应用程序。使用 --force-new 标志安装新实例而不是更新(这对于自托管 oak-agent 很有用;Luxonis OS 不允许同时运行多个 DepthAI 应用程序)。如果多个应用程序共享相同的标识符,请使用 --update <APP_ID> 标志指定要更新的应用程序。更新过程遵循以下步骤:
  1. 新应用程序版本从 Hub、URL 或本地 *.oakapp 文件下载(取决于来源:-i、-u 或文件路径)。在此步骤中,当前版本保持运行。
  2. 一旦新版本下载并验证,当前版本停止,新版本启动。然后删除任何以前的回滚版本。
为了更好地控制,您可以手动执行更新:
  1. 暂存新版本:oakctl app install --manual-update 下载并准备新版本,而无需停止当前版本。使用 oakctl app list 验证准备情况。
  2. 提交更新:oakctl app update <APP_ID> --commit 停止当前版本并启动新版本。
  3. 如果需要,回滚:oakctl app update <APP_ID> --rollback 在出现问题时恢复到以前的版本。
  4. 准备就绪时完成:oakctl app update <APP_ID> --finalize 在您确认新版本稳定后删除为回滚保留的旧版本。

构建和发布应用程序

您可以构建自己的应用程序。该过程将生成 *.oakapp 文件,可以安装在其他设备上:
Command Line
1oakctl app build ./folder/app/src
默认情况下,oakctl app build 使用提供的应用程序目录中的 oakapp.toml。 使用 --oakapp-file 选择备用配置文件(例如 oakapp.dev.toml 或 oakapp.prod.toml),只要该文件位于同一应用程序目录树中即可。可选标志:
  • -d, --device [<DEVICE>] - 使用 IP、IP:PORT、索引或 oakctl list 中的序列号指定设备
  • -k, --keep - 构建后保留容器(如果您想在构建后立即 oakctl app start 它,则很有用)
  • -p, --publish - 构建后将应用程序发布到 Hub(应用程序将显示在 Hub 的 OAK4 Apps 中)。
  • -O, --optimized - 以优化模式构建应用程序(更小的尺寸,更长的构建时间)
  • -U, --update-description - 如果应用程序已发布,则更新 Hub 上的应用程序描述
  • -N, --no-download - 构建后不将 *.oakapp 文件下载到主机
  • -o, --output [<PATH>] - 构建的 *.oakapp 文件应下载到的目录路径
  • --oakapp-file [<PATH>] - 使用提供的应用程序目录树中的备用 oakapp.toml 文件
  • --preserve-line-endings - 在将文件上传到设备之前禁用自动 CRLF 到 LF 转换
如果您发布应用程序,您需要在 oakapp.toml 文件中指定应用程序的标识符和唯一版本。

Hub 连接

对于某些操作,您需要将设备连接到 Hub。您可以使用以下命令执行此操作:
Command Line
1oakctl hub login
登录后,您可以使用以下命令检查连接状态:
Command Line
1oakctl hub status
要更改活动团队,请再次运行 oakctl hub login 并在 Web 登录流程中选择团队。 oakctl hub switch-team 是 oakctl hub login 的别名。使用以下命令注销:
Command Line
1oakctl hub logout
登录后,您可以发布构建的 *.oakapp 包:
Command Line
1oakctl hub publish <oakapp-file>
您还可以运行需要 Hub 令牌才能下载模型等的本地脚本:
Command Line
1oakctl hub run-script <script-file>

设备管理

设备信息

设备信息命令将显示设备的详细信息,例如操作系统版本、代理版本、架构、序列号和型号。
Command Line
1$ oakctl device info
2Device Info:
3  OS:                   Luxonis OS RVC4 1.4.0
4  Agent Version:        2.0.11 (rvc4)
5  Architecture:         linux/arm64
6  Serial Number:        2713799968
7  Model:                Luxonis, Inc. KalamaP OAK4-D R1
使用 --check_internet 标志也可以检查互联网连接。

设备统计

使用 oakctl device stats 在开发、部署或故障排除应用程序时监视资源使用情况:
Command Line
1oakctl device stats
该报告将 CPU 使用率、SoC 温度、内存、功耗、文件系统使用率和网络活动整合到一个视图中。使用 --watch [<interval>] 进行持续监视,使用 --all 将每个文件系统包含在默认输出中,或使用 --format json 获取机器可读输出。在没有间隔的情况下运行 --watch 会每两秒刷新一次。某些指标(例如功耗数据)可能并非在每个平台上都可用。

设备更新

设备可以使用以下命令更新 - CHANNEL 的可能值为 stable 和 beta:
Command Line
1oakctl device update --channel=[CHANNEL]
此命令将检查最新的可用版本,如果版本不同,则更新设备。您可以使用 --select 标志选择要更新到的特定版本:
Command Line
1oakctl device update --select --channel=[CHANNEL]
或者,您可以使用 --url 或 --path 标志直接提供更新 URL 或本地文件的路径:
Command Line
1oakctl device update --url=[URL]
2oakctl device update --path=[PATH]
要在不将 OTA 更新包安装到设备上的情况下下载到主机,请指定目标目录:
Command Line
1oakctl device update --download <DIR>
更新命令仅在设备连接到互联网时有效。 如果您的设备未连接到互联网,可以使用 --local 标志将文件下载到本地计算机,然后在下载完成后将其传输到设备:
Command Line
1oakctl device update --local
要显示设备上记录的最新操作系统更新状态,请运行:
Command Line
1oakctl device update --status
状态命令不会启动更新,并且在自托管代理上不受支持。

设备重启

您可以使用 oakctl 重启设备:
Command Line
1oakctl device reboot
此命令将重启设备并等待其重新联机。

设备解锁

新设备默认禁用 SSH 访问。您可以使用以下命令启用它:
Command Line
1oakctl device unlock
此命令将提示您设置密码。

设备刷写

您可以使用以下命令将新 Luxonis OS 映像刷写到设备(仅限 USB):
Command Line
1oakctl device reflash [<path-to-tar.xz>]
*.tar.xz 映像的路径是可选的;如果未指定,将下载并刷写最新的稳定映像。有关详细的刷写和操作系统更新说明,请参阅 更新操作系统页面。要在不刷写设备的情况下下载完整的操作系统映像,请运行:
Command Line
1oakctl device reflash --download <DIR>

oak-agent

oak-agent 是在 OAK4 设备上运行并管理容器的服务。它负责:
  • 管理应用程序,运行容器;
  • 与 oakctl 工具通信;
  • 与 Hub(云平台)通信。

容器

oak-agent 使用 runc 作为轻量级容器运行时,这也是 Docker/Podman 使用的。 我们选择 runc 是因为它轻量级,并且可以完全控制容器生命周期。

oakctl 和 oak-agent 的发布说明

oakctl v0.30.1 (2026 年 9 月 3 日)

新增

  • 在 Windows 上,新增:oakctl usbd share-to <device|auto>,以便能够控制互联网共享到哪个设备。
  • oakctl device stats 以显示 CPU、内存、文件系统使用情况和其他有用的设备数据。
  • 为可能源于 [base_image] 部分位置不当的 oakapp.toml 解析错误添加了提示。
  • oakctl device update --status 以显示 agentconfd 记录的最新操作系统更新状态。

修复

  • Windows Home 上的 USB 互联网共享。
  • 通过 --env 标志传递的应用程序配置值保留 =。

更改

  • 扩展了 oakctl usbd status 以包含有关 oakctl-usbd 状态的更多详细信息。

agent v0.27.1 (2026 年 9 月 3 日)

新增

  • 通过 oakapp.toml 中的 restart_policy 字段支持应用程序自动重启。
  • 支持 oakctl device stats。

修复

  • 修复了设备启动时互联网无法访问时长时间的时间同步延迟。
  • WebRTC 稳定性改进。
  • 改进了在 oakctl app run/build 期间丢失与 oakctl 连接的内部处理。
  • 断电后“应用程序处于未知状态”(.process.pid 文件存在)。
  • 连续运行 oakctl app run 时出现 static-fe: no such file or directory 错误。
  • 运行 oakctl app run 时,通用 log detach 错误隐藏了构建错误。
  • 在编辑 oakapp.toml 中的 base_image 后,oakctl app run . 上出现 static-fe: no such file or directory 错误。
  • oakctl app install --update 后应用程序配置被删除。
  • oakctl app restart 现在将应用程序状态更改为 restarting,而不是 stopping 后跟 starting。

oakctl v0.29.1 (2026 年 8 月 26 日)

修复

  • oakctl Windows 安装程序错误:0x80070666。该错误可能由于 vc_redist 版本冲突而在某些计算机上发生。

oakctl v0.29.0 (2026 年 8 月 25 日)

新增

  • oakctl inspect 用于列出 DepthAI RemoteConnection 主题、打印管道图并从正在运行的 DepthAI 应用程序捕获帧或快照。

oakctl v0.28.0 (2026 年 8 月 20 日)

新增

  • oakctl device update 和 oakctl device reflash 的 --download <DIR> 参数,允许您将更新包下载到计算机而无需刷写。

oakctl v0.27.3 (2026 年 8 月 12 日)

修复

  • oakctl self-update:当 oakctl-usbd 启用时,资源繁忙错误。

oakctl v0.27.2 (2026 年 8 月 11 日)

修复

  • Windows 上的 oakctl 签名。

更改

  • 使用旧代理时,使用新 base_image 语法时出现更好的错误消息。

oakctl v0.27.1 (2026 年 8 月 3 日)

修复

  • oakctl 初始化时发生恐慌。

oakctl v0.27.0 (2026 年 7 月 30 日)

新增

  • oakctl device setup apply 和 oakctl device setup apply-b64 命令中的 Wi-Fi 配置支持。
  • oakctl registry login 和 oakctl registry logout 用于向容器注册表进行身份验证。这支持私有镜像拉取并有助于避免未经身份验证的拉取速率限制。
  • oakctl app uninstall、start、stop、restart、enable 和 disable 的 --all 标志。
  • oakctl device sahara enable|disable 用于在设备上启用或禁用 Sahara。
  • oakctl device uart enable|disable 用于通过 UART 启用或禁用 Linux 内核日志和登录 shell。
  • 许可证和第三方许可证通知分发。

修复

  • 修复了已更新应用程序的 oakctl app prune-storage。
  • 修复了配置默认路由但互联网无法访问时,启动 oakctl 命令的长时间延迟。
  • 修复了运行 oakctl app prune-storage 时的超时。
  • 修复了应用程序挂载 /dev 时 oakctl app exec -i。
  • 改进了通过 USB 连接但无法通过网络访问的设备的 oakctl list 输出。
  • Windows 11 上的 oakctl device reflash。

agent v0.25.0 (2026 年 7 月 15 日)

新增

  • 新的私有 HTTP API 端点 (device-reboot、app-stop、app-restart)。
  • 支持:oakctl device sahara enable|disable 用于在设备上启用或禁用 Sahara。
  • 支持 oakctl device uart enable|disable 用于在 UART 上启用或禁用 linux 内核日志和登录 shell。
  • 持久日志:
    • 使用 journald 记录 oakapp 输出。
    • 能够将应用程序日志摄取到 hub。
  • 许可证通知。
  • 为设备设置添加了 wifi 支持。
  • 支持 oakctl app uninstall、start、stop、restart、enable、disable 上的 --all 标志。

修复

  • 修复了 app prune-storage 超时。

agent v0.23.0 (2026 年 6 月 17 日)

更改

  • 应用程序关闭:应用程序现在通过向应用程序进程发送 SIGTERM 并等待其退出而优雅地停止,而不是立即强制终止容器。这允许应用程序在关闭期间执行清理。

修复

  • 修复了在无法检索 Hub 服务 URL 时部分设备设置状态。
  • oakctl app prune storage 用于已更新的应用程序。

agent v0.22.1 (2026 年 6 月 2 日)

新增

  • 将已删除的容器删除到 oakctl app prune-storage。

oakctl v0.23.0 (2026 年 5 月 29 日)

新增

  • 为 oakctl 添加了分析。可以使用 OAKCTL_ANALYTICS=0 环境变量禁用分析。

更改

  • 删除了 oakctl app install --update 上的弃用通知。

oakctl v0.22.0 (2026 年 5 月 21 日)

新增

  • oakctl app examples list 以显示可用的 OAK 应用程序示例,以及 oakctl app examples clone <path> 以在本地下载 oak-examples 存储库。
  • 通过 oakctl usbd 支持 USB 互联网共享。
    • 添加了 oakctl-usbd 后台服务,通过 USB 与 OAK 设备共享主机的互联网连接。
    • 添加了 oakctl usbd <status|enable|disable> 以管理 oakctl-usbd 服务。

更改

  • 删除了 oakctl list、oakctl connect、oakctl setup、oakctl setup-b64 和 oakctl start-setup 的弃用通知。
  • 使 oakctl list 和 oakctl connect 在帮助输出中再次可见。

agent v0.20.0 (2026 年 5 月 7 日)

新增

  • USB 互联网共享支持。

agent v0.19.1, oakctl v0.20.0 (2026 年 5 月 5 日)

修复

  • oakctl adb 有时会以代码 255 退出,即使 adb 命令成功。
  • oakctl 在运行 self-update 时不再显示新版本可用提示。

新增

  • oakctl device update --url/--path 用于从 URL 或本地文件更新 RVC 设备操作系统。
  • oakctl device update --local 用于在本地下载操作系统更新。
  • oakctl device connection get|unset 用于在使用 oakctl connect 后检查或清除当前设备连接。

更改

  • oakctl CLI 一致性:
    • oakctl list 已移至 oakctl device list(旧命令已隐藏并显示弃用通知)。
    • oakctl connect 已移至 oakctl device connection set(旧命令已隐藏并显示弃用通知)。
    • oakctl start-setup 已移至 oakctl device setup start(旧命令已隐藏并显示弃用通知)。
    • oakctl setup 已移至 oakctl device setup apply(旧命令已隐藏并显示弃用通知)。
    • oakctl device flash 已重命名为 oakctl device reflash(旧命令已隐藏并显示弃用通知)。
    • oakctl app delete 已重命名为 oakctl app uninstall(旧命令已隐藏并显示弃用通知)。
    • oakctl hub publish 已移至 oakctl app publish(旧命令已隐藏并显示弃用通知)。
    • oakctl app config <app_id> set|get 已重构为 oakctl app config set|get <app_id>。
    • oakctl setup-b64 已移至 oakctl device setup apply-b64(旧命令已隐藏并显示弃用通知)。
  • 扩展了所有 oakctl 的 --help 输出。帮助现在包括示例命令和核心概念的简短解释。

agent v0.18.6, oakctl v0.18.6 (2026 年 4 月 8 日)

新增

  • oakctl app install 现在在安装后删除不必要的文件以节省存储空间。
  • oakctl app prune-storage 现在也删除安装和下载文件。
  • oakctl app delete 现在也删除格式错误的应用程序。
  • oakctl device info 现在显示:
    • 日期
    • 网络信息
    • 用于下载构建应用程序的 HTTP API 端口
  • oakctl app run 如果命令在构建步骤中失败,则不再重新构建整个应用程序;它保留成功构建的层。
  • 新的 oakapp.toml 定义:
    • 添加了 shell 字段以指定 RUN 命令、build_steps 和 entrypoint 的默认 shell(默认值:["/bin/sh", "-c"])。
    • 命令现在可以以 shell 形式(字符串)或 exec 形式(字符串数组)编写。
    • 删除了基于 shlex 的解析,因为它不支持重定向和管道等构造。
    • 为构建时环境变量添加了可选的 arg 部分,并为 oakctl app build 和 oakctl app run 添加了 --build-arg 标志。
    • 为仅在构建阶段使用的挂载添加了可选的 additional_build_mounts 部分。
  • 所有 Hub 服务端点现在都可以通过 API 配置。
    • 在 oakctl 中使用 OAKCTL_HUB_API_URL。
    • 在 oak-agent 的 setup-utility 配置中使用 api=。

更改

  • 将 oakctl 中选择 Hub 服务环境的环境变量从 ENV 重命名为 OAKCTL_ENV。

agent v0.18.3, oakctl v0.18.2 (2026 年 2 月 17 日)

新增

  • oakctl app build 和 oakctl app run 命令期间的图像下载进度报告。
  • 自托管代理的 GPU 支持,如果启用,允许 oak 应用程序使用主机的 Nvidia GPU。
  • oakctl app [build|run] --oakapp-file [PATH] 参数,用于指定 oakapp.toml 文件的自定义路径。
  • oakctl app logs --no-follow 参数,用于避免附加到日志流。
  • 从 Luxonis Hub 远程执行命令。
  • 将 oakctl setup 的 --*-b64 参数替换为新的子命令 oakctl setup-b64。
  • 拒绝 oakapp.toml 挂载字段中的相对路径:required_mounts、required_devices、optional_mounts、optional_devices、additional_mounts。
  • oakctl device update 支持自托管 oak-agent。

修复

  • oakctl app build 在尝试使用具有许多层(约 30 层)的基础映像时出现 Failed to mount overlayfs 错误。
  • jetson 上的 oakctl adb。
  • 将 QDL udev 规则的安装添加到 oakctl self-update。
    • 修复了 oakctl device flash 期间的某些 qdl: Failed to open device 实例。
  • 编辑 oakapp.toml 后,第二次应用程序运行容器中缺少 /etc/resolv.conf。

agent v0.17.4, oakctl v0.17.4 (2026 年 1 月 15 日)

新增

  • oakctl app build --output [PATH] 参数,用于指示构建后将 *.oakapp 文件下载到何处。
  • oakctl setup 命令的 Base64 编码参数,以确保 Hub 生成的设置命令的特殊字符的跨操作系统兼容转义。
  • 每天自动检查一次新的 oakctl 版本。
  • oakctl app prune-storage 命令,用于删除不必要的应用程序文件。
  • oakctl app list --long 标志,用于显示完整的应用程序 ID。
  • oak-agent 测试 WebRTC 连接。
  • oakctl device info 和 oakctl list 显示采用状态。
  • 欢迎 ACK 出厂重置支持。
  • oakctl app install 默认更新现有应用程序。
    • 可以使用 --force-new 标志修改为安装为新应用程序。
    • 可以使用 --update 标志修改为更新特定的现有应用程序。
  • oakctl app install --env / --env-file 用于在应用程序安装期间设置环境变量。
  • 多平台自托管 Docker 映像。

更改

  • oakctl app list 现在默认显示截断为 3 个字符的应用程序 ID;当发生冲突时,截断会自动增加。
  • oak-agent 保存新的应用程序构建元数据。
  • 自托管 WebRTC 终端打开主机 shell 而不是容器 shell。
  • oakctl app <ACTION> <app-id> 命令现在接受完整和截断的应用程序 ID。

修复

  • 修复了在单个读取中接收到多条消息时 OTA 更新状态反序列化失败的问题。
  • Windows 上的 oakctl 自动将 CRLF 转换为 LF。
  • 自托管 oak-agent/oakctl 修复:
    • 修复了 oakctl device info --check_internet
    • 修复了 oakctl device reboot
    • 修复了 oakctl setup 命令(在 RPi 等某些设备上失败)
    • 缺少 ARM 设备的 adb 二进制文件(错误地包含了 x86 二进制文件)
  • 修复了使用 OAKCTL_HUB_TOKEN 的应用程序发布上传。
  • macOS ARM 和 Windows 的 oakctl 构建未签名。
  • 修复了 oak-agent 的构建缓存失效。
  • 修复了 oakctl 未正确保存和/或读取 sn-data.json 的问题。

弃用

  • OAKCTL_HUB_LOGIN_TOKEN 环境变量重命名为 OAKCTL_HUB_TOKEN。
  • oakctl hub switch-team 现在是 oakctl hub login 的别名(团队在 Web 登录流程中选择)。
  • --enabled 标志从 -e 重命名为 -E。

oakctl v0.16.5 (2025 年 12 月 15 日)

新增

  • 非交互式 oakctl device update 的新标志 --yes。
  • oakctl device update 的新标志 --check_internet,用于在更新前检查互联网连接。
  • oakctl viewer 命令已启用,用于打开 Viewer。
  • oakctl app build 的新标志 --no-download,用于跳过将构建的 *.oakapp 文件下载到主机;对测试很有用。
  • oakctl app start 的新标志 --enable 和 --disable-others。

更改

  • oakctl hub login 现在使用基于 Web 的身份验证流程。
  • 对集成到 Viewer 的次要改进。