README.zh-cn.md

English | 简体中文

---

Tip

一行命令。任意 CLI 工具。隔离沙箱。

cli-box start claude

就这样。Claude Code 在独立沙箱窗口中运行。截图。自动化。关闭。

cli-box

macOS 桌面自动化沙箱 — AI Agent 专用

安装

TL;DR

你想	运行	效果
npm	npx cli-box-skill install	选择 harness，自动装二进制 + skill
Shell	bash <(curl -fsSL https://raw.githubusercontent.com/Shadow-Azure/cli-box/main/packages/cli-box-skill/skill/install.sh) claude	下载到 ~/.cli-box/bin/，安装 skill
手动	GitHub Releases	手动下载解压

给人类用户

把这段命令粘贴到 Claude Code 里 — 它会自动下载、安装、配置权限、验证运行：

Install cli-box by following the instructions here:
https://raw.githubusercontent.com/Shadow-Azure/cli-box/main/docs/guide/installation.md

Agent 会处理 macOS 权限、PATH 配置和快速测试。只需在提示时确认即可。

给 AI Agent

一行安装 cli-box： 运行 npx cli-box-skill install all 把 skill 装到所有受支持的 harness（Claude Code、OpenCode、OpenClaw）；把 all 换成 claude / opencode / openclaw 可只装一个。

npx cli-box-skill install claude    # claude | opencode | openclaw | all

添加 PATH

echo 'export PATH="$HOME/.cli-box/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

演示

启动 Claude Code 沙箱，交互，获取截图：

$ cli-box start claude
Sandbox started: 0cd60ad4

$ cli-box screenshot --id 0cd60ad4 -o state.png

多 Tab — 同时运行 Claude Code、OpenCode、zsh：

支持任意 CLI 工具：

cli-box start claude    # Claude Code
cli-box start opencode  # OpenCode
cli-box start zsh       # Shell
cli-box start node      # Node.js

特性

	功能
多实例	每个 CLI 工具独立沙箱 Tab
窗口截图	ScreenCaptureKit 按窗口 ID 截图，无需前台
PTY 输入	直接终端输入，支持中文和所有按键组合
MCP 集成	Claude Code / OpenCode 通过 MCP 调用 cli-box
零侵入	目标应用无需适配，OS 层面操作

快速参考

# 沙箱生命周期
cli-box start [command]         # 启动沙箱（默认 zsh）
cli-box start "cd /app && claude -r"  # 复合命令经 zsh -lc 执行
cli-box list                    # 列出活跃沙箱
cli-box close <id>              # 关闭沙箱

# 截图 + 输入
cli-box screenshot --id <id> -o shot.png
cli-box screenshot --id <id> --up 100 -o history.png   # 截图窗口上移 100 行
cli-box screenshot --id <id> --top -o top.png          # 跳到 scrollback 最顶部
cli-box scrollback --id <id>                           # 导出整段会话文本（干净文本）
cli-box type --id <id> "你好世界"
cli-box key --id <id> Return
cli-box click --id <id> 100 200

# MCP 配置（添加到 .claude/settings.json）
# { "mcpServers": { "cli-box": { "command": "cli-box", "args": ["mcp-serve"] } } }

macOS 权限

权限	用途	授权位置
辅助功能	输入模拟 + UI 检查	系统设置 → 隐私与安全性
屏幕录制	窗口截图	系统设置 → 隐私与安全性

将 cli-box 和 CLI Box.app 添加到两个列表中。权限需手动授予。

技术栈

组件	技术
核心	Rust (≥1.88), cli-box-core
CLI	Rust, cli-box-cli 二进制
桌面	Electron + React 18 + TypeScript + Vite + xterm.js
macOS API	CoreGraphics (CGEvent), ApplicationServices (AXUIElement), ScreenCaptureKit
License	Apache 2.0

---

English · GitHub Issues