opencomputer

你可以使用 oc CLI 管理 OpenComputer 云沙盒。使用它来创建沙盒、执行命令、管理检查点等。

首次设置（在运行任何其他 oc 命令之前执行）

在运行任何沙盒命令之前，请确保用户已完成设置。按顺序执行以下检查，只修复有问题的部分：

1. 是否已安装 oc CLI？

which oc

如果返回了路径 → 已安装，跳到第 2 步。

如果没有返回内容 / 退出码非零 → 使用官方单行命令安装：

curl -fsSL https://raw.githubusercontent.com/diggerhq/opencomputer/main/scripts/install.sh | bash

这会将 oc 安装到 ~/.local/bin/oc。如果 ~/.local/bin 不在用户的 PATH 中，请告知他们将 export PATH="$HOME/.local/bin:$PATH" 添加到 shell rc 文件中，并在本次会话的其余时间使用完整路径 ~/.local/bin/oc。

2. 用户是否已登录（已配置 API 密钥）？

oc config show

如果显示了 API Key（即使已屏蔽）→ 已登录，完成。

如果未设置 API 密钥，或者沙盒命令因身份验证错误（401、“unauthorized”、“missing API key”）而失败：

1. 在用户的浏览器中打开 OpenComputer 仪表板，让他们创建密钥：
   • macOS：open https://app.opencomputer.dev
   • Linux：xdg-open https://app.opencomputer.dev
2. 在聊天中告知用户：
   • 在刚打开的页面上登录 / 注册
   • 创建 API 密钥
   • 获取密钥后，在终端中运行此命令：

     oc config set api-key YOUR_API_KEY
     

3. 等待用户确认已设置密钥后再继续。

不要在聊天中向他们索要密钥——他们应将密钥粘贴到自己的终端中，以确保密钥不会离开他们的设备。

CLI 参考

沙盒生命周期

# Create a sandbox (returns sandbox ID)
oc sandbox create --timeout 300 --cpu 1 --memory 512
oc sandbox create --env KEY=VALUE --env KEY2=VALUE2
oc sandbox create --secret-store my-secrets --metadata project=demo
oc create  # shortcut

# List running sandboxes
oc sandbox list
oc ls  # shortcut

# Get sandbox details
oc sandbox get <sandbox-id>

# Kill a sandbox
oc sandbox kill <sandbox-id>

# Hibernate (saves state to S3, can wake later)
oc sandbox hibernate <sandbox-id>

# Wake a hibernated sandbox
oc sandbox wake <sandbox-id> --timeout 300

# Update timeout
oc sandbox set-timeout <sandbox-id> <seconds>

执行命令

默认情况下，oc exec 会实时输出 stdout/stderr，并以远程进程的退出码退出。使用 --wait 执行缓冲式 / 同步操作（--json 需要此选项），或使用 --detach 以启动后立即返回。

# Stream live (default)
oc exec <sandbox-id> -- echo hello
oc exec <sandbox-id> --cwd /app -- npm install
oc exec <sandbox-id> --timeout 120 -- make build
oc exec <sandbox-id> --env NODE_ENV=production -- node server.js

# Buffered + JSON envelope (exitCode, stdout, stderr) — required for scripting
oc exec <sandbox-id> --wait --json -- whoami

# Fire-and-forget; prints the session id so you can re-attach later
oc exec <sandbox-id> --detach -- long-running-job

# Manage exec sessions
oc exec list <sandbox-id>
oc exec attach <sandbox-id> <session-id>
oc exec kill <sandbox-id> <session-id>

检查点

检查点会为正在运行的沙盒创建快照。你可以恢复到某个检查点（就地还原），也可以从检查点启动新的沙盒（分叉）。

# Create a checkpoint
oc checkpoint create <sandbox-id> --name "after-setup"

# List checkpoints
oc checkpoint list <sandbox-id>

# Restore sandbox to a checkpoint (in-place revert)
oc checkpoint restore <sandbox-id> <checkpoint-id>

# Spawn a new sandbox from a checkpoint (fork)
oc checkpoint spawn <checkpoint-id> --timeout 300

# Delete a checkpoint
oc checkpoint delete <sandbox-id> <checkpoint-id>

检查点补丁

补丁是在从检查点启动沙盒时应用的脚本。使用它们来自定义分叉出的环境。

# Create a patch (reads script from file)
oc patch create <checkpoint-id> --script ./setup.sh --description "Install deps"

# Create a patch from stdin
echo "apt install -y curl" | oc patch create <checkpoint-id> --script -

# List patches
oc patch list <checkpoint-id>

# Delete a patch
oc patch delete <checkpoint-id> <patch-id>

预览 URL

通过公共 URL 暴露沙盒端口。

# Create a preview URL
oc preview create <sandbox-id> --port 3000
oc preview create <sandbox-id> --port 8080 --domain myapp.example.com

# List preview URLs
oc preview list <sandbox-id>

# Delete a preview URL
oc preview delete <sandbox-id> <port>

交互式 Shell

# Open an interactive terminal session
oc shell <sandbox-id>
oc shell <sandbox-id> --shell /bin/zsh

全局标志

所有命令都支持：

• --json — 输出 JSON，而非表格
• --api-key <key> — 覆盖 API 密钥
• --api-url <url> — 覆盖 API URL

工作流模式

创建并使用沙盒

ID=$(oc create --json | jq -r '.sandboxID')
oc exec $ID --wait -- apt update
oc exec $ID --wait -- apt install -y nodejs
oc exec $ID -- node -e "console.log('hello')"
oc sandbox kill $ID

检查点工作流（设置一次，多次分叉）

# Create base environment
ID=$(oc create --json | jq -r '.sandboxID')
oc exec $ID --wait -- apt update
oc exec $ID --wait -- apt install -y python3 pip
oc exec $ID --wait -- pip install flask

# Checkpoint it
CP=$(oc checkpoint create $ID --name "python-flask" --json | jq -r '.id')
# Wait for checkpoint to be ready
oc checkpoint list $ID

# Spawn copies from the checkpoint
FORK1=$(oc checkpoint spawn $CP --json | jq -r '.sandboxID')
FORK2=$(oc checkpoint spawn $CP --json | jq -r '.sandboxID')

添加补丁以自定义分叉出的沙盒

oc patch create $CP --script ./inject-config.sh --description "Add app config"
# All future spawns from $CP will run inject-config.sh on boot

重要说明

• 需要以编程方式提取 ID 或字段时，始终使用 --json 并通过 jq 解析。
• 沙盒 ID 的格式类似 sb-xxxxxxxx。检查点 ID 为 UUID。
• 检查点需要几秒钟才能变为 ready。如有需要，使用 oc checkpoint list 轮询。
• 完成后，使用 oc sandbox kill 清理沙盒。
• oc exec 命令会以远程进程的退出码退出。