obscli 用户手册¶

obscli 是 Beak 的命令行客户端。安装并登录后，您可以在终端中完成以下操作：

1. 查看当前 workspace 中的 Agent。
2. 创建新 Task，或继续已有 Task。
3. 与 Agent 对话、引用观测资源、指定 Skill。
4. 在脚本中提交一次性任务并获取结果。

安装 obscli¶

用安装脚本安装¶

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 路径：

安装后如果无法直接运行 obscli，请把安装目录加入 PATH：

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

WSL 属于 Linux 环境，也使用以上命令和路径。

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>

Windows 默认安装到：

%LOCALAPPDATA%\Programs\obscli\obscli.exe

安装完成后，重新打开 PowerShell，然后运行：

obscli

如果不方便重新打开 PowerShell，可以直接运行完整路径：

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

Windows 默认目录：

建议在 Windows 上使用 PowerShell 安装脚本。Git Bash 会按自己的 $HOME 解释路径；如果使用 Git Bash，请明确指定安装目录：

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>

用离线安装包安装¶

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

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

卸载 obscli¶

重命名前旧版迁移¶

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

Linux/macOS/WSL:

以下两条命令任选其一。第一条会在删除前询问确认，第二条使用 --yes 跳过确认：

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¶

从 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 如何自动更新¶

通过安装脚本安装的 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

常用命令¶

表格里的 <number> 指 /agents 或 /tasks 输出表格中 # 列的临时编号。/newtask <number> 使用 /agents 的 # 编号；/attach <number> 和 /close <number> 使用 /tasks 的 # 编号。

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

控制 Agent 的访问权限¶

/yolo 是开关命令：

• 第一次执行：进入 Full access，Agent 可以访问 working directory 以外的文件，工具调用不再请求审批。
• 再次执行：回到 normal mode，恢复文件访问限制和审批提示。

只在信任当前 Agent 和 Task 上下文时开启 YOLO。

让 subagents 并行处理任务¶

当任务适合拆分为多个独立方向时，可以用 /subagent <task> 要求 Agent 优先使用 subagents。例如：

/subagent 分别检查最近一小时的错误日志、慢查询和告警事件，并汇总根因线索

obscli 会显示各 subagent 的启动、等待和完成状态，最终结果由主 Agent 汇总。您也可以用上下方向键从输入历史中找回完整命令。

手动压缩任务历史¶

长任务接近模型上下文限制时，Agent 会自动压缩较早的对话和工具交互。需要提前释放上下文空间时，可以在当前 Task 中执行：

/compact

压缩会保留最近的原始交互，并把较早历史整理为可继续执行的摘要；它不会关闭 Task，也不会删除完整的 session 事件记录。obscli 会显示压缩开始和完成状态。如果当前历史仍在保留预算内，Agent 会直接提示无需压缩。

规划并执行复杂任务¶

使用 /plan 主动进入 Plan mode：

/plan [prompt]

例如：

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

收到计划后，可以确认、拒绝、要求修改或中断：

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

直接发送普通消息不会自动进入 Plan mode。关闭仍在执行计划的 Task，也会中断该计划。

在脚本中运行单个 prompt¶

使用 obscli run 可以提交一次性任务、等待 Agent 回答，然后退出。它适合 shell 脚本和自动化任务。

运行前需要先通过 obscli --login <user-sk> 登录。run 会读取现有登录配置，脚本无需再次传入认证信息。

运行 obscli -h 或 obscli run -h 可以查看 run 支持的全部参数。

如果不知道 agent UUID，先列出当前 workspace 内在线的 agent：

obscli run --list-agents
obscli run --list-agents --json

默认输出包含 Agent 的 UUID、名称和状态；--json 适合脚本解析。该命令只查询在线 Agent，不会创建 Task。

直接传入 prompt：

answer="$(obscli run --agent-uuid <AGENT_UUID> --prompt '检查最近一小时的错误并简要总结')"
printf '%s\n' "$answer"

读取多行文件或 stdin：

obscli run --agent-uuid <AGENT_UUID> --prompt-file ./prompt.md
printf '%s\n' '总结当前 workspace 的健康状态' | \
  obscli run --agent-uuid <AGENT_UUID> --prompt-file -

默认 stdout 只包含 Agent 返回的原始 Markdown，正常过程不会写 stderr。需要结构化结果时使用 --json：

obscli run --agent-uuid <AGENT_UUID> --prompt '返回一句状态摘要' --json

JSON 结果包含回答、相关 UUID、Agent UUID 和 Task 名称。存在用量或附件信息时，也会一并返回。

默认超时为 5 分钟，可用 --timeout 90s 修改。使用 -v、-vv、-vvv 或 --verbose=1|2|3 可以把不同级别的诊断信息写入 stderr。默认情况下，如果 Agent 请求危险工具审批，命令会取消本轮并以退出码 3 结束。只有明确接受 Full access 风险时才使用 --yolo。

需要让一次性任务优先使用 subagents 时，添加 --subagent：

obscli run --agent-uuid <AGENT_UUID> --subagent \
  --prompt '分别检查最近一小时的错误日志、慢查询和告警事件，并汇总线索'

如果任务无法合理拆分，Agent 会说明原因后直接回答。--subagent 不能与 --list-agents 组合。

obscli run 不支持需要多轮确认的 Plan mode。如需确认或修改计划，请使用交互式 obscli。

常用退出码：

在 --json 模式下，失败时 stdout 保持为空，stderr 返回包含 error.code 和 error.message 的 JSON 对象。脚本应使用退出码和这两个字段判断结果。

在消息中引用资源和 Skill¶

在交互式输入框中输入 @，可以引用当前 workspace 的观测资源：

• Service
• Dashboards
• Application
• Hosts
• Containers

使用方向键或 Tab 浏览列表，按 Space 选择一项或多项，按 Enter 确认。输入文字可以模糊搜索资源名称和类型。选中的资源会以 @资源名 显示在消息中，为 Agent 提供查询上下文。

在已 attach 的单 Agent Task 中输入 $，可以选择该 Agent 提供的 Skill。搜索支持 Skill 名称和描述，并忽略空格，例如 rootcause 可以匹配 Root cause analysis。选择方式与资源列表相同，每个已选 Skill 都作用于整条消息。

两个列表都需要先按 Space 选择，再按 Enter 确认。搜索不会清除已经选中的项目。

在 @资源名 或 $skill-name 边界按 Backspace 或 Delete，会删除整个引用。通过方向键或 Ctrl+R 找回历史消息时，资源和 Skill 也会恢复。

如果只想输入普通 @ 或 $，打开列表后按 Esc 即可。粘贴到普通输入框中的 @ 和 $ 也会保留为普通文本。

进入 Task 后，直接输入消息并按 Enter 即可发送。

如果 Task 中只有一个 Agent，消息默认发送给该 Agent；如果有多个 Agent，消息会广播给所有 Agent。

使用键盘快捷键¶

普通输入支持以下快捷键：

弹窗选择支持：

如果某个终端里的方向键或控制键无效，请先确认终端没有把该快捷键绑定给外层应用；仍异常时，打开 ~/.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>

这里的 <number> 是 /agents 输出表格中 # 列的编号。