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

本页目录

  • 安装
  • 更新
  • 用法
  • 连接到设备
  • 查找设备
  • 应用开发
  • 应用管理
  • Hub 连接
  • 设备管理
  • oak-agent
  • 容器
  • oakctl 和 oak-agent 的发行说明
  • 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 日)

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

用法

连接到设备

如果网络中只有一个可用设备,您可以使用以下命令连接到它:
Command Line
1oakctl connect
如果您有多个设备,或者设备不在您 PC 的同一网络中,您可以指定设备的 IPv4 地址进行连接:
Command Line
1oakctl connect 10.0.1.24
可选地,您可以使用 --with-password 标志存储设备的密码。这样可以避免每次会话过期时都输入密码。

查找设备

oakctl 允许您与安装了 oak-agent 的设备进行交互。您可以使用以下命令列出所有可用设备(在您的网络中找到):
Command Line
1oakctl list
2+---+---------------+---------------+------------+----------------+---------------+-------+
3| # | 序列号        | 设备          | 连接       | 操作系统       | Agent 版本    | 设置  |
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.tomloakapp.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 文件(例如开发/生产变体)。
--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_IDENTIFIER来自 oakapp.toml 的应用标识符。
OAKAGENT_APP_VERSION来自 oakapp.toml 的应用版本。
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设备上的全局存储路径。

应用管理

您可以在设备上安装多个应用。如果您正在开发一个应用,可以在团队内部与其他成员共享编译好的应用。请确保一次只运行一个 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 表示应用已安装但未运行,已被用户停止。

应用控制流程

控制应用的命令是 startstopdelete。首先,我们来启动应用
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 delete 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>
要交互式地连接到设备上已运行的应用,请使用 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# Install app by identifier
2oakctl app install -i com.example.app
如果应用在互联网上的某个位置,还可以选择通过 URL 安装应用:
Command Line
1# Install app by 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.tomloakapp.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-teamoakctl 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 标志还可以检查互联网连接。

设备更新

可以使用以下命令更新设备 - CHANNEL 的可能值为 stablebeta
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]
更新命令仅在设备连接到互联网时才有效。 如果您的设备未连接,可以使用 --local 标志在本地计算机上下载文件,然后在下载完成后将其传输到设备:
Command Line
1oakctl device update --local
--local 标志也可以与其他标志结合使用。

设备重启

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

设备解锁

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

设备刷写

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

oak-agent

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

容器

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

oakctl 和 oak-agent 的发行说明

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_stepsentrypoint 的默认 shell(默认值:["/bin/sh", "-c"])。
    • 命令现在可以以 shell 形式(字符串)或 exec 形式(字符串数组)编写。
    • 移除了 shlex 解析,因为它不支持重定向和管道等构造。
    • 添加了可选的 arg 部分,用于构建时环境变量和 oakctl app buildoakctl 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 buildoakctl 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_mountsrequired_devicesoptional_mountsoptional_devicesadditional_mounts
  • oakctl device update 支持自托管 oak-agent。

修复

  • 在尝试使用具有许多层(约 30 个)的基础镜像时,oakctl app build 出现 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 infooakctl 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 的集成进行了小的改进。