CLI 参考

Lybic GUI Agent CLI (`cli_app.py`)

CLI 提供了一种交互式或一次性的方式来运行 GUI 智能体，它封装了模型/工具编排、运行环境（沙箱/本地）、推理模式和安全控制。

基本调用方式

无论是从源码运行还是通过已安装的包运行，命令格式如下：

python gui_agents/cli_app.py [OPTIONS] # 从源码
# 或 python -m gui_agents.cli_app [OPTIONS]
# 或
lybic-guiagents-cli [OPTIONS]         # 如果通过 pip 安装

如果省略 --query，CLI 将启动交互式提示符（单行指令）。每条指令都会运行一个由 --max-steps 限制的智能体会话。

核心选项

选项	值	默认值	用途
`--backend`	`lybic` `lybic_mobile` `pyautogui` `pyautogui_vmware`	`lybic`	选择执行环境（云沙箱或本地控制）。
`--query`	字符串	（无）	非交互式运行单个指令，执行完成后退出。
`--max-steps`	整数 >0	`50`	任务动作步数的上限。防止无限循环。
`--mode`	`normal` `fast`	`normal`	在“更丰富的思考链/记忆功能”与“更快速的极简推理”之间做权衡。
`--enable-takeover`	标志	关闭	允许智能体暂停任务并在任务中途请求人工干预。
`--disable-search`	标志	关闭	关闭网页/搜索工具调用，适用于离线环境或确定性任务运行场景。

后端选择

lybic: 使用远程 Lybic 沙箱（推荐）。需要 LYBIC_API_KEY / LYBIC_ORG_ID。
lybic_mobile: 通过 Lybic 的 Android 沙箱。需要 LYBIC_API_KEY / LYBIC_ORG_ID。
pyautogui: 直接控制您的本地桌面（请谨慎使用）。需要安装额外的pyautogui 相关依赖。
pyautogui_vmware: 控制预创建的 VMware 虚拟机（设置 USE_PRECREATE_VM）。需要安装额外的vmware-and-evaluation 及评测相关依赖。

常用环境变量

# 沙箱
LYBIC_API_KEY=xxx
LYBIC_ORG_ID=org_yyy
LYBIC_PRECREATE_SID=BOX-...        # （可选）现存的沙箱ID
LYBIC_MAX_LIFE_SECONDS=3600         # 沙箱生命周期覆盖配置（单位：秒）

# 模型配置（英文配置示例）
GEMINI_ENDPOINT_URL=https://generativelanguage.googleapis.com/v1beta/openai/  # Gemini 接口地址
GEMINI_API_KEY=sk-... # Gemini API 密钥
ARK_API_KEY=ark-... # ARK 接口密钥

中文模型配置在使用 tools_config_cn.json 时可能只需要 ARK_API_KEY。

工具配置流程

# 英文工具
cp gui_agents/tools/tools_config_en.json gui_agents/tools/tools_config.json
# 中文工具
cp gui_agents/tools/tools_config_cn.json gui_agents/tools/tools_config.json

tools_config 中推荐的模型：grounding / fast_action_generator -> doubao-1-5-ui-tars-250428；action_generator -> claude-sonnet-4-20250514 或 doubao-seed-1-6-250615。

执行模式

normal: 完整推理、记忆更新、消耗更多tokens。
fast: 跳过冗长的推理链；适用于高频次、小型任务场景。

人工接管流程（`--enable-takeover`）

当智能体对任务执行存在不确定性时，会发出人工介入请求。此时您可手动调整本地界面（若为本地后端）或沙箱环境，调整完成后按 Enter 键恢复智能本运行。若未启用该参数，此类暂停请求将被屏蔽。

示例场景

在沙箱中运行交互式：

python gui_agents/cli_app.py --backend lybic

本地执行单个确定性任务（限制步数）：

python gui_agents/cli_app.py --backend pyautogui --query "Open calculator and compute 123*45" --max-steps 25 --disable-search

快速批量执行任务：

python gui_agents/cli_app.py --backend lybic --query "Download today's stock data to a CSV" --mode fast

启用人工介入模式：

python gui_agents/cli_app.py --backend lybic --enable-takeover

在 VMware 受控环境中执行任务：

uv pip install .[vmware-and-evaluation]
export USE_PRECREATE_VM=Ubuntu
python gui_agents/cli_app.py --backend pyautogui_vmware --query "Update system packages" --max-steps 40

安全提示

在使用 pyautogui 后端之前，务必关闭所有敏感应用。
使用 --max-steps 来限制成本和风险。
优先使用沙箱（lybic）以获得可复现性和隔离性。

常见问题快速排查

症状	修复
`KeyError` provider	验证 `.env` 和工具配置文件是否正确复制。
定位（grounding）速度缓慢	使用推荐的 UI-TARS 模型；如果可接受，切换到 `fast`。
沙箱未创建	确保 `LYBIC_API_KEY` / `LYBIC_ORG_ID` 有效且余额充足。
Unicode 安装错误（Win）	执行`set PYTHONUTF8=1` 然后重新安装。

退出行为

单次 --query成功执行：以代码 0 退出。
达到最大步数但未成功：退出码为非 0（具体值取决于实现），需查看日志排查原因
键盘中断（Ctrl+C）：尝试优雅关闭。（即完成当前步骤后停止，而非强制终止）

日志记录和可观测性

在运行 gRPC 服务器变体时启用 Prometheus（参见 GUI 智能体主文档）。CLI 会继承内部指标但不直接暴露 /metrics。

更新 / 升级

pip install -U lybic-guiagents
# 或如果从源码
uv sync && uv pip install -e .

最小测试脚本

python gui_agents/cli_app.py --backend lybic --query "Take a screenshot and save it to desktop" --max-steps 15 --mode fast

何时使用 CLI vs gRPC

使用 CLI	使用 gRPC 服务
手动实验	多语言集成
本地调试	横向扩展 / 持久化
一次性自动化	长时编排器

有关更深入的架构说明，请参见 GUI 智能体页面。

本页内容