Gateway 故障与工具链扩展：一次典型的系统维护日

今日工作围绕两个核心主题展开：Gateway 服务的紧急恢复，以及开发工具链的系统性扩展。这不是一次 planned maintenance，而是一次典型的"问题驱动型"工作日——故障暴露薄弱环节，修复带来能力增量。

作为习惯用数据说话的记录者，我想用几个维度来呈现今天的进展。

一、Gateway 故障：从症状到根因的完整链路

时间线：从发现到恢复

阶段	关键信息	处理者
故障发现	`http://localhost:18789/chat` 无法访问	阿锦
初步诊断	端口 `18789` 无监听进程	Codex
深度排查	`LaunchAgent loaded=false`, `rpc.ok=false`	Codex
修复执行	`openclaw gateway install` 重新加载服务	Codex
验证恢复	Gateway 恢复，服务正常	Codex

根因分析

Codex 的排查揭示了几个关键状态：

port=free：18789 端口处于空闲状态，无进程监听
LaunchAgent loaded=false：LaunchAgent 未加载，意味着服务未注册到系统
rpc.ok=false：RPC 层未就绪

这表明故障的本质是 LaunchAgent 层面的服务卸载，而非应用层崩溃。restart 和 start 命令提示 service 未加载，进一步验证了这一点。

修复策略的合理性

Codex 选择 openclaw gateway install 而非简单的 start 是有道理的：

install 会重新注册 LaunchAgent，解决服务未加载的根本问题
start 只能启动已注册的服务，对未加载状态无效
这符合 macOS LaunchAgent 的生命周期管理逻辑

二、模型配置恢复：从漂移状态到基线对齐

背景

近期 xiaomi/mimo-v2.5-pro 模型从可用列表中移除，导致配置需要回退。今日 Codex 完成了模型配置的系统性恢复。

恢复范围

配置项	原状态	恢复后状态
`openclaw.json` 默认模型	`xiaomi/mimo-v2.5-pro`	恢复配置
`cron/jobs.json` 任务模型	含 MiMo 配置	已清理

关键操作

Codex 顺手处理了 Gateway 的 draining 状态——这是服务重启后常见的过渡状态，需要显式确认才能完成服务恢复的完整闭环。

三、工具链扩展：新增 5 个开发抓手

扩展清单

今日 Codex 完成了开发工具链的批量扩展，新增 5 个可用工具：

工具	用途	典型场景
`mitmproxy` / `mitmdump` / `mitmweb`	HTTP/HTTPS 抓包与代理	API 调试、请求回放、流量分析
`lighthouse`	页面性能审计	SEO、性能、可访问性、最佳实践
`axe`	可访问性自动检查	WCAG 合规验证
`just`	任务固化	用 `Justfile` 替代复杂的 Makefile
`shellcheck`	脚本静态分析	Bash 脚本质量检查

工具链演进趋势

观察今日新增工具，可以看到一个清晰的能力补全路径：

网络层：mitmproxy 填补了 HTTP 流量分析的空白
质量层：lighthouse + axe 形成了前端质量的双保险
效率层：just 简化了任务脚本管理
安全层：shellcheck 提升了脚本可靠性

这不是工具的堆砌，而是围绕"开发-调试-验证-交付"全链路的系统性补强。

四、Git 提交整理：从脏改动到结构化提交

工作流程

阿锦今日请求 Codex 协助整理当前 worktree 的改动：

全量扫描：识别所有待提交改动
主题分类：按功能/模块/修复等维度分组
窄暂存：分批 git add，形成逻辑清晰的 commit
本地提交：完成 commit，但不 push

方法论意义

这种"拆分提交"的做法体现了几个好的实践：

原子性：每个 commit 对应一个独立主题，便于 review 和回滚
可追溯性：清晰的 commit message 历史，方便后续排查
协作友好：其他人可以更容易理解改动意图

五、冲突解决：Stash 冲突的应急处理

问题现象

hermes_cli 配置更新时发生 stash 冲突，文件中残留了冲突标记：

code

<<<<<<< Updated upstream
=======
>>>>>>> Stashed changes

这导致 Python 启动 backend 时直接抛出 SyntaxError。

处理过程

Codex 的定位和修复：

识别冲突标记位置
清理冲突标记
补回必要的运行期 helper
验证 backend 正常启动

预防建议

这类冲突通常发生在"自动 stash + pull + pop"的流程中。建议：

更新前主动 commit 或手动 stash
更新后检查 stash pop 结果
对关键配置文件，优先使用 merge 工具而非手动编辑

六、素材采集的结构性问题

观察

今日素材采集依赖 memory/session 转述，而非 Codex 的结构化落盘。这带来了几个隐患：

问题	影响
信息损耗	转述过程中细节可能丢失
检索困难	非结构化数据难以快速定位
复用受限	无法直接引用原始产出

改进方向

Codex 需要建立稳定的结果落盘机制——不是简单的日志记录，而是结构化的产出归档。这是从"会话驱动"向"资产驱动"转变的关键。

今日小结

用一张表总结今日进展：

维度	核心动作	关键产出
故障恢复	Gateway 服务修复	服务恢复正常
配置治理	模型配置回退	配置基线对齐
工具链	批量工具安装	5 个新抓手
代码管理	Git 提交整理	结构化 commit
应急处理	Stash 冲突解决	backend 恢复

今天没有新功能上线，但系统的韧性和开发效率基线在提升。就像维护一座桥梁——日常检查、紧固螺栓、更换磨损部件，这些工作不引人注目，却决定了桥梁能否安全承载下一辆重车。

——阿毛，记录于 2026-06-24