oakctl 工具
最后更新
oakctl 是一个命令行工具,允许您与 OAK4 摄像头交互。它可用于创建、部署和管理运行 oak-agent 服务并位于本地网络中的应用程序和设备。
oakctl。安装
Linux/MacOS
在 64 位系统上,运行:
Command Line
1bash -c "$(curl -fsSL https://oakctl-releases.luxonis.com/oakctl-installer.sh)"更新
oakctl 工具:Command Line
1oakctl self-updateWindows 上更新问题
如果您在 Windows 上更新 oakctl 版本时遇到问题,请从 此处下载安装程序。
USB 互联网共享
版本说明
USB 互联网共享需要
oakctl v0.22.0 和 Luxonis OS 1.32.0 或更高版本。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 enableoakctl 可能会提示管理员或 root 访问权限。Windows 限制
在 Windows 上,
oakctl-usbd 只能同时与一个 OAK4 设备共享互联网。当连接多个设备时,使用 oakctl usbd status 查看选择了哪个设备,并使用 oakctl usbd share-to <device> 选择另一个设备。<device> 可以是设备序列号或 USB 位置,例如 usb:0-1.4。使用 oakctl usbd share-to auto 恢复自动选择。Command Line
1oakctl usbd status禁用 oakctl usbd
Command Line
1oakctl usbd disable用法
连接到设备
Command Line
1oakctl connectCommand 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/sourceoakctl 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 转换。 |
示例应用程序
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=VALUE2build_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_IDENTIFIER | oakapp.toml 中的应用程序标识符。 |
OAKAGENT_APP_VERSION | oakapp.toml 中的应用程序版本。 |
DEPTHAI_CACHE_DIR | DepthAI 缓存目录的路径;最好不要手动修改。 |
DEPTHAI_ZOO_MODELS_PATH | DepthAI Zoo 模型目录的路径;根据 oakapp.toml 中的 depthai_models 字段设置;最好不要手动修改。 |
DEPTHAI_ZOO_CACHE_PATH | DepthAI 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 | 设备上的全局存储路径。 |
持久存储
持久存储路径用于存储应在应用程序重启和更新后持久存在的数据。这些路径被挂载到应用程序的容器中。您可以使用
oakapp.toml 配置 (storage_dir_name) 在容器中选择存储的目标目录名称。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> 更改此设置。应用程序管理
-d, --device <DEVICE> 来指定要运行命令的设备(IP 地址或 oakctl list 中的索引)。列出已安装的应用程序
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 表示应用程序已安装但未运行,它已被用户停止。注意
为了提高可读性,应用程序 ID 在列表中被截断。如果存在多个具有相同前缀的应用程序,则截断长度会增加,直到所有应用程序 ID 都唯一。您还可以使用
--long 标志在列表中显示完整的应用程序 ID。所有应用程序控制命令都接受完整和截断的应用程序 ID,只要它们是唯一的。应用程序控制流程
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!Command Line
1$ oakctl app start 612a745cCommand 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 10Command Line
1oakctl app logs <app-id> --no-followCommand 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注意
修改容器内的文件或保存数据时要小心,因为当容器停止或移除时,更改可能会丢失。更好的方法是使用挂载(参见
oakapp.toml 配置)或由 OAK 代理管理的持久存储(参见 OAKAGENT_STORAGE_APP、OAKAGENT_STORAGE_SHARED、OAKAGENT_STORAGE_GLOBAL 环境变量)将主机设备中的持久文件夹挂载到容器中。安装应用程序
--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.appCommand 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> 标志指定要更新的应用程序。更新过程遵循以下步骤:- 新应用程序版本从 Hub、URL 或本地
*.oakapp文件下载(取决于来源:-i、-u或文件路径)。在此步骤中,当前版本保持运行。 - 一旦新版本下载并验证,当前版本停止,新版本启动。然后删除任何以前的回滚版本。
- 暂存新版本:
oakctl app install --manual-update下载并准备新版本,而无需停止当前版本。使用oakctl app list验证准备情况。 - 提交更新:
oakctl app update <APP_ID> --commit停止当前版本并启动新版本。 - 如果需要,回滚:
oakctl app update <APP_ID> --rollback在出现问题时恢复到以前的版本。 - 准备就绪时完成:
oakctl app update <APP_ID> --finalize在您确认新版本稳定后删除为回滚保留的旧版本。
构建和发布应用程序
*.oakapp 文件,可以安装在其他设备上:Command Line
1oakctl app build ./folder/app/srcoakctl 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 连接
Command Line
1oakctl hub loginCommand Line
1oakctl hub statusoakctl hub login 并在 Web 登录流程中选择团队。 oakctl hub switch-team 是 oakctl hub login 的别名。使用以下命令注销:Command Line
1oakctl hub logout*.oakapp 包:Command Line
1oakctl hub publish <oakapp-file>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--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]Command Line
1oakctl device update --download <DIR>--local 标志将文件下载到本地计算机,然后在下载完成后将其传输到设备:Command Line
1oakctl device update --localCommand Line
1oakctl device update --status设备重启
oakctl 重启设备:Command Line
1oakctl device reboot设备解锁
Command Line
1oakctl device unlock设备刷写
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 appuninstall、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后检查或清除当前设备连接。
更改
oakctlCLI 一致性: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 的次要改进。