obscli 用户手册¶

obscli 是连接 Beak 服务的命令行客户端。它可以登录 Beak、查看 agent 和 task、创建或 attach 到 task，并在终端里与 agent 对话。

安装¶

使用安装脚本¶

Linux/macOS:

curl -fsSL https://static.guance.com/obscli/install-obscli.sh | bash -s -- \
  --release-base-url https://static.guance.com/obscli \
  --beak-server https://agent-api.guance.com \
  --login <YOUR-USER-SK>

Linux/macOS 默认使用 Unix 路径：

Windows Git Bash 可以执行 Unix shell 安装脚本，但路径会按 Git Bash 的 $HOME 解释。如需安装到 Windows 用户目录，优先使用 PowerShell 安装脚本。WSL 属于 Linux 环境，使用 Linux 路径和 Linux 安装包。

curl.exe -fsSL https://static.guance.com/obscli/install-obscli.sh | bash -s -- \
  --release-base-url https://static.guance.com/obscli \
  --install-dir "$HOME/bin" \
  --beak-server https://agent-api.guance.com \
  --login <YOUR-USER-SK>

Windows PowerShell:

iwr https://static.guance.com/obscli/install-obscli.ps1 -OutFile $env:TEMP\install-obscli.ps1
Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass -Force
& $env:TEMP\install-obscli.ps1 `
  -ReleaseBaseUrl https://static.guance.com/obscli `
  -BeakServer https://agent-api.guance.com `
  -Login <YOUR-USER-SK>

默认安装到 ~/.local/bin/obscli，不需要 root 权限，也方便后续自更新。

确保安装目录在 PATH 中：

export PATH="$HOME/.local/bin:$PATH"

Windows PowerShell 安装默认使用用户目录：

%LOCALAPPDATA%\Programs\obscli\obscli.exe

修改用户 Path 后，已经打开的终端可能不会自动刷新环境变量；重新打开 PowerShell 后可以直接运行：

obscli

如果是在当前 PowerShell 中又启动了一个子进程执行安装，例如 powershell -File ...，父窗口的 PATH 不会被子进程刷新。此时可以直接运行安装脚本输出的完整路径：

& "$env:LOCALAPPDATA\Programs\obscli\obscli.exe"

Windows 默认目录：

使用离线安装包¶

下载与你的系统匹配的安装包，例如：

obscli-linux-amd64-v1.2.3.tar.gz
obscli-darwin-arm64-v1.2.3.tar.gz
obscli-windows-amd64-v1.2.3.tar.gz

校验并安装：

sha256sum -c obscli-linux-amd64-v1.2.3.tar.gz.sha256
bash install-obscli.sh --archive ./obscli-linux-amd64-v1.2.3.tar.gz --install-dir "$HOME/.local/bin" --yes

卸载¶

重命名前旧版迁移¶

如果本机曾安装旧版 obsycli，不要直接覆盖安装 obscli。先删除旧可执行文件和旧数据目录，再按“安装”章节重新安装并登录新版 obscli。

Linux/macOS/WSL:

curl -fsSL https://static.guance.com/obs-agent/uninstall-legacy.sh | sudo bash
curl -fsSL https://static.guance.com/obs-agent/uninstall-legacy.sh | sudo bash -s -- --yes

该脚本会清理重命名前的 beak-agent 固定系统布局，也会删除旧 obsycli 的常见 Linux/macOS 安装位置：/usr/local/bin/obsycli、/usr/bin/obsycli、当前 HOME 和 SUDO_USER 对应 home 下的 ~/.local/bin/obsycli 与 ~/.obsycli。

Windows PowerShell:

Get-Command obsycli -All
Remove-Item "$env:LOCALAPPDATA\Programs\obsycli\obsycli.exe" -Force -ErrorAction SilentlyContinue
Remove-Item "$env:LOCALAPPDATA\Programs\obsycli" -Recurse -Force -ErrorAction SilentlyContinue
Remove-Item "$env:USERPROFILE\.obsycli" -Recurse -Force -ErrorAction SilentlyContinue

删除旧版后，使用当前文档里的 obscli 安装命令重新安装。obscli 使用 ~/.obscli 或 %USERPROFILE%\.obscli，不会读取旧版 obsycli 的本地配置。

卸载当前版本¶

Linux/macOS:

which -a obscli
rm -f ~/.local/bin/obscli
rm -rf ~/.obscli

如果曾经用 sudo 安装到系统目录：

sudo rm -f /usr/local/bin/obscli
rm -rf ~/.obscli

Windows PowerShell:

Get-Command obscli -All
Remove-Item "$env:LOCALAPPDATA\Programs\obscli\obscli.exe" -Force -ErrorAction SilentlyContinue
Remove-Item "$env:LOCALAPPDATA\Programs\obscli" -Recurse -Force -ErrorAction SilentlyContinue
Remove-Item "$env:USERPROFILE\.obscli" -Recurse -Force -ErrorAction SilentlyContinue

如果曾经把 obscli.exe 放到其他目录，按 Get-Command obscli -All 输出的 Windows 路径删除对应文件。

Windows Git Bash:

which -a obscli
rm -f "$HOME/bin/obscli.exe"
rm -rf "$HOME/.obscli"

WSL:

which -a obscli
rm -f ~/.local/bin/obscli
rm -rf ~/.obscli

本地数据目录包含登录 token、更新配置和日志。删除后需要重新登录。

