Year: 2026

背景 某 AI 代理工具的工作区目录中，反复出现一个状态文件。即使手动删除，过一段时间后文件仍会重新生成。 工作区中同时还能看到另一个隐藏目录下的状态文件。经过人工对比，这两个文件内容完全相同。于是问题变成了： 现象 工作区中存在两个状态文件： 其中顶层的 state 文件删除后会再次出现。隐藏目录中的 state 文件一直存在。 两个文件内容相同，JSON 结构也相同，主要记录工作区初始化状态，例如： 这些字段看起来不像用户数据，也不像配置密钥，而是程序用于判断工作区是否完成初始化的运行状态信息。 排查方式 排查过程中保持只读原则，没有删除、移动、修改文件，也没有重启服务。 主要检查方向包括： 排查结果 结果显示，这两个文件都属于工具正常运行会产生的文件，但地位并不完全相同。 顶层的状态文件是当前版本代码中的 canonical 路径，也就是当前主状态文件。 隐藏目录中的状态文件是 legacy 兼容路径，也就是旧路径或兼容路径。当前代码仍然会读取它，并在需要时把里面的状态迁移回顶层的 canonical 文件。 换句话说，这不是两个互相冲突的状态文件，而是同一份工作区状态在新旧路径之间共存。 为什么删除后还会出现 删除顶层状态文件后，如果隐藏目录中的 legacy 状态文件仍然存在，那么下一次工具启动、工作区初始化、代理会话创建或 heartbeat 触发时，程序会重新读取 legacy 状态。 如果程序发现顶层 canonical 状态文件不存在，就会根据 legacy 状态重新生成顶层文件。 因此，文件并不是“神秘复活”，而是程序的兼容迁移逻辑主动恢复了它。 可以理解为： 是否属于异常 从排查结果看，没有明显异常迹象。 两个文件内容一致，权限正常，字段结构正常，也没有发现异常进程或可疑写入行为。顶层文件比隐藏目录中的文件更新，说明当前程序确实更偏向使用顶层 canonical 文件，而隐藏目录中的文件更像历史兼容残留。 这种情况更像是软件版本迁移期间的兼容设计，而不是数据损坏或异常垃圾文件。 …

背景 某台小型 Linux 主机上运行着一个 AI 代理网关服务。该服务平时占用并不高，但在运行一段时间后，systemctl status 显示历史内存峰值曾达到约 5.5GB。 状态中可以看到类似结构： 这说明服务并不是单一进程，而是由主进程和若干子进程共同组成。若只限制某个 Node 进程，无法可靠覆盖整个服务组。更合理的方式是使用 systemd cgroup 资源限制，对整个 service 统一设置内存上限。 问题 该主机总内存约为 8GB，且没有启用 swap。AI 网关服务如果在高负载或异常情况下继续增长内存占用，可能导致系统进入异常状态，例如： 因此，需要给该服务设置一个最大内存使用上限。 目标不是修改应用源码，也不是给应用打补丁，而是通过系统服务管理器限制资源使用。 方案选择 最终采用的是 systemd 用户级 service drop-in 配置。 这种方式的特点是： 也就是说，这不是“打补丁”，而是系统层面的标准资源控制。 配置目标 最终设置为： 含义如下： 启用内存统计，让 systemd 记录该服务的内存使用情况。 软限制。服务内存超过 5GB 后，systemd 会开始施压、回收、限速，尽量避免继续膨胀。 硬限制。整个服务 cgroup 的内存占用不能超过 6GB。主进程和子进程合计计算。 如果服务因超出内存限制触发 OOM，systemd …

