系统进程运行时

worker-sys 直接以宿主机 OS 进程执行代码，不经过任何容器隔离。适用于需要直接控制真实设备或主机资源的场景。

当前版本 worker-sys 的能力和程序实现已经完备。但考虑到其危险性，我们将不会在短期内将其标注为生产就绪。

适用场景

• 需要直接访问宿主机硬件或外设
• 容器开销不可接受
• 运行在专用的可信机器上
• OpenClaw like 场景

警告： worker-sys 不提供任何沙箱隔离。终端命令直接在宿主机上执行。仅在专用的机器上运行。

工作原理

1. Worker 通过 gRPC 连接控制节点。
2. 执行请求被作为原生 OS 进程在宿主机上启动。
3. 进程的 stdout/stderr 通过控制面流式返回。

一个账号可以配置多个 worker-sys。公开 computerUse 调用通过 worker_id 选择其中一个；省略时列出当前账号全部实例及其在线/离线状态。公开 readImage 与 exportFile 使用 CU:<worker_id>。Console 会校验归属和类型，将执行固定投递到该 Worker 且不回退，并把公开 session ID 转换为 worker-sys 所理解的内部 session_id="computerUse"。

Shell 选择（跨平台）

computerUse 通过宿主机的系统 shell 执行命令，shell 按平台自动选择：

• Linux / macOS：/bin/sh -lc <command>
• Windows：powershell.exe -NoProfile -NonInteractive -ExecutionPolicy Bypass -Command <command>，并自动注入 [Console]::OutputEncoding 与 $OutputEncoding 为 UTF-8，避免在中文系统上被 GBK 代码页截断为乱码。

部署 Windows worker 时，WORKER_COMPUTER_USE_COMMAND_WHITELIST 中的条目必须是 PowerShell 形态（如 Get-ChildItem、Get-Process），不能直接使用 ls、cat 等 Unix 命令——白名单是按字符串前缀/精确匹配的，与所在平台的 shell 必须一致。

前置条件

• 能够访问控制节点 gRPC 端口
• 工作负载所需的 OS 级别权限

启动 worker

从 GitHub Releases 页面 下载最新的 worker-sys 二进制文件，然后运行：

WORKER_CONSOLE_GRPC_TARGET=<console_grpc_target> \
WORKER_ID=<worker_id> \
WORKER_SECRET=<worker_secret> \
./onlyboxes-worker-sys

通过非 TLS 连接时请设置 WORKER_CONSOLE_INSECURE=true。

Windows / PowerShell 启动示例：

$env:WORKER_CONSOLE_GRPC_TARGET = "<console_grpc_target>"
$env:WORKER_ID = "<worker_id>"
$env:WORKER_SECRET = "<worker_secret>"
.\onlyboxes-worker-sys.exe

配置文件

Dashboard 中的 Worker 启动工具可以生成并下载可直接使用的 config.toml。设置 WORKER_CONFIG_FILE 可以显式指定配置文件；未设置时，worker 会依次查找程序文件同目录和当前工作目录下的 config.toml。

配置优先级为：环境变量 > config.toml > 内置默认值。TOML 键名由环境变量名移除 WORKER_ 前缀并转换为小写得到；数组使用 TOML 原生数组，Worker 标签使用 [labels] 表配置。

id = "wk_..."
secret = "..."
console_grpc_target = "console.internal:50051"
computer_use_command_whitelist = ["echo", "time"]

[labels]
device = "lab-machine"

全部可用配置请参考带注释的配置模板。

环境变量

连接

身份

Computer use

并发上限

computerUse 与 readImage 使用相互独立的并发配额，因此一个进行中的 readImage 不会占用 computerUse 的 slot。超出对应能力的上限会返回 409 session_busy。

心跳

日志

相关文档

• 架构
• Docker 运行时
• Boxlite 运行时