obscli 用户手册¶

obscli 是 Obsy Agent Teams 的命令行工具。安装并登录后，您可以在终端中完成以下操作：

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

安装 obscli¶

从设置中心安装（推荐）¶

在 Obsy Agent Teams 页面点击右上角的个人头像，进入 个人配置 > 开发工具 > obs-cli：

1. 选择 macOS、Linux 或 Windows；
2. 点击复制命令；
3. 在需要使用 obscli 的终端中运行该命令；
4. 安装完成后运行 obscli，确认可以查看当前工作空间中的 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 路径：

安装后如果无法直接运行 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、更新配置和日志。删除后需要重新登录。

登录 obscli¶

通过设置中心复制的安装指令会在安装时完成登录，无需再次操作。

如果使用离线安装包，或需要重新指定登录信息，请进入 个人配置 > 开发工具获取当前个人访问凭证，然后执行：

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。

!!! warning "更新个人访问凭证"

在设置中心重新生成个人访问凭证后，原凭证会立即失效。请重新复制安装指令完成接入，或使用新凭证重新登录 `obscli`。

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 的 # 编号。

/agents 和 /tasks 都带 workspace 列。执行 /newtask <number> 或 /attach <number> 后，当前 Session 会切换到对应 workspace；消息、审批、历史、附件、@ 资源和 $ Skill 都继续使用该 workspace。关闭当前 Task 后会回到登录配置中的默认 workspace。底部状态栏用独立的 workspace 项显示当前 workspace，并用 agent_task 显示 Agent/Task；两项都可通过 /statusline 调整。

重新 /attach 时会加载最近 10 条消息及其关联的工具调用历史，显示工具状态和结果预览。同一次调用的运行记录与终态结果合并展示，不会重新执行历史工具或重复发起审批。工具历史读取失败时，对话正文仍会显示，并提示未能加载的回复；可稍后重新 attach 重试。

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 会直接提示无需压缩。

复制最终回答¶

在当前 Task 中执行 /copy，可把最近一条已完成的 LLM 最终回答按原始 Markdown 复制到运行 obscli 的机器的系统剪贴板：

/copy

/copy 不接受参数，只复制最终回答本身，不包含 thinking、commentary、工具调用、task insight、subagent handoff 或其它运行详情。plan_final 也属于可复制的最终回答。需要收集诊断上下文时，应让 Agent 使用 collect_bug_report，不要通过剪贴板导出运行详情。

若最新一轮尚未产生最终回答，obscli 会复制前一条已完成回答并显示警告。

规划并执行复杂任务¶

使用 /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 脚本和自动化任务。

任务需要临时凭据时，用 --import-credential /secure/credentials.json 导入文本和文件；全部确认后才发送 prompt，任务结束后关闭会话并撤销凭据。格式和路径规则见 会话私密凭据。不要把秘密写入 prompt。

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

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

如果不知道 agent UUID，先列出账号各 workspace 中可用的 Agent：

obscli run --list-agents
obscli run --list-agents --json
obscli run --list-agents --workspace-uuid <WORKSPACE_UUID>

默认输出包含 workspace、Agent UUID、名称以及 creating、idle、busy 或 offline 原始状态；--json 还包含 workspace_uuid 和 workspace_name，适合脚本解析。指定 --workspace-uuid 时，obscli 仍先读取账号级列表，再在客户端过滤；该命令不会创建 Task。

直接传入 prompt：

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

默认在登录配置的 workspace 中创建 Task；要在其他 workspace 执行，请显式指定：

obscli run --workspace-uuid <WORKSPACE_UUID> --agent-uuid <AGENT_UUID> --prompt '检查当前状态'

创建 Task 前，run 会校验目标 Agent 是否存在于该 workspace 且当前账号有权访问。Agent 不存在或属于其他 workspace 时，命令立即退出并提示重新选择 Agent；--json 的错误码为 agent_not_found，退出码为 2。认证、网络或服务请求失败也会在创建 Task 前报错。已注册但暂时离线的 Agent 仍可接收任务，命令会在超时范围内等待其恢复并回复。

读取多行文件或 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 名称。存在用量或附件信息时，也会一并返回。

obscli run 默认端到端超时为 2 小时，覆盖本次任务准备、发送提示及等待最终回复，可用 --timeout 90s 修改。该上限适用于一次 run 命令，交互式聊天不使用这个超时；单次模型请求和工具执行仍遵循各自的超时设置。

使用 -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¶

在交互式输入框中输入 @，可以引用当前 Session 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。

使用键盘快捷键¶

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

