你在虚拟机的配置里明明勾选了"启用 guest agent"，满心以为这下能看 IP、能优雅关机、能在线改密码了。可真去用的时候，平台提示 agent 没运行。你回头确认了开关确实开着，一头雾水。
现象
具体表现：
- 想查询虚拟机 IP，平台报
agent 未运行或No QEMU guest agent configured； - 想执行"优雅关机"（shutdown），平台说 agent 不可用，只能硬断电或走别的途径；
- 想冻结文件系统做快照、想在线改 IP，都因为"agent 未运行"而做不了。
而你去查虚拟机配置，agent: 1 这一项确实是开着的。
根因
这是一个典型的**"两端开关"**问题。
guest agent（在 Proxmox VE 里是 qemu-guest-agent）是一套运行在客户机（虚拟机内部）里的程序，它通过 virtio 串口和宿主机通信，替宿主机执行"读 IP、优雅关机、注入配置"这类操作。
它需要两端都就位：
- 宿主机侧：在虚拟机配置里打开 agent 开关。它的作用是创建一个通信通道（virtio-serial 端口）并"允许"agent 通信。
- 客户机侧：在虚拟机内部安装并运行 agent 程序。它才是真正响应请求的那一方。
你在平台里勾的那个开关，属于宿主机侧——它只是把"通道"和"许可"准备好了。如果客户机里根本没装 agent 软件，通道那头就没人应答。于是平台 ping 它时报"agent 未运行"——准确地说，是"agent 不在那儿"。
一句话：宿主机的开关只管"允许"，客户机的软件才管"可用"。 一个开着的开关，不代表服务在跑。
解决
在客户机内部安装并启用 agent。
以 Debian/Ubuntu 系为例：
sudo apt update
sudo apt install -y qemu-guest-agent
sudo systemctl enable --now qemu-guest-agent
sudo systemctl status qemu-guest-agent
RHEL/CentOS 系：
sudo dnf install -y qemu-guest-agent
sudo systemctl enable --now qemu-guest-agent
注意几个细节：
- 装完要重启虚拟机（或至少确保 agent 服务起来），因为 virtio 串口设备在启动时枚举；
- 确认虚拟机里存在那个 virtio 串口设备（
/dev/virtio-ports/org.qemu.guest_agent.0之类），没有的话说明宿主机侧的通道没配好； - agent 装好、起来之后，平台侧的 IP 查询、优雅关机就会正常工作。
临时应急：在 agent 装好之前，你只能走网络 SSH 来管理这台机器——没有 agent，平台给不了 IP，你可能得先靠 DHCP 租约表、路由器后台或查看邻居缓存（ip neigh）去猜 IP。所以对于批量部署，agent 一定要写进镜像初始化里，别等建好再一个个补。
延伸与预防
这条坑的通用模型，是**"配置开关 ≠ 服务可用"**。
但凡一个功能横跨"两侧"——宿主机/客户机、服务端/客户端、控制面/执行面——你都要问一句："我开的这个开关，改变的是哪一侧？另一侧就位了吗？" 常见的同类情况：
- 防火墙"开端口"了，但服务根本没在监听（允许≠有服务）；
- 服务端开了代理协议，客户端却还在用普通协议；
- CI 里配了某个 runner 标签，但 runner 进程没跑；
- 监控平台加了探针目标，但目标机器上没装 exporter。
预防上，最省事的一条是把它做进"标准镜像"：在制作基础镜像/模板时就把 guest agent 装好、设成开机自启。这样克隆出来的每台机器都自带，不用事后一台台救。凡是"每台新机器都要做一遍的手工动作"，都应该被固化进镜像——这是批量运维的基本功。