1. 服务器上的 Agent 为什么总在“失忆”如果你在服务器上跑过 AI Agent大概率遇到过这种场景任务执行到第 30 步网关因为一次 OOM 被系统杀掉重启之后 Agent 一脸茫然之前分析到一半的代码库、写到第三章的报告、已经调用过的工具结果全部归零。你只能从头再来而它可能在第 28 步又挂一次。这不是模型能力问题是会话状态管理的问题。大多数 Agent 框架把会话当成一个内存里的线程进程活着会话就在进程一死会话就没了。OpenClaw.NET 在 PR #174 里换了一条路——把会话当成状态而不是线程用 SQLite 检查点把状态落到磁盘让 Agent 在服务器重启后还能从断点继续。这篇就围绕这套机制给你一份能直接复制的config.toml配置骨架以及检查点写入、恢复、验证的具体动作。适合谁看在自有服务器上部署 Agent、希望任务能跨重启续跑的后端开发者正在评估 Agent 持久化方案、想搞清楚检查点粒度怎么选的架构同学。读完你能拿到一套可运行的配置并知道每个参数在什么场景下该调。2. 前置准备TaoToken 统一 Key 与 API 通道在拆配置之前先把模型调用通道理顺。OpenClaw.NET 的 Agent 运行时需要访问大模型我建议用 TaoToken 做统一入口好处是 Key 和 API 地址集中管理后面换模型或加并发不用改一堆地方。官网入口在这里https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 注册后在控制台创建 API Key。API 基地址是https://taotoken.net/api这个地址不加 UTM 参数直接填进配置即可。你需要准备三样东西一个可用的 API Key形如sk-开头的一串字符API Base URLhttps://taotoken.net/api想用的模型名比如claude-sonnet-4-20250514或你账号下可用的其他模型控制台里可以随时查看用量和余额API Keys 页面能创建、吊销 Key。如果你后面要跑长期编码或 Agent 任务可以了解下 Coding Plan它更适合高频、长会话的调用场景。注意Key 不要硬编码进提交到 Git 的配置文件用环境变量注入下面配置骨架里我会用${TAOTOKEN_API_KEY}这种占位写法。3. 可复制的 config.toml 配置骨架OpenClaw.NET 的配置分几块模型通道、会话存储、检查点、后台执行、启动自愈。下面这份骨架可以直接拿去改我按功能分区加了注释。# 模型通道TaoToken 统一入口 [llm] provider openai-compatible base_url https://taotoken.net/api api_key ${TAOTOKEN_API_KEY} # 从环境变量注入别写死 model claude-sonnet-4-20250514 max_tokens 8192 timeout_seconds 120 # 会话存储SQLite 作为状态锚点 [session] # 会话是状态不是线程。存储层是唯一的“状态锚点” store sqlite sqlite_path /var/lib/openclaw/sessions.db # 热路径内存缓存上限超出按 LastActiveAt 淘汰 active_capacity 512 # 淘汰的会话完整保留在 SQLite下次消息到达时回水合 eviction_policy lru_last_active # 检查点工具调用批次完成后的“存档点” [checkpoint] enabled true # 在工具调用批次完成、进入下一步推理的接缝处写入 write_on tool_batch_complete # 检查点 ID 存入 BackgroundRunMetadata.LastCheckpointId store sqlite # 保留最近 N 个检查点防止无限增长 retain_last 20 # 后台执行批次续跑 [background] enabled true # 单次 turn 最多迭代步数达到后返回 ShouldContinuetrue max_iterations_per_batch 20 # 后台并发上限与前台请求隔离 max_concurrent_background_turns 3 # 连续无进展轮次阈值达到判定卡死并停止空转 consecutive_no_progress_limit 5 # 后台运行 Token 预算上限超支进入 BudgetLimited 状态 token_budget 200000 # 启动自愈网关重启后自动恢复 [recovery] auto_resume_on_startup true # 错峰启动间隔避免刚恢复的网关被瞬间压垮 auto_resume_stagger_seconds 5 # 恢复并发上限 auto_resume_max_concurrent 3几个参数值得单独说。active_capacity决定内存里同时保留多少会话太小会导致频繁从 SQLite 回水合太大吃内存512 是个中等负载下的稳妥起点。max_iterations_per_batch默认 20意味着一个长任务会被切成多个批次每批结束写一次检查点这是恢复粒度的核心。consecutive_no_progress_limit是防傻跑保险Agent 连续多轮没实质进展就自己停下来不会无限循环烧 Token。token_budget配合会话级的原子计数器TotalInputTokens、TotalOutputTokens 等工作超支后 Agent 进入 BudgetLimited 状态等你处理而不是继续烧钱。4. 检查点写入、恢复与验证配置写好后启动网关然后按下面的步骤验证检查点机制真的在工作。4.1 启动并确认存储初始化export TAOTOKEN_API_KEYsk-你的key openclaw-gateway --config ./config.toml启动日志里应该能看到 SQLite 初始化、后台恢复 worker 启动的记录。如果sqlite_path目录不存在先手动创建并给写权限sudo mkdir -p /var/lib/openclaw sudo chown $(whoami) /var/lib/openclaw4.2 触发一个多批次任务给 Agent 一个需要多步执行的任务比如让它分析一个较大的代码库。观察日志里是否出现批次边界和检查点写入# 查看检查点写入记录 sqlite3 /var/lib/openclaw/sessions.db \ SELECT run_id, last_checkpoint_id, run_state, continuation_count \ FROM background_runs ORDER BY started_at_utc DESC LIMIT 5;正常的话你会看到run_state在 Running 和 Continuing 之间切换continuation_count随批次递增last_checkpoint_id每次批次完成后更新。4.3 模拟重启验证自愈这是最关键的一步。任务跑到一半时直接杀掉网关进程pkill -f openclaw-gateway # 等几秒重新启动 openclaw-gateway --config ./config.toml重启后BackgroundSessionRecoveryWorker会扫描存储找出RunState IN (Running, Continuing) AND Goal IS ACTIVE的会话逐个入队background_auto_resume消息。日志里应该能看到错峰恢复的记录间隔约 5 秒并发不超过 3。再查一次数据库确认continuation_count在重启后继续增长而不是从零开始——这就说明检查点恢复生效了。4.4 验证 Token 审计sqlite3 /var/lib/openclaw/sessions.db \ SELECT session_id, total_input_tokens, total_output_tokens, \ total_cache_read_tokens, total_cache_write_tokens \ FROM token_ledger ORDER BY total_input_tokens DESC LIMIT 5;每个会话的 Token 消耗精确记录配合token_budget就能做成本控制。5. 本篇常见错排查检查点没写入last_checkpoint_id一直是空。先确认[checkpoint] enabled true再看write_on是不是被改成了别的值。检查点只在工具调用批次完成的接缝处写如果任务全是纯推理、没有工具调用就不会触发。另外确认 SQLite 文件有写权限。重启后任务没恢复。检查auto_resume_on_startup是否为 true以及对应会话的 Goal 是否还处于 ACTIVE。Goal 已被取消、状态是 Completed 或 Failed 的会话不会被恢复这是设计如此。如果 Goal 活跃但没恢复看日志里BackgroundSessionRecoveryWorker有没有报错常见原因是存储连接失败。恢复时并发太高把网关压垮。调小auto_resume_max_concurrent调大auto_resume_stagger_seconds。默认 3 并发、5 秒错峰是保守值如果你的网关资源紧张可以再放宽。Token 超预算后 Agent 卡在 BudgetLimited 不动。这是预期行为不是 bug。去数据库里查该会话的 Token 消耗确认预算设置是否合理然后手动调整token_budget或处理该会话。多实例部署时 SQLite 写入排队。单节点 SQLite 没问题但网关水平扩展到多个实例后共享 SQLite 文件的并发写锁会成为瓶颈。这时需要把存储层换成 PostgreSQL 或 MySQLIMemoryStore接口已经抽象好替换成本不高但替换前你得先意识到这个瓶颈存在。6. 把长会话 Agent 真正跑起来配置骨架和验证步骤都给你了接下来就是把它接到你自己的服务器上。模型通道这块用 TaoToken 的 API Keys 页面创建 Key接入文档里有不同语言的调用示例照着填进[llm]段就行。如果你要验证模型是否通、检查点恢复后上下文是否完整可以直接在模型对话里发一条带历史引用的消息看它能不能接上之前的话题。长期跑编码或 Agent 任务的话Coding Plan 比按量调用更适合高频长会话场景预算和并发都更可控。控制台里能实时看用量配合配置里的token_budget成本不会失控。最后提醒一句检查点保证的是 Agent 自己不会重复干活但它管不了外部世界的变化。如果一个检查点记录的是“已调用支付 API”恢复时支付服务端的订单状态可能已经变了。检查点做到工具调用批次粒度是正确取舍但业务层的幂等设计不能省——这个界限用得好很强大用得模糊就会踩坑。
你的 AI Agent 会在服务器上“修仙”——OpenClaw.NET 长持久会话技术解读：从 SQLite 检查点到 config.toml 配置骨架
1. 服务器上的 Agent 为什么总在“失忆”如果你在服务器上跑过 AI Agent大概率遇到过这种场景任务执行到第 30 步网关因为一次 OOM 被系统杀掉重启之后 Agent 一脸茫然之前分析到一半的代码库、写到第三章的报告、已经调用过的工具结果全部归零。你只能从头再来而它可能在第 28 步又挂一次。这不是模型能力问题是会话状态管理的问题。大多数 Agent 框架把会话当成一个内存里的线程进程活着会话就在进程一死会话就没了。OpenClaw.NET 在 PR #174 里换了一条路——把会话当成状态而不是线程用 SQLite 检查点把状态落到磁盘让 Agent 在服务器重启后还能从断点继续。这篇就围绕这套机制给你一份能直接复制的config.toml配置骨架以及检查点写入、恢复、验证的具体动作。适合谁看在自有服务器上部署 Agent、希望任务能跨重启续跑的后端开发者正在评估 Agent 持久化方案、想搞清楚检查点粒度怎么选的架构同学。读完你能拿到一套可运行的配置并知道每个参数在什么场景下该调。2. 前置准备TaoToken 统一 Key 与 API 通道在拆配置之前先把模型调用通道理顺。OpenClaw.NET 的 Agent 运行时需要访问大模型我建议用 TaoToken 做统一入口好处是 Key 和 API 地址集中管理后面换模型或加并发不用改一堆地方。官网入口在这里https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 注册后在控制台创建 API Key。API 基地址是https://taotoken.net/api这个地址不加 UTM 参数直接填进配置即可。你需要准备三样东西一个可用的 API Key形如sk-开头的一串字符API Base URLhttps://taotoken.net/api想用的模型名比如claude-sonnet-4-20250514或你账号下可用的其他模型控制台里可以随时查看用量和余额API Keys 页面能创建、吊销 Key。如果你后面要跑长期编码或 Agent 任务可以了解下 Coding Plan它更适合高频、长会话的调用场景。注意Key 不要硬编码进提交到 Git 的配置文件用环境变量注入下面配置骨架里我会用${TAOTOKEN_API_KEY}这种占位写法。3. 可复制的 config.toml 配置骨架OpenClaw.NET 的配置分几块模型通道、会话存储、检查点、后台执行、启动自愈。下面这份骨架可以直接拿去改我按功能分区加了注释。# 模型通道TaoToken 统一入口 [llm] provider openai-compatible base_url https://taotoken.net/api api_key ${TAOTOKEN_API_KEY} # 从环境变量注入别写死 model claude-sonnet-4-20250514 max_tokens 8192 timeout_seconds 120 # 会话存储SQLite 作为状态锚点 [session] # 会话是状态不是线程。存储层是唯一的“状态锚点” store sqlite sqlite_path /var/lib/openclaw/sessions.db # 热路径内存缓存上限超出按 LastActiveAt 淘汰 active_capacity 512 # 淘汰的会话完整保留在 SQLite下次消息到达时回水合 eviction_policy lru_last_active # 检查点工具调用批次完成后的“存档点” [checkpoint] enabled true # 在工具调用批次完成、进入下一步推理的接缝处写入 write_on tool_batch_complete # 检查点 ID 存入 BackgroundRunMetadata.LastCheckpointId store sqlite # 保留最近 N 个检查点防止无限增长 retain_last 20 # 后台执行批次续跑 [background] enabled true # 单次 turn 最多迭代步数达到后返回 ShouldContinuetrue max_iterations_per_batch 20 # 后台并发上限与前台请求隔离 max_concurrent_background_turns 3 # 连续无进展轮次阈值达到判定卡死并停止空转 consecutive_no_progress_limit 5 # 后台运行 Token 预算上限超支进入 BudgetLimited 状态 token_budget 200000 # 启动自愈网关重启后自动恢复 [recovery] auto_resume_on_startup true # 错峰启动间隔避免刚恢复的网关被瞬间压垮 auto_resume_stagger_seconds 5 # 恢复并发上限 auto_resume_max_concurrent 3几个参数值得单独说。active_capacity决定内存里同时保留多少会话太小会导致频繁从 SQLite 回水合太大吃内存512 是个中等负载下的稳妥起点。max_iterations_per_batch默认 20意味着一个长任务会被切成多个批次每批结束写一次检查点这是恢复粒度的核心。consecutive_no_progress_limit是防傻跑保险Agent 连续多轮没实质进展就自己停下来不会无限循环烧 Token。token_budget配合会话级的原子计数器TotalInputTokens、TotalOutputTokens 等工作超支后 Agent 进入 BudgetLimited 状态等你处理而不是继续烧钱。4. 检查点写入、恢复与验证配置写好后启动网关然后按下面的步骤验证检查点机制真的在工作。4.1 启动并确认存储初始化export TAOTOKEN_API_KEYsk-你的key openclaw-gateway --config ./config.toml启动日志里应该能看到 SQLite 初始化、后台恢复 worker 启动的记录。如果sqlite_path目录不存在先手动创建并给写权限sudo mkdir -p /var/lib/openclaw sudo chown $(whoami) /var/lib/openclaw4.2 触发一个多批次任务给 Agent 一个需要多步执行的任务比如让它分析一个较大的代码库。观察日志里是否出现批次边界和检查点写入# 查看检查点写入记录 sqlite3 /var/lib/openclaw/sessions.db \ SELECT run_id, last_checkpoint_id, run_state, continuation_count \ FROM background_runs ORDER BY started_at_utc DESC LIMIT 5;正常的话你会看到run_state在 Running 和 Continuing 之间切换continuation_count随批次递增last_checkpoint_id每次批次完成后更新。4.3 模拟重启验证自愈这是最关键的一步。任务跑到一半时直接杀掉网关进程pkill -f openclaw-gateway # 等几秒重新启动 openclaw-gateway --config ./config.toml重启后BackgroundSessionRecoveryWorker会扫描存储找出RunState IN (Running, Continuing) AND Goal IS ACTIVE的会话逐个入队background_auto_resume消息。日志里应该能看到错峰恢复的记录间隔约 5 秒并发不超过 3。再查一次数据库确认continuation_count在重启后继续增长而不是从零开始——这就说明检查点恢复生效了。4.4 验证 Token 审计sqlite3 /var/lib/openclaw/sessions.db \ SELECT session_id, total_input_tokens, total_output_tokens, \ total_cache_read_tokens, total_cache_write_tokens \ FROM token_ledger ORDER BY total_input_tokens DESC LIMIT 5;每个会话的 Token 消耗精确记录配合token_budget就能做成本控制。5. 本篇常见错排查检查点没写入last_checkpoint_id一直是空。先确认[checkpoint] enabled true再看write_on是不是被改成了别的值。检查点只在工具调用批次完成的接缝处写如果任务全是纯推理、没有工具调用就不会触发。另外确认 SQLite 文件有写权限。重启后任务没恢复。检查auto_resume_on_startup是否为 true以及对应会话的 Goal 是否还处于 ACTIVE。Goal 已被取消、状态是 Completed 或 Failed 的会话不会被恢复这是设计如此。如果 Goal 活跃但没恢复看日志里BackgroundSessionRecoveryWorker有没有报错常见原因是存储连接失败。恢复时并发太高把网关压垮。调小auto_resume_max_concurrent调大auto_resume_stagger_seconds。默认 3 并发、5 秒错峰是保守值如果你的网关资源紧张可以再放宽。Token 超预算后 Agent 卡在 BudgetLimited 不动。这是预期行为不是 bug。去数据库里查该会话的 Token 消耗确认预算设置是否合理然后手动调整token_budget或处理该会话。多实例部署时 SQLite 写入排队。单节点 SQLite 没问题但网关水平扩展到多个实例后共享 SQLite 文件的并发写锁会成为瓶颈。这时需要把存储层换成 PostgreSQL 或 MySQLIMemoryStore接口已经抽象好替换成本不高但替换前你得先意识到这个瓶颈存在。6. 把长会话 Agent 真正跑起来配置骨架和验证步骤都给你了接下来就是把它接到你自己的服务器上。模型通道这块用 TaoToken 的 API Keys 页面创建 Key接入文档里有不同语言的调用示例照着填进[llm]段就行。如果你要验证模型是否通、检查点恢复后上下文是否完整可以直接在模型对话里发一条带历史引用的消息看它能不能接上之前的话题。长期跑编码或 Agent 任务的话Coding Plan 比按量调用更适合高频长会话场景预算和并发都更可控。控制台里能实时看用量配合配置里的token_budget成本不会失控。最后提醒一句检查点保证的是 Agent 自己不会重复干活但它管不了外部世界的变化。如果一个检查点记录的是“已调用支付 API”恢复时支付服务端的订单状态可能已经变了。检查点做到工具调用批次粒度是正确取舍但业务层的幂等设计不能省——这个界限用得好很强大用得模糊就会踩坑。
