obsycli 用户手册¶

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

安装¶

使用安装脚本¶

Linux/macOS:

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

Linux/macOS 默认使用 Unix 路径：

类型	默认路径
安装目录	`~/.local/bin`
可执行文件	`~/.local/bin/obsycli`
数据目录	`~/.obsycli`
登录和更新配置	`~/.obsycli/login.toml`
日志目录	`~/.obsycli/log`
当前日志文件	`~/.obsycli/log/obsycli.log`

确保安装目录在 PATH 中：

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

Windows PowerShell:

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

Windows 默认使用 Windows 路径：

类型	默认路径
安装目录	`%LOCALAPPDATA%\Programs\obsycli`
可执行文件	`%LOCALAPPDATA%\Programs\obsycli\obsycli.exe`
数据目录	`%USERPROFILE%\.obsycli`
登录和更新配置	`%USERPROFILE%\.obsycli\login.toml`
日志目录	`%USERPROFILE%\.obsycli\log`
当前日志文件	`%USERPROFILE%\.obsycli\log\obsycli.log`

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

obsycli

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

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

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

安装脚本会把 --release-base-url 记录到对应系统的登录配置文件：

Linux/macOS: ~/.obsycli/login.toml
Windows:     %USERPROFILE%\.obsycli\login.toml

后续 obsycli 启动时会读取该地址检查新版本。

卸载¶

Linux/macOS:

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

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

sudo rm -f /usr/local/bin/obsycli
rm -rf ~/.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

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

Windows Git Bash:

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

WSL:

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

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

登录¶

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

obsycli --login <user-sk> --beak-server https://agent-api.guance.com

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

obsycli --login <user-sk> --beak-server https://agent-api.guance.com --insecure-skip-tls-verify

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

~/.obsycli/login.toml

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

自动更新¶

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

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

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

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

export OBSYCLI_NO_UPDATE_CHECK=1

常用命令¶

命令	用途
`obsycli`	进入交互式客户端
`/agents`	查看 workspace 下的 agent
`/tasks`	查看可用 task
`/newtask <number>`	创建新 task 并 attach 到指定编号的 agent
`/attach <number>`	Attach 到已有编号的 task
`/close <number\\|task_id>`	关闭当前或指定 task
`/clear`	清屏
`/statusline`	配置状态栏字段，并写入 `~/.obsycli/config.toml`
`/exit`	退出

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

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

命令	用途
`/plan`	切入 plan mode，但不向 agent 发送规划请求
`/plan <prompt>`	切入 plan mode，并把 prompt 作为规划请求发送给 agent
`/plan-approve`	确认最近收到的待确认 final plan
`/plan-reject [reason]`	拒绝当前 final plan，并让 agent 回到规划修订
`/plan-revise <feedback>`	发送修改意见，用于继续迭代计划
`/plan-interrupt [reason]`	打断当前 active plan，并回到 normal mode

例如：

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

如果 prompt 不具备可规划的任务语义，agent 会继续澄清具体规划意图。

发送消息¶

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

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

终端按键兼容¶

obsycli 的交互式输入和弹窗选择支持以下按键：

普通输入支持：

按键	行为
`Enter`	发送当前输入；如果正在选择 slash command，则接受当前高亮命令
`Shift+Enter` / `Alt+Enter`	插入换行
`Esc`	触发取消当前输入确认
双击 `Esc`	取消当前输入或当前 chat
`↑` / `↓`	浏览历史输入；如果当前正在选择 slash command，则移动高亮项
`←` / `→`	左右移动光标
`Home` / `End`	跳到行首/行尾
`Backspace`	删除光标前字符
`Delete`	删除光标处字符
`Tab`	补全 slash command 的公共前缀
`Ctrl+A` / `Ctrl+E`	跳到行首/行尾
`Ctrl+C`	当前输入非空时清空输入；输入为空时退出当前交互
`Ctrl+L`	清屏并保留当前输入
`Ctrl+R`	搜索历史输入
`Ctrl+T`	打开工具输出全文
`Ctrl+W`	删除光标前一个词
直接输入文字	插入到当前光标位置

弹窗选择支持：

按键	行为
`↑` / `Ctrl+P`	向上移动高亮项；到第一项后继续按会跳到最后一项
`↓` / `Tab` / `Ctrl+N`	向下移动高亮项；到最后一项后继续按会回到第一项
`Space`	选中当前项；多选弹窗中切换当前项
`Enter`	提交已选项
`Esc`	取消当前弹窗
`Ctrl+C`	取消弹窗并退出当前交互
`Backspace`	删除搜索词最后一个字符
直接输入文字	过滤列表，并把高亮项重置到第一项

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

本地文件¶

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

Linux/macOS:

~/.obsycli/login.toml
~/.obsycli/log/obsycli.log

Windows:

%USERPROFILE%\.obsycli\login.toml
%USERPROFILE%\.obsycli\log\obsycli.log

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

故障排查¶

登录失败时，先确认：

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

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

/agents
/newtask <number>

obsycli 用户手册¶

安装¶

使用安装脚本¶

卸载¶

登录¶

自动更新¶

常用命令¶

发送消息¶

终端按键兼容¶

本地文件¶

故障排查¶

文档内容是否对您有帮助？ ×