Agent 日常使用手册¶
本文面向已经完成 Agent 服务安装的用户，说明如何查看 Agent 状态、管理服务、修改配置、查看日志、收集 Session Bug Report、手动更新和卸载 Agent。
以下命令适用于 Linux/systemd 安装方式。执行服务管理、配置修改和卸载命令时，通常需要主机的 sudo 权限。
找到 Agent 文件¶
默认安装后，Agent 相关文件位于以下位置：
| 类型 | 默认位置 |
|---|---|
| Agent 程序 | /usr/local/bin/obs-agent |
| 更新程序 | /usr/local/bin/obs-agent-updater |
| 配置文件 | /etc/obs-agent/agent.env |
| 工作目录 | /var/lib/obs-agent/work |
| Profile Cache | /var/lib/obs-agent/profile-cache |
| 日志目录 | /var/log/obs-agent |
| 主日志文件 | /var/log/obs-agent/log |
| systemd 服务 | obs-agent.service |
技能与 MCP 更新¶
Agent 先读取基础配置并连接，再逐项准备技能和 MCP。依赖准备期间可以继续聊天；准备完成后，已有会话的后续请求即可使用新能力。
有依赖的技能必须先通过检查；主机安装会补齐缺失或不满足版本要求的依赖，容器部署需要在镜像中提供依赖。更新失败后该资源不可用，不回退旧版；其他已就绪资源继续可用。正常同步默认约每十分钟执行一次；失败后 30 秒自动重试，成功后恢复正常间隔。手动配置了更短同步间隔时，失败重试沿用该间隔。
在 Agent 的技能或 MCP 页面查看准备结果。若本机已就绪但状态暂未更新，可能是上报连接失败；后续同步会重新上报，不需要重新安装或新建会话。
查看 Agent 状态¶
查看 Agent 是否正在运行：
只查看服务是否为 active：
查看当前安装的 Agent 版本：
查看 Agent 运行用户：
默认情况下，Agent 服务会以 obs-agent 用户运行，而不是以 root 常驻运行。root 主要用于安装、升级、卸载等主机管理动作。
启动、停止或重启 Agent¶
启动 Agent：
停止 Agent：
重启 Agent：
修改配置后，通常需要重启服务让新配置生效：
查看 Agent 日志¶
查看最近的 systemd 日志：
持续查看最新日志：
查看 Agent 主日志文件：
如果 Agent 无法启动，建议先查看：
离线收集本地 Bug Report¶
当 Agent 无法连接 Beak、LLM 调用失败或 Session 工具无法运行时，直接在 Agent 主机执行：
默认深度为 0，收集主机、进程、配置、日志、所有可发现 Session 和运行时现场，不导出 LLM 深度证据。报告默认写入当前目录，也可以用 --bug-report-output 指定完整 ZIP 文件路径（不是目录）；目标文件必须尚不存在，父目录必须已经存在：
命令不会启动正常 Agent runtime，也不会连接 WebSocket、调用模型、请求审批或上传文件。stdout 只输出一行 JSON，其中 status 为 completed 或 partial，并包含绝对路径、字节数、SHA-256 和稳定错误码。两种状态都表示 ZIP 已完成安全校验；命令退出码均为 0。
若 Agent 使用独立配置文件，可追加 --env-file /etc/obs-agent/agent.env，并以能读取该 Agent 缓存和本地诊断接口的账户执行。深度范围是 0..3：1 为调用结构信息，2 追加脱敏后的 provider 请求、响应及工具证据；需要先在运行中的 Agent 配置 AGENT_DIAGNOSTIC_CHAT_DEPTH=2（或更高），未录制的历史无法补录。基础证据与深度证据位于同一个 ZIP。3 仅允许本地离线导出，标记为 UNREDACTED，会保留未脱敏原始内容；默认文件名和 stderr 均提示该敏感性，不应直接分享。
在本机打开报告：
查看器兼容基础报告、历史 LLM 深度报告与统一报告，通过本地浏览器展示 Session、调用轮次、指标和文件，不上传归档。
正常 Agent 默认在 profile cache 的 diagnostics/runtime.sock 提供权限 0600 的本地诊断接口，用于采集目标进程的 heap、goroutine、30 秒 CPU profile、5 秒 runtime trace、cmdline、metrics 和 runtime timeline。该接口只使用 Unix socket，不监听 TCP；可在 agent.env 中设置 AGENT_LOCAL_DIAGNOSTICS_ENABLED=false 关闭。
容器中可直接执行并复制报告：
docker exec obs-agent obs-agent --bug-report --bug-report-output /app/obs-agent-support.zip
docker cp obs-agent:/app/obs-agent-support.zip ./obs-agent-support.zip
报告没有固定 ZIP 大小上限，会为输出文件系统保留动态安全空间。CPU profile、trace、日志和 Session 历史可能使报告较大；复制前先核对 stdout 中的 size_bytes 和 sha256。
深度 0..2 诊断包可能包含脱敏后的配置、Session 内容、日志和运行时现场；深度 3 包含未脱敏内容。文件固定为 0600，仍应只通过受控支持渠道传递；处理完成后及时删除，不要提交到代码仓库、公开工单或聊天群。
收集 Session Bug Report¶
当 Agent 回复异常、工具卡住或连接不稳定时，可以在发生问题的 Session 中直接请求 Agent 收集、脱敏并上传诊断报告，同时把临时下载链接发送到指定支持邮箱，无需手动下载后再转发。
具体操作、权限说明、邮件发送和失败处理见在 Session 中收集并发送 Agent Bug Report。
在线收集只针对当前 Session，支持 chat_depth=0..2，默认 0，遵循会话授权规则并上传报告；chat_depth=3 会被拒绝。
修改 Agent 配置¶
Agent 的运行配置默认写在：
修改前建议先备份：
编辑配置：
常见配置包括：
| 配置项 | 说明 |
|---|---|
BEAK_WS_URL |
Agent 连接的服务地址 |
AGENT_API_KEY |
Agent 接入凭证 |
AGENT_ID |
当前 Agent ID |
LLM_BASE_URL |
LLM 服务地址 |
LLM_API_KEY |
LLM 调用凭证 |
AGENT_WORKDIR |
Agent 工具执行工作目录 |
AGENT_PROFILE_CACHE_DIR |
Agent profile、Skill 和 schema 缓存目录 |
AGENT_UPDATE_BASE_URL |
Agent release 下载地址 |
AGENT_LOCAL_AUTO_UPDATE_ENABLED |
本机自动升级开关，由独立更新检查器读取 |
AGENT_DEFAULT_APPROVAL_TTL_SECONDS |
已废弃的兼容项；可删除，Agent 不再按它让审批过期 |
如果 Agent 必须通过企业代理访问 Beak、LLM 或 release 服务，请按为 obs-agent 配置正向代理设置代理变量和企业 CA。
LLM_MODEL 不是必填配置，默认使用 auto 自动路由。旧配置中的 LLM_MODEL=default 在加载时按 auto 处理，Agent 不会改写原文件。只有需要固定模型时才需配置真实模型 ID；否则可以删除该行后重启服务。BYOK 使用其目录中的默认模型配置，不受此环境变量影响。
修改完成后重启服务：
如果配置改错导致服务无法启动，可以恢复备份：
注意
agent.env 中可能包含 API Key、Token、访问地址等敏感信息。不要把完整配置文件发送到公开聊天、工单、代码仓库或截图中。
个人 Owl Key 模式¶
默认使用 Agent 安装时配置的 Owl 凭据。启用个人 Owl Key 模式后，普通会话使用会话创建者的个人 Open API Key，定时任务和用户 Webhook 使用配置创建者的 Key；其他成员追问不会改用提问者的 Key。IM 及其派生委派继续使用安装凭据。个人 Key 缺失、禁用或删除时拒绝执行，不回退到安装凭据。
管理员须先完成 Beak、Backend/Connector、Owl 和 Agent 的配套升级，并确认创建者的个人 Key 已同步。Owl 必须支持 runtime-profile/v1；安装流程会检查其实际能力。通过配套前端保存安装设置，再显式重新安装 Agent，才能应用 AGENT_OWL_USER_TOKEN_ENABLED=true。该项默认 false，普通升级保留本机模式，保存设置或重启不等于已应用新的安装模式。
不同身份使用隔离的 Owl Profile 和查询结果目录，不复制默认目录中的历史查询结果。Key 更换或撤销会取消仍使用旧 Key 的运行和排队任务；需要时重新提交新请求。遇到权限拒绝时，检查创建者在目标工作空间的角色和查询权限，不改用其他凭据绕过拒绝。Profile 隔离不提供同一系统用户下任意脚本的操作系统沙箱。
部署前须审核 Backend outbox 的数据库变更。依次部署 Beak（保持该模式关闭）、Backend/Connector、支持新能力的 Owl 与完整 Agent 发行包、前端，再保存设置并重装启用。回退前先关闭该模式并重装，保留凭据版本水位及既有加密配置，避免旧凭据覆盖新状态。
手动更新或回退 Agent¶
Agent 可以通过本机更新程序切换版本。
旧版更新程序可以沿用原有命令升级，无需先手动替换 updater。支持空闲保护的 Agent 会等待已有任务结束；升级期间已被 Beak 接收的新对话会在连接恢复后自动重试。没有空闲协议的旧 Agent 首次过渡时会直接重启，可能中断正在执行的对话，完成过渡后使用空闲保护。
托管升级失败时会尝试恢复原有二进制、配置和服务，并保留失败诊断。同一目标按既有退避策略重试，新目标不继承旧目标的等待时间。
从 v0.16.0 起，支持新维护协议的主机先等待已有工作完成，再停止旧进程、安装完整发行包，并进行启动前预检及正式进程版本检查。会话中可查看维护开始、成功、失败和恢复结果；维护期间提交的新消息保留在 Beak，连接恢复后自动续投。可用依赖会保留，缺失依赖才补装；下载或预检失败按现有流程恢复旧发行。
Agent 内部版本收敛轮询、obscli agent pin-version 和 POST /api/v1/agents/{id}/version:pin 已移除。旧 AGENT_UPDATE_ENABLED 和 AGENT_UPDATE_CHECK_INTERVAL_SECONDS 不再生效；自动升级由本机 systemd 定时器触发，通过 AGENT_LOCAL_AUTO_UPDATE_ENABLED 控制。原有 updater 调用方式保留，--target-version 仅指定本次操作的目标，不建立持续版本锁定。
更新到 release 源中的最新版本：
即使当前 agent 已经是 latest，该命令仍会执行一次完整升级，用于重试安装当前版本配套的 Browser runtime 等组件。后台定时检查在版本相同时不会重复安装这些组件。
安装指定版本：
版本回退也使用同一个命令。例如回退到 v0.1.9：
查看自动更新定时器状态：
如果更新失败，优先检查：
/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¶
卸载脚本默认只展示卸载计划，不会删除任何内容：
确认无误后，带 --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-agentobs-agent.serviceobs-agent-update-check.serviceobs-agent-update-check.timer/etc/sudoers.d/obs-agentobs-agent用户和用户组
卸载不会删除 skill-dep.sh 安装或检查过的 Skill 运行依赖，例如系统命令、语言运行时、Python/Node 包、字体或其它系统包。这些依赖可能是主机原本已有的共享组件，也可能被其它服务复用，不能由 Agent 卸载流程移除。
常见检查¶
Agent 在页面中显示离线¶
建议按顺序检查：
- 主机服务是否运行：
systemctl status obs-agent - 主机网络是否能访问服务地址；
/etc/obs-agent/agent.env中的BEAK_WS_URL、AGENT_API_KEY、AGENT_ID是否正确；- 最近日志中是否有认证失败、网络连接失败或 DNS 解析失败。
Agent 修改配置后没有生效¶
确认是否已经重启服务：
然后查看日志确认新进程已经启动：
Agent 更新后版本没有变化¶
先查看当前版本：
再检查更新日志：
如果是指定版本更新，确认命令中的版本号和 release 源中的版本号一致。