登录¶

从 Beak Web 页面复制 user sk，然后执行：

obscli --login <YOUR-USER-SK> --beak-server https://agent-api.guance.com

测试环境证书不被本机信任时，可以加：

obscli --login <YOUR-USER-SK> --beak-server https://agent-api.guance.com --insecure-skip-tls-verify

登录成功后，认证信息会写入：

~/.obscli/login.toml

后续直接运行 obscli 即可进入交互式 chat。

自动更新¶

通过安装脚本安装的 obscli 会在启动阶段检查是否有新版本。发现新版本时，会提示：

New obscli version available: v1.2.3 -> v1.2.4. Update now? [y/N]

输入 y 或 yes 后，obscli 会下载当前系统匹配的安装包、校验 .sha256，并替换本地可执行文件。Linux/macOS 更新后会自动重新启动 obscli；Windows 会在当前进程退出后完成替换，需要重新运行 obscli。

如果当前环境不希望启动时检查更新，可以设置：

export OBSCLI_NO_UPDATE_CHECK=1

常用命令¶

关闭后 task 不能再发送新消息；如需继续对话，请新建 task。

/yolo 是开关命令。首次执行会把当前 task 切换到高风险 Full access 状态：agent 可以访问 working directory 之外的本机文件路径，并且后续工具调用不会再弹出 approve/reject 审批。再次执行 /yolo 会回到 normal mode：恢复文件访问范围限制，并重新启用 approval 弹窗。只在信任当前 agent 和 task 上下文时开启 YOLO。

Plan mode 只能通过 slash command 主动触发，agent 不会根据规划类自然语言请求自动进入。主动触发方式：

/plan [prompt]

例如：

/plan 我要制作一个 dashboard，请给我一个规划

Plan mode 中确认、拒绝、要求修改或打断计划：

/plan-approve
/plan-reject [reason]
/plan-revise <feedback>
/plan-interrupt [reason]

其中：

• /plan 会把当前 task 切入 plan mode，但不向 agent 发送规划请求；它只是模式开关。
• /plan <prompt> 会切入 plan mode，并把 prompt 作为用户规划请求发送给 agent。如果 prompt 不具备可规划的任务/场景语义，agent 应继续澄清具体规划意图。
• /plan-approve 会确认最近收到的待确认 final plan。
• /plan-reject [reason] 会拒绝当前 final plan，并让 agent 回到规划修订。
• /plan-revise <feedback> 会把修改意见发送给 agent，用于继续迭代计划。
• /plan-interrupt [reason] 用于打断当前 active plan。它可以用于 planning、等待审批、修订或执行阶段；打断后 plan mode 退出，后续普通消息按 normal mode 处理。
• 如果 /close 关闭的 task 仍有 active plan，服务端应先产生 plan_interrupted(reason=session_closed)，再进入 close summary / close 流程。obscli 应把它视为普通 plan_interrupted terminal event，清理本地 plan 状态。

obscli 会把 plan_update、plan_final、plan_execution_progress、plan_blocked、plan_interrupted、plan_completed 等 plan events 渲染为 Markdown/普通文本块。plan_interrupted 和 plan_completed 都会清理本地 plan 状态并回到 normal mode。Web UI 可使用 schema overlay 做富展示；obscli 不渲染 Web UI schema，只消费同一套 plan event 语义。

本地手测方式：

本地手测脚本会生成专用 login.toml。用对应 HOME 启动 dist/obscli 后，先用 /agents 查看 agent 编号，之后 /newtask <number> 创建普通 task。进入 plan mode 可以执行 /plan 只切换模式，也可以执行 /plan <规划请求> 直接提交规划请求，或通过 Web UI 触发等价 plan action；直接发送规划类自然语言只会作为普通 chat 处理，agent 可建议用户切换但不能自动进入。

发送消息¶

Attach 到 task 后，直接输入自然语言消息并回车即可。

如果 task 中只有一个 agent，消息默认发送给该 agent；如果 task 中有多个 agent，消息会作为广播发送。

终端按键兼容¶

obscli 的交互式输入和弹窗选择需要从终端读取按键。常见终端会用不同协议编码方向键、控制键和组合键；obscli 当前兼容以下模式：

普通输入支持：

弹窗选择支持：

部分终端启用增强键盘协议后，Esc 可能表现为 27u 或 27;1u。obscli 会把这些序列按同一个全局取消请求处理，而不是当作搜索词。

如果某个终端里的方向键或控制键无效，请先确认终端没有把该快捷键绑定给外层应用；仍异常时，打开 ~/.obscli/log/obscli.log 并记录终端名称、版本和按键行为。

本地文件¶

obscli 默认使用以下本地路径：

Linux/macOS:

~/.obscli/login.toml
~/.obscli/log/obscli.log

Windows:

%USERPROFILE%\.obscli\login.toml
%USERPROFILE%\.obscli\log\obscli.log

日志会自动轮转，默认单文件最大 32 MiB。

故障排查¶

登录失败时，先确认：

• --beak-server 指向 Beak 服务地址
• 如果使用安装脚本自动登录，--beak-server 指向 Beak 服务地址
• user sk 是从当前 Beak Web 页面复制的有效凭据
• HTTPS 测试环境是否需要 --insecure-skip-tls-verify

如果进入 chat 后没有 task，可以先执行：

/agents
/newtask <number>