slash 命令等待 Beak 响应时，按 Ctrl+C 或连续两次 Esc 可停止本地等待，期间输入会保留为草稿，需重新按 Enter 才提交。取消不会撤销服务端已完成的操作；若提示写操作可能已生效，请先核对状态再重试。

凭据表单的网络等待也支持上述取消按键，但等待期间的输入和粘贴会被丢弃，避免秘密进入普通聊天草稿、日志或缓存。

工具详情中，方向键或鼠标滚轮滚动，PageUp／PageDown 翻页，Home／End 跳到首尾， Ctrl+P／Ctrl+N 切换上一／下一条工具调用。进入时定位到最近一次调用的开头。 查看期间普通输入、粘贴和 Enter 不会编辑或提交聊天消息；新结果保留当前阅读位置， 滚动到末尾后自动跟随。审批到达时显示提示，按 q 返回后处理。

已加载及后续收到的聊天内容缓存在 ~/.obscli/cache/sessions/YYYY/MM/DD/<session-id>.jsonl， 无需先打开工具详情。一个会话固定使用首次创建缓存的日期目录，退出和再次 attach 后继续复用。 交互终端 attach 先显示本地最近的聊天内容，再在后台分页补齐 Beak 可提供的全部会话历史，期间可以正常输入。通过管道或脚本输入时，会先完成历史加载再读取下一条命令，保证 /save、/exit 等顺序执行。 再次 attach 从消息同步水位加载新增历史，并单独检查离线前尚未结束的 Reply Run；已同步且版本未变化的完成调用不会重复下载详情。 同步失败会显示 History sync incomplete，再次 attach 或进入工具详情时重试，继续未完成的历史分页。 较早的工具调用同步后可在 Ctrl+T 中浏览，普通聊天仅呈现最近的消息和工具预览。

同一会话和 Agent 下的 tool_call_id 对应一条调用：本地已有参数、调用说明及完整结果优先保留， 远端历史补齐缺失内容和离线期间的终态、最终结果，不用脱敏摘要覆盖本地正文，也不把终态倒退为运行中。 普通聊天和 Ctrl+T 读取相同的合并记录；无法从现有事件判断顺序的冲突终态保留先前状态。 SQLite 侧文件只保存 JSONL 位置、排序、去重及同步索引，每次打开时重建；正文、来源和同步检查点均保存在 JSONL。 旧缓存无需迁移。切换会话或退出会取消后台请求，缓存不可写时仅显示可用历史并提示原因。 文件按服务端、工作空间、用户和会话校验身份，30 天未更新且未被使用时自动清理。 工具详情不受每条 256 KiB 或最近 50 条的限制；Beak 已有的脱敏、截断和引用文本保持原样。 展开视图沿用聊天工具块的标题、分隔和命令高亮，支持 JSON 缩进和 Markdown 排版；滚动、翻页与终端缩放时保留样式及完整正文。 工具调用前的进展反馈和调用说明会一并展示，工具结束或再次 attach 后仍保留。 完整参数需要新版 Agent 提供；旧 Agent 或旧缓存没有保留完整参数时，会明确提示不可用并展示已有摘要。历史参数以 Beak 返回的脱敏内容为准。 按行缩略的参数、命令、调用说明及结果统一提示 ...+<n> lines (ctrl+t to view transcript)。 工具编号按同一会话缓存中的首次出现顺序从 1 递增，同一会话的新一轮聊天不重置，重新 attach 后保持稳定。普通聊天默认隐藏编号；/tool-index on|off 会立即重绘当前保留的聊天回放和运行中工具，并将偏好保存为 ~/.obscli/config.toml 的 show_tool_index。开启后编号以灰色 (n) 显示，组内 [i/count] 仍独立保留。Ctrl+T 始终显示编号，按 g 输入编号并回车定位调用开头，Esc 取消输入；无效编号不改变当前位置，跳转后停止自动跟随。编号仅保证同一本地缓存内稳定，缓存不可用时不生成伪编号。 工具标题显示工具名称，包括 read_skill 和 read_skill_file；Skill 名称、路径等参数在下方展示。旧记录没有工具名时沿用已有显示名称。 推理期间，Thinking... 下方实时保留最新 5 个屏幕行，长行自动换行，未换行片段也立即显示；结束后保留有界预览，完整事件继续写入会话缓存。非交互输出保留完整文本。 普通聊天也会显示参数预览，包括并发工具块和 attach 加载的历史；长参数在折叠模式中缩略，按 Ctrl+T 查看完整内容。 缓存或历史读取失败时会明确提示完整详情不可用，其余内容仍可查看。

弹窗选择支持：

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