export const meta = {
  title: '系统进程',
  description: '使用 worker-sys 以宿主机进程方式执行任务。',
  section: '运行时',
  order: 46,
  slug: 'worker-sys',
}

# 系统进程运行时

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

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

## 适用场景

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

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

## 工作原理

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

### 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 页面](https://github.com/Coooolfan/onlyboxes/releases/latest) 下载最新的 `worker-sys` 二进制文件，然后运行：

```bash
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 启动示例：

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

## 环境变量

### 连接

| 变量 | 必填 | 默认值 | 说明 |
| --- | --- | --- | --- |
| `WORKER_CONSOLE_GRPC_TARGET` | 否 | `127.0.0.1:50051` | 控制节点 gRPC 地址 |
| `WORKER_CONSOLE_INSECURE` | 否 | `false` | 设为 `true` 允许不安全的连接（非 TLS） |
| `WORKER_ID` | 是 | | Dashboard 中的 Worker ID |
| `WORKER_SECRET` | 是 | | 创建 worker 时的一次性密钥 |

### 身份

| 变量 | 必填 | 默认值 | 说明 |
| --- | --- | --- | --- |
| `WORKER_NODE_NAME` | 否 | | 可读的节点名称 |
| `WORKER_VERSION` | 否 | 构建版本 | 上报给控制节点的版本号 |
| `WORKER_LABELS` | 否 | | CSV 格式标签，如 `region=us,owner=team-a` |

### Computer use

| 变量 | 必填 | 默认值 | 说明 |
| --- | --- | --- | --- |
| `WORKER_COMPUTER_USE_OUTPUT_LIMIT_BYTES` | 否 | `1048576` | 每个流的输出上限（字节） |
| `WORKER_COMPUTER_USE_COMMAND_WHITELIST_MODE` | 否 | `exact` | `exact` / `prefix` / `allow_all` |
| `WORKER_COMPUTER_USE_COMMAND_WHITELIST` | 否 | `[]` | 允许执行的命令 JSON 数组，如 `'["echo","time"]'` |
| `WORKER_READ_IMAGE_ALLOWED_PATHS` | 否 | `[]` | 允许读取图片的路径 JSON 数组 |

### 心跳

| 变量 | 必填 | 默认值 | 说明 |
| --- | --- | --- | --- |
| `WORKER_HEARTBEAT_INTERVAL_SEC` | 否 | `5` | 心跳间隔（秒） |
| `WORKER_HEARTBEAT_JITTER_PCT` | 否 | `20` | 抖动百分比（0–100） |
| `WORKER_CALL_TIMEOUT_SEC` | 否 | `ceil(2.5 * interval)` | gRPC 调用超时（秒） |

### 日志

| 变量 | 必填 | 默认值 | 说明 |
| --- | --- | --- | --- |
| `WORKER_LOG_LEVEL` | 否 | `info` | `debug` / `info` / `warn` / `error` |
| `WORKER_LOG_FORMAT` | 否 | `json` | `json` / `text` |
| `WORKER_LOG_ADD_SOURCE` | 否 | `false` | 是否在日志中包含源文件和行号 |

## 相关文档

- [架构](/zh-CN/docs/architecture)
- [Docker 运行时](/zh-CN/docs/worker-docker)
- [Boxlite 运行时](/zh-CN/docs/worker-boxlite)
