Agent 日常使用手册¶

本文面向已经完成 Agent 服务安装的普通使用者，说明如何查看 Agent 运行状态、管理服务、修改配置、查看日志、手动更新和卸载 Agent。

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

常用路径¶

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

类型	默认位置
Agent 程序	`/usr/local/bin/beak-agent`
更新程序	`/usr/local/bin/beak-agent-updater`
配置文件	`/etc/beak-agent/agent.env`
工作目录	`/var/lib/beak-agent/work`
Profile Cache	`/var/lib/beak-agent/profile-cache`
日志目录	`/var/log/beak-agent`
主日志文件	`/var/log/beak-agent/log`
systemd 服务	`beak-agent.service`

查看服务状态¶

查看 Agent 是否正在运行：

systemctl status beak-agent

只查看服务是否为 active：

systemctl is-active beak-agent

查看当前安装的 Agent 版本：

/usr/local/bin/beak-agent --version

查看 Agent 运行用户：

systemctl show beak-agent -p User -p Group

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

启动、停止和重启¶

启动 Agent：

sudo systemctl start beak-agent

停止 Agent：

sudo systemctl stop beak-agent

重启 Agent：

sudo systemctl restart beak-agent

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

sudo systemctl restart beak-agent

查看日志¶

查看最近的 systemd 日志：

journalctl -u beak-agent -n 100

持续查看最新日志：

journalctl -u beak-agent -f

查看 Agent 主日志文件：

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

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

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

修改配置¶

Agent 的运行配置默认写在：

/etc/beak-agent/agent.env

修改前建议先备份：

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

编辑配置：

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

常见配置包括：

配置项	说明
`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_DEFAULT_APPROVAL_TTL_SECONDS`	默认审批超时时间

修改完成后重启服务：

sudo systemctl restart beak-agent

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

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

注意

agent.env 中可能包含 API Key、Token、访问地址等敏感信息。不要把完整配置文件发送到公开聊天、工单、代码仓库或截图中。

手动更新和回退¶

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

手动检查并更新到 release 源中的最新版本：

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

安装指定版本：

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

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

sudo /usr/local/bin/beak-agent-updater --target-version v0.1.8

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

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

卸载 Agent¶

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

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

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

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

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

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

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

常见检查¶

Agent 在页面中显示离线¶

建议按顺序检查：

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

Agent 修改配置后没有生效¶

确认是否已经重启服务：

sudo systemctl restart beak-agent

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

journalctl -u beak-agent -n 50

Agent 更新后版本没有变化¶

先查看当前版本：

/usr/local/bin/beak-agent --version

再检查更新日志：

journalctl -u beak-agent -n 100

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