从零实现 OpenClaw (11)：工程化命门 —— 可观测性、韧性与 WAL 容错

1. 为什么你的 OpenClaw 一崩就“失忆”如果你已经跟着这个系列把 OpenClaw 从单体逻辑一路搭到分布式协作大概率会遇到一个很尴尬的时刻凌晨跑一个长链路任务比如“抓取—移动—放置—回写记录”跑到一半进程挂了重启之后它完全不记得自己刚才干到哪一步甚至可能把已经执行过的动作再执行一遍。这不是模型不够聪明而是工程化没做到位。这一篇要解决的就是这个命门可观测性、韧性与 WAL 容错。简单说可观测性让你知道“它刚才到底做了什么、慢在哪、错在哪”韧性让它在网络抖动、接口 503、硬件瞬断时能优雅重试而不是直接崩WAL预写式日志则保证断电重启后任务进度不丢能断点续传。适合正在自建 AI 工具链、准备把 Agent 从 demo 推向“能过夜跑”的开发者。我会给你一份可复制的config.toml骨架把日志、指标、WAL 回放、故障注入的验证动作都串起来并用 TaoToken 作为统一的模型调用通道让整条链路可复现。全程本地可跟做不需要复杂集群。2. 前置用 TaoToken 统一模型通道与 Key在讲可观测性之前先把“外部依赖”收敛掉。OpenClaw 的韧性设计里最不可控的就是 LLM 接口——超时、限流、偶发 5xx 都会触发重试逻辑。如果每个 Skill 各自直连不同厂商重试策略和日志格式会乱成一锅粥。我的做法是统一走一个兼容 OpenAI 协议的网关这里用 TaoToken。它的作用是一个 Key、一个 Base URL就能调用多种模型省去在config.toml里维护一堆厂商地址和密钥。对可观测性来说统一入口意味着所有 LLM 调用的延迟、状态码、Token 消耗都能在同一个地方打点追踪链路不会断。你需要先拿到 Key进入控制台创建 API Key地址是https://taotoken.net/api-keys。创建后复制保存后面写进配置。接口基址用https://taotoken.net/api注意这个地址不带任何查询参数直接作为base_url使用。注意Key 只存本地环境变量或配置文件不要提交到 Git。建议用.env.gitignore的方式管理。如果你只是想先验证模型通道是否通可以打开模型对话页面手动发一条消息确认返回正常再进入下面的工程化配置。这一步能帮你排除“到底是网关问题还是我代码问题”。3. 可复制配置config.toml 骨架下面这份config.toml是我实测下来比较顺手的骨架把可观测性、韧性、WAL 三块参数都暴露出来方便你按环境调。字段名你可以按自己项目改但结构建议保留。[app] name openclaw env local log_level info # debug / info / warn / error log_format json # json 便于采集本地调试可换 text [llm] provider taotoken base_url https://taotoken.net/api api_key_env TAOTOKEN_API_KEY # 从环境变量读取不写死 model gpt-4o-mini timeout_seconds 30 max_retries 5 [resilience] base_delay_ms 100 max_delay_ms 8000 jitter_ratio 0.5 # 抖动比例0~1 retry_on_status [429, 500, 502, 503, 504] circuit_breaker_threshold 10 # 连续失败多少次熔断 circuit_breaker_cooldown_s 30 [observability] otel_enabled true otel_exporter otlp otel_endpoint http://localhost:4317 metrics_enabled true metrics_port 9090 trace_sample_ratio 1.0 # 本地全采样生产可降到 0.1 [wal] enabled true dir ./data/wal sync_on_write true # 每次写入 fsync保证断电不丢 segment_max_mb 64 recovery_mode resume # resume / skip / manual几个关键点解释一下。sync_on_write true是 WAL 的灵魂代价是每次写盘有 IO 开销但换来断电不丢如果你追求吞吐可以关掉但要接受可能丢最后几条。jitter_ratio控制重试抖动的幅度多 Agent 场景下这个值很重要能避免所有实例同一秒集体重试把下游打崩。trace_sample_ratio本地设 1.0 方便调试生产环境建议降到 0.1 甚至更低否则追踪数据量会很吓人。环境变量这样设置export TAOTOKEN_API_KEY你的Key4. 可观测性落地日志、指标与追踪配置只是骨架真正让系统“透明”的是三件套结构化日志、指标、链路追踪。我按重要性排序讲。4.1 结构化日志先让错误可检索别再用print(doing task)了。把日志打成 JSON每条至少带trace_id、span_id、skill_name、status、latency_ms。这样出问题时你能按trace_id把一次任务的所有日志串起来。import json, logging, time, uuid logger logging.getLogger(openclaw) def log_event(skill_name, status, latency_ms, extraNone): record { ts: time.time(), trace_id: extra.get(trace_id) if extra else str(uuid.uuid4()), skill_name: skill_name, status: status, latency_ms: round(latency_ms, 2), } if extra: record.update(extra) logger.info(json.dumps(record, ensure_asciiFalse))调用时包一层计时start time.time() try: result await run_skill() log_event(MoveTo, OK, (time.time() - start) * 1000) except Exception as e: log_event(MoveTo, ERROR, (time.time() - start) * 1000, {error: str(e)}) raise4.2 指标P99 延迟和成功率才是告警依据日志是事后查指标是事前防。用 Prometheus 客户端暴露几个核心指标LLM 调用延迟直方图、工具调用成功率、Token 消耗速率、WAL 待恢复条目数。from prometheus_client import Histogram, Counter, Gauge, start_http_server LLM_LATENCY Histogram(openclaw_llm_latency_seconds, LLM call latency) TOOL_RESULT Counter(openclaw_tool_calls_total, Tool calls, [skill, status]) WAL_PENDING Gauge(openclaw_wal_pending, Pending WAL entries) start_http_server(9090) # 对应 config 里的 metrics_port在调用处打点import time start time.time() try: resp await call_llm(prompt) TOOL_RESULT.labels(skillllm, statusok).inc() return resp finally: LLM_LATENCY.observe(time.time() - start)WAL_PENDING这个指标特别有用——如果它一直不降说明恢复流程卡住了比看日志快得多。4.3 链路追踪把 Agent 的“思维路径”摊开OpenTelemetry 的价值在于把一次推理拆成树状 Span根 Span 是用户意图子 Span 是向量检索、提示词组装、工具调用孙 Span 是硬件网关通信。这样你一眼就能看出是检索慢还是模型慢。from opentelemetry import trace from opentelemetry.trace import Status, StatusCode tracer trace.get_tracer(openclaw.core) def trace_skill(skill_name: str): def decorator(func): async def wrapper(*args, **kwargs): with tracer.start_as_current_span(fSkill:{skill_name}) as span: span.set_attribute(openclaw.skill_name, skill_name) try: result await func(*args, **kwargs) span.set_status(Status(StatusCode.OK)) return result except Exception as e: span.record_exception(e) span.set_status(Status(StatusCode.ERROR, str(e))) raise return wrapper return decorator配合otel_endpoint指向本地 collector你就能在 Jaeger 或 Grafana Tempo 里看到完整调用链。本地验证时先跑一个简单 Skill确认 Span 能正常上报再上复杂任务。5. 韧性带抖动的指数退避与熔断网络抖动和 503 是常态盲目立即重试会引发惊群效应。核心公式是第 n 次重试等待min(base * 2^n, max_delay) jitter其中 jitter 是随机偏移。import asyncio, random async def resilient_call(func, cfg, max_retries5): for n in range(max_retries): try: return await func() except (TimeoutError, ConnectionError) as e: if n max_retries - 1: raise base cfg[base_delay_ms] / 1000 delay min(base * (2 ** n), cfg[max_delay_ms] / 1000) delay random.uniform(0, delay * cfg[jitter_ratio]) await asyncio.sleep(delay)熔断器是第二道防线连续失败超过circuit_breaker_threshold次就打开冷却cooldown_s秒后再半开试探。这样下游彻底挂掉时你的 Agent 不会一直空转烧 Token。class CircuitBreaker: def __init__(self, threshold, cooldown): self.threshold threshold self.cooldown cooldown self.failures 0 self.opened_at 0 def allow(self): if self.failures self.threshold: return True if time.time() - self.opened_at self.cooldown: self.failures 0 return True return False实测下来加了抖动之后多实例同时重试的峰值明显被削平下游 429 的概率下降不少。6. WAL 容错断电重启后断点续传WAL 的思路来自数据库在执行任何改变外部状态的操作前先把“意图”写盘。执行成功后再写一条完成记录。重启时扫描 WAL找出所有PENDING的条目按幂等性原则决定重放还是跳过。写入格式建议用追加式 JSON Lines每行一条方便回放import json, os, time class WAL: def __init__(self, path): self.path path os.makedirs(os.path.dirname(path), exist_okTrue) def append(self, entry): entry[ts] time.time() with open(self.path, a) as f: f.write(json.dumps(entry, ensure_asciiFalse) \n) f.flush() os.fsync(f.fileno()) # 对应 sync_on_write任务开始时写PENDING成功后写COMPLETEDwal.append({id: 101, action: MoveTo, params: {x: 10}, status: PENDING}) # ... 执行 ... wal.append({id: 101, status: COMPLETED})恢复逻辑def recover(wal_path): pending {} with open(wal_path) as f: for line in f: e json.loads(line) if e[status] PENDING: pending[e[id]] e elif e[status] COMPLETED: pending.pop(e[id], None) return list(pending.values())关键在幂等性MoveTo这类操作如果重复执行结果一致就可以安全重放如果是“累加计数”这种非幂等操作恢复时要先查询真实状态再决定。这一步想清楚断电恢复才不会造成二次事故。7. 验证与故障注入确认它真的能扛配置写完不验证等于没写。我一般做三个动作。第一正常路径验证。跑一个包含 LLM 调用和工具调用的任务确认日志有trace_id、指标端口9090能抓到数据、追踪面板能看到 Span 树。curl -s http://localhost:9090/metrics | grep openclaw_第二故障注入。用tc模拟网络延迟或者直接在代码里让 LLM 调用抛TimeoutError观察重试日志是否按指数退避增长、熔断是否在阈值后打开。async def flaky(): raise TimeoutError(injected) # 观察 resilient_call 的重试间隔第三WAL 回放验证。手动写一条PENDING不写COMPLETED然后重启进程确认recover()能把它捞出来并且openclaw_wal_pending指标先升后降。echo {id:999,action:Test,status:PENDING} ./data/wal/wal.log # 重启后检查恢复日志如果这三步都过你的 OpenClaw 基本具备了“过夜跑”的底气。8. 常见报错排查报错一Connection refused连不上localhost:4317。这是 OTel collector 没起。本地调试可以先关掉otel_enabled或者用docker run起一个 collector。别急着改代码先确认端口在监听。报错二LLM 调用一直 401。多半是TAOTOKEN_API_KEY没导出或者base_url写成了带路径的地址。确认base_url https://taotoken.net/apiKey 从环境变量读取。可以在接入文档里对照请求示例排查。报错三WAL 文件越来越大。说明COMPLETED记录没写或者 segment 没轮转。检查segment_max_mb配置并确认每次成功执行后都追加了完成记录。长期运行建议加一个压缩/归档任务。报错四重试风暴把下游打挂。检查jitter_ratio是不是设成了 0以及熔断阈值是不是太高。多实例部署时抖动是必须的。报错五恢复后任务重复执行。这是幂等性没设计好。恢复前先查询外部真实状态或者给每个操作加唯一id做去重。9. 下一步把通道和编码流固定下来工程化做到这一步可观测性、韧性、WAL 三块就闭环了。接下来最影响日常效率的其实是模型通道和编码工作流的稳定性。如果你打算长期跑 Agent 任务建议把 Key 和通道固定成一套API Key 在控制台统一管理接入细节对照接入文档避免每次换模型都改一遍代码。对于需要长时间编码、跑 Agent 循环的场景可以了解一下 Coding Plan它更适合把模型调用纳入长期工作流如果只是临时验证某个模型的表现直接用模型对话最快。把这几件事固定下来你的 OpenClaw 才算真正从“能跑”变成“敢让它自己跑”。