本地 Agent 最让人崩溃的场景之一，是昨天还能用，今天更新以后全坏了。OpenClaw 换了版本，工具执行和 memory 不稳定；Hermes 升级后 Gateway 或 provider 配置像没生效；OpenHands 换了镜像或 runtime 后，本地模型、sandbox、依赖又要重查。你会花半天确认是不是自己配置错了，最后发现是版本、依赖和旧状态混在一起。
这类问题很常见，因为本地 Agent 的状态比普通软件多。它不只有程序文件，还有 config、env、skills、memory、MCP server、workspace、模型 provider、Gateway 服务、Docker 镜像、浏览器依赖和本地日志。更新任何一层，都可能让另一层断掉。
所以维护本地 Agent，不能只靠“坏了再重装”。更实用的做法，是把它当成一个小型运行环境来维护。
更新前先备份什么
更新前最少备份 6 类东西。
第一类是主配置。Hermes 常见位置是 ~/.hermes/config.yaml 和相关 .env；OpenClaw 常见位置是 ~/.openclaw/openclaw.json；OpenHands 如果用 Docker 或本地配置，也要保存 .env、compose 文件、runtime 镜像版本和模型配置。不同工具路径不一样，但原则一样：保存“当前能跑”的配置快照。
第二类是 API Key 和 provider 设置。不要只备份 key 本身，还要记录它对应哪个 provider、base_url、model id、是否走 gateway、是否有 rate limit 或余额限制。很多更新后的问题不是 key 丢了，而是 provider 字段、模型名或 endpoint 格式变了。
第三类是 skills、tools 和 MCP server 配置。OpenClaw skills、Hermes tools、Claude Desktop / Claude Code / Cline 里的 MCP server 配置，都可能因为 schema 变化、路径变化或依赖变化出问题。更新前至少保存工具列表、server 命令、env、工作目录和关键参数。
第四类是 memory、notes 和长期状态。OpenClaw 这类工具会把一部分 memory 以 Markdown 或本地文件形式存下来；Hermes 也有会话、配置和日志状态。很多人重装以后发现真正丢的不是程序，而是 Agent 过去积累的上下文、任务状态和自定义规则。
第五类是运行时依赖。Node、Python、uv、Docker、Playwright、浏览器、ffmpeg、npx、bun、模型服务端口，这些都可能在更新后变成隐性问题。尤其是 Gateway 作为服务进程运行时，它拿到的 PATH 可能和你当前终端不一样。
第六类是版本号。更新前记录当前工具版本、模型 provider、Docker 镜像 tag、重要插件版本和本地模型版本。没有这些信息，就很难判断要不要回退。
更新后先做最小验证，不要直接恢复日常任务
更新完成以后，不要立刻把它接回真实项目、邮箱、文件系统和定时任务。先跑最小验证。
第一步只看命令和状态：version、doctor、health、status 能不能跑。OpenClaw FAQ 提到 openclaw health --verbose 会显示 target URL 和 config path；Hermes 问题页建议先跑 hermes doctor 来判断卡在安装、模型、Gateway、Tools 还是远程后端；Hermes 模型文档也建议用 hermes config get model 和 hermes status 看当前实际配置。
第二步测试模型。用一个很短的问题确认模型能返回，再确认当前会话真的用的是更新后的 provider 和 model。不要只看 config 文件，因为运行中的 session 或 Gateway 可能还拿着旧配置。
第三步只开一个低风险工具。比如列目录、读测试文件、查一个公开网页，确认工具调用格式和权限没问题。工具调用能成功以后，再逐步恢复 browser、shell、MCP、消息平台、cron job 和外部 API。
第四步恢复真实任务前，先看日志。很多本地 Agent 的错误已经写在 gateway log、errors log、runtime log 或 Docker logs 里。直接重装会掩盖真正原因，后面同样的问题还会回来。
什么时候该修，什么时候该回退
更新后出问题，不一定都要硬修。可以按影响范围判断。
如果只是一个 provider、一个工具或一个 MCP server 坏了，先局部修。比如 API Key 过期、model id 改名、base_url 变化、Playwright 没装、browser tool 找不到依赖，这些通常没必要回退整个 Agent。
如果主会话、memory、skills、Gateway 和工具调用同时坏，先不要继续叠补丁。这个时候更像版本迁移或配置 schema 问题，应该回到更新前备份，对照官方迁移说明或社区 issue，看是否有人遇到同样问题。OpenClaw 的配置资料里提到 openclaw doctor --fix、config.apply、config.patch 这类迁移和修复入口，这类工具比手改大 JSON 更安全。
如果更新导致安全策略变化，也不要急着关掉保护。比如某些写文件、shell、外部请求突然需要确认，可能是工具把权限收紧了。为了恢复“以前的方便”而把确认全关掉，后面风险会更大。
平时怎么维护，少遇到一更新就坏
本地 Agent 可以按周做一次轻维护。
先看模型配置：当前 provider、model、base_url、key、余额、rate limit 是否还正常。本地模型还要看显存、模型版本、上下文长度和 tool calling 表现。社区里关于 Hermes 和本地模型的讨论提到，工具集太大时，本地模型会循环、误用工具或根本不调用工具。平时不要默认把所有工具都挂上。
再看工具和 MCP。清理不再使用的 MCP server，关闭高风险工具，保留一个低风险测试任务。MCP server 不要只看“能连接”，还要看它暴露了什么工具、是否需要文件或网络权限、是否来自可信来源。OWASP 和 HashiCorp 的 MCP 安全资料都强调：不要把外部工具输出直接当成可信指令，也不要给 root/shared token。
然后看 Gateway 和定时任务。如果你依赖 Telegram、Discord、Slack、飞书、企业微信、cron job 或 webhook，定期跑一次实际消息链路。CLI 能用不代表 Gateway 能用，Gateway 能用也不代表定时任务正在跑。
最后看日志和存储。日志无限增长会占空间，旧会话和旧运行时会让问题更难查。可以保留最近能复现问题的一段日志，定期清理无用缓存和临时文件，但不要随手删 memory、skills 和 config 备份。
一个可复制的更新检查清单
更新前：
- 记录当前版本、模型 provider、model id、base_url、运行方式。
- 备份 config、env、skills、memory、MCP server 配置、Docker compose 或启动脚本。
- 暂停 cron job、消息机器人和高风险自动任务。
- 记录一条“更新前能成功”的最小任务。
更新后：
- 跑 version / doctor / health / status。
- 新开干净会话，测试最小问答。
- 测试一个低风险 tool call。
- 测试一个常用 MCP server。
- 测试 Gateway 或消息入口。
- 查看日志里是否有 provider、schema、PATH、权限、依赖相关错误。
- 成功后再恢复真实 workspace、shell、browser、cron 和外部 API。
需要回退时：
- 先保存当前错误日志和版本号。
- 恢复更新前 config/env/skills/memory。
- 固定旧版本或旧 Docker 镜像 tag。
- 用同一条最小任务验证回退是否成功。
- 再决定要不要重新尝试升级。
继续往下看
参考来源
- OpenClaw FAQ
- https://docs.openclaw.ai/help/faq
- OpenClaw Skills Library：Gateway Configuration
- https://openclawskills.dev/en/reference/gateway/configuration/
- OpenClaw Update Survival Guide
- https://www.remoteopenclaw.com/blog/openclaw-update-survival-guide
- Hermes Agent 中文站：遇到问题
- https://hermes-zh.com/docs/issues
- Hermes Agent Docs：Configuring Models
- https://hermes-agent.ru/docs/user-guide_configuring-models.html
- OpenHands Docs：Local Setup
- https://docs.openhands.dev/openhands/usage/run-openhands/local-setup
- OWASP：MCP Tool Poisoning
- https://owasp.org/www-community/attacks/MCP_Tool_Poisoning
- HashiCorp Developer：Vault MCP Server Security Model
- https://developer.hashicorp.com/vault/docs/mcp-server/security-model