背景 某本地 AI 代理系统已经开始定期执行 HEARTBEAT 任务，并能够通过邮件发送状态报告。整体执行链路已经跑通：任务可以被触发，邮件可以正常发出，收件端也能收到报告。 不过在实际使用后，暴露出两个需要调整的问题： 第一，HEARTBEAT 执行频率过高。默认频率约为 30 分钟一次，对于日常状态汇总来说过于密集，容易造成邮件噪音。 第二，新闻摘要任务的输出质量不理想。虽然系统能够抓取公开 RSS 新闻标题并生成邮件，但内容基本停留在“标题列表 + 固定占位摘要”的层面，缺少真正可读的摘要信息。 因此，这次调整主要围绕两个目标展开： 问题一：新闻摘要内容过于粗糙 原先的新闻邮件结构大致如下： 这种输出存在明显问题： 期望的格式是每条新闻形成一个小型三语新闻卡片，例如： 这种格式的优点是： 新闻摘要任务规则的修改 原来的任务说明只要求“发送一封简洁的中文新闻摘要邮件”，这会导致 AI 代理自然倾向于输出中文简报，而不是三语新闻卡片。因此，任务规则需要明确改写。 修改后的规则重点包括： 修改后的核心目标不是“多翻译几种语言”，而是让邮件本身变成可读、可用、可追溯的国际新闻摘要。 问题二：HEARTBEAT 默认频率过高 另一个问题是 HEARTBEAT 默认频率较高。系统状态检查本身已经正常执行，但 30 分钟一次对于当前用途来说没有必要。 经过只读检查后，确认当前系统并不是通过外部定时器或 cron 控制 HEARTBEAT，而是由 AI 代理自身的配置项控制。 检查结果显示： 因此，最终修改目标是： 修改方式 修改前先进行了 dry-run，确认配置写入动作可以被接受。 示意命令如下： dry-run 成功后，再实际写入： 系统返回配置已更新，但同时提示需要重启 …

背景 在本地部署 AI 代理之后，一个很自然的需求是让它承担一些低风险、可重复的日常检查工作。例如： 这些任务看起来都可以用传统脚本完成，例如写一个 Python 脚本，再配合 cron 或 systemd timer 定时执行。但如果本地 AI 代理本身已经内置了 Heartbeat 机制，那么更合理的做法不是再造一套外部自动化系统，而是把任务边界写进代理的 Heartbeat 配置文件，让代理自己按授权范围执行。 本文记录一次围绕 Heartbeat 文件、邮件通知和发件人显示名的整理过程。 Heartbeat 文件的定位 最初容易产生一个误解：Heartbeat 文件是不是一份普通说明文档？ 实际检查后可以确认，它更适合被理解为： 本地 AI 代理的周期任务授权清单。 它不是长期记忆文件，也不是系统状态总表，更不是脚本。它的核心作用是告诉代理： 因此，Heartbeat 文件不应存放大量历史信息、主机清单、连接细节、密码、令牌、日志原文或临时排障内容。那些信息应该分别放在长期记忆文件、工具环境说明文件、每日记录文件或专门的配置文件中。 Heartbeat 文件只负责回答一个问题： 代理现在被授权定期做什么？ 最初的需求 本次需求可以分成四类每日邮件： 要求是： 这样的需求非常适合写进 Heartbeat 文件。 不应该额外写一套完整脚本 一开始可以想到一种传统方案： 这套方案当然可行，但它有一个问题： 如果脚本自己完成全部工作，那么即使没有 AI 代理，也能收到邮件。 这就偏离了 Heartbeat 文件的真正用途。此时 …

背景 某台小型 Linux 主机上运行着 OpenClaw Gateway，作为个人运维辅助入口使用。该实例经历过一次迁移和配置调整，迁移后需要确认几件事： 本次排查的原则是只读优先：先通过 systemd、journal、监听端口、配置目录和进程状态确认现状，不直接修改、不删除、不重启。只有当证据明确显示配置变更需要重启生效，且重启本身也能释放内存压力时，才执行服务重启。 初始自检结论 自检首先确认了几个基础事实： 这说明迁移后的实例基本可用，不属于“服务没起来”或“运行了错误实例”的情况。 不过自检也发现了几个需要继续收尾的问题： 这些问题并不等于实例不可用，但说明迁移后仍需要做一轮细化确认。 问题一：trusted proxy warning 的真正含义 日志中最容易误判的一条 warning 是： 表面看，这像是某个内网地址访问了 OpenClaw，并携带了代理头。进一步查看完整上下文后，发现实际情况并不是“路由器直接访问了 Gateway”。 真正的连接关系是： 日志中的关键信息可以分成两类： 其中： 因此，应该加入 trustedProxies 的不是路由器地址，而是本机 loopback 地址。 正确方向是： 不应在证据不足的情况下把路由器地址加入 trusted proxy。因为当前证据只说明路由器地址出现在 forwarded header 中，并不是它直接连接 OpenClaw Gateway。 问题二：配置变更需要重启才能生效 设置 gateway.trustedProxies 后，日志出现了新的提示： 这说明 OpenClaw 已检测到配置变化，但该项不能热重载，必须重启 Gateway 才能生效。 这里有一个重要判断： …