Agent 日常使用手册¶

本文面向已经完成 Agent 服务安装的用户，说明如何查看 Agent 状态、管理服务、修改配置、查看日志、收集 Session Bug Report、手动更新和卸载 Agent。

以下命令适用于 Linux/systemd 安装方式。执行服务管理、配置修改和卸载命令时，通常需要主机的 sudo 权限。

找到 Agent 文件¶

默认安装后，Agent 相关文件位于以下位置：

查看 Agent 状态¶

查看 Agent 是否正在运行：

systemctl status obs-agent

只查看服务是否为 active：

systemctl is-active obs-agent

查看当前安装的 Agent 版本：

/usr/local/bin/obs-agent --version

查看 Agent 运行用户：

systemctl show obs-agent -p User -p Group

默认情况下，Agent 服务会以 obs-agent 用户运行，而不是以 root 常驻运行。root 主要用于安装、升级、卸载等主机管理动作。

启动、停止或重启 Agent¶

启动 Agent：

sudo systemctl start obs-agent

停止 Agent：

sudo systemctl stop obs-agent

重启 Agent：

sudo systemctl restart obs-agent

修改配置后，通常需要重启服务让新配置生效：

sudo systemctl restart obs-agent

查看 Agent 日志¶

查看最近的 systemd 日志：

journalctl -u obs-agent -n 100

持续查看最新日志：

journalctl -u obs-agent -f

查看 Agent 主日志文件：

tail -n 100 /var/log/obs-agent/log

如果 Agent 无法启动，建议先查看：

systemctl status obs-agent
journalctl -u obs-agent -n 100

收集 Session Bug Report¶

当 Agent 回复异常、工具卡住或连接不稳定时，可以在发生问题的 Session 中直接请求 Agent 收集、脱敏并上传诊断报告，同时把临时下载链接发送到指定支持邮箱，无需手动下载后再转发。

具体操作、权限说明、邮件发送和失败处理见在 Session 中收集并发送 Agent Bug Report。

修改 Agent 配置¶

Agent 的运行配置默认写在：

/etc/obs-agent/agent.env

修改前建议先备份：

sudo cp /etc/obs-agent/agent.env /etc/obs-agent/agent.env.bak

编辑配置：

sudo vi /etc/obs-agent/agent.env

常见配置包括：

如果 Agent 必须通过企业代理访问 Beak、LLM 或 release 服务，请按为 obs-agent 配置正向代理设置代理变量和企业 CA。

LLM_MODEL 已不再是必填配置。新版本运行时默认使用 default 模型标识；如果旧配置中仍保留 active LLM_MODEL=...，只有在确实需要固定模型时才建议继续保留，否则可以删除该行后重启服务。

修改完成后重启服务：

sudo systemctl restart obs-agent

如果配置改错导致服务无法启动，可以恢复备份：

sudo cp /etc/obs-agent/agent.env.bak /etc/obs-agent/agent.env
sudo systemctl restart obs-agent

手动更新或回退 Agent¶

Agent 可以通过本机更新程序切换版本。

旧版更新程序可以沿用原有命令升级，无需先手动替换 updater。支持空闲保护的 Agent 会等待已有任务结束；升级期间已被 Beak 接收的新对话会在连接恢复后自动重试。没有空闲协议的旧 Agent 首次过渡时会直接重启，可能中断正在执行的对话，完成过渡后使用空闲保护。

托管升级失败时会尝试恢复原有二进制、配置和服务，并保留失败诊断。同一目标按既有退避策略重试，新目标不继承旧目标的等待时间。

更新到 release 源中的最新版本：

sudo /usr/local/bin/obs-agent-updater

安装指定版本：

sudo /usr/local/bin/obs-agent-updater --target-version v0.2.0

版本回退也使用同一个命令。例如回退到 v0.1.9：

sudo /usr/local/bin/obs-agent-updater --target-version v0.1.9

查看自动更新定时器状态：

systemctl status obs-agent-update-check.timer
systemctl list-timers obs-agent-update-check.timer

如果更新失败，优先检查：

• /etc/obs-agent/agent.env 中的 AGENT_UPDATE_BASE_URL 是否正确；
• release 地址下是否存在 install.sh、目标版本安装包和校验文件；
• journalctl -u obs-agent-update-check.service -n 100 中是否有下载、校验或调度错误；
• journalctl -u obs-agent -n 100 中是否有启动或重启错误。

自动升级会读取 /etc/obs-agent/agent.env 中的代理变量。代理环境下的检查方法见让自动升级继续使用代理。

卸载 Agent¶

卸载脚本默认只展示卸载计划，不会删除任何内容：

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

确认无误后，带 --yes 执行彻底卸载：

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

卸载会删除以下固定对象：

• /usr/local/bin/obs-agent
• /usr/local/bin/obs-agent-updater
• /usr/local/bin/obs-agent-update-check
• /etc/obs-agent
• /var/lib/obs-agent
• /var/log/obs-agent
• obs-agent.service
• obs-agent-update-check.service
• obs-agent-update-check.timer
• /etc/sudoers.d/obs-agent
• obs-agent 用户和用户组

卸载不会删除 skill-dep.sh 安装或检查过的 Skill 运行依赖，例如系统命令、语言运行时、Python/Node 包、字体或其它系统包。这些依赖可能是主机原本已有的共享组件，也可能被其它服务复用，不能由 Agent 卸载流程移除。

常见检查¶

Agent 在页面中显示离线¶

建议按顺序检查：

1. 主机服务是否运行：systemctl status obs-agent
2. 主机网络是否能访问服务地址；
3. /etc/obs-agent/agent.env 中的 BEAK_WS_URL、AGENT_API_KEY、AGENT_ID 是否正确；
4. 最近日志中是否有认证失败、网络连接失败或 DNS 解析失败。

Agent 修改配置后没有生效¶

确认是否已经重启服务：

sudo systemctl restart obs-agent

然后查看日志确认新进程已经启动：

journalctl -u obs-agent -n 50

Agent 更新后版本没有变化¶

先查看当前版本：

/usr/local/bin/obs-agent --version

再检查更新日志：

journalctl -u obs-agent-update-check.service -n 100
journalctl -u obs-agent -n 100

如果是指定版本更新，确认命令中的版本号和 release 源中的版本号一致。