Paperclip Claude Code 适配器恢复会话遇到 previous_message_id 400 报错怎么排查【免费下载链接】paperclipThe open-source app everyone uses to manage agents at work项目地址: https://gitcode.com/GitHub_Trending/papercl/paperclip当你使用 Paperclip 的claude_local适配器本地运行 Claude Code CLI执行 issue 时如果上一次运行留下了一个中毒的会话下一次心跳恢复会话resume时会在日志或 issue 线程里反复看到这条报错API Error: 400 diagnostics.previous_message_id: must be the id from a prior /v1/messages response (starts with msg_)它不是一个偶发的网络问题而是确定性的只要不处理同一个 issue 的每次 resume 都会被 Anthropic 的/v1/messages拒绝。本文说明这个错误的成因、适配器已经内置的自动恢复机制、如何验证恢复是否生效以及如何清理在修复版本之前就已经卡死的遗留会话行。参考文档见 docs/adapters/claude-local.md。错误成因中毒的会话转录文件Claude Code CLI 会为每个会话在磁盘上维护一个 JSONL 转录文件路径是claude-config-dir/projects/encoded-cwd/sessionId.jsonl其中encoded-cwd是把工作目录中的非字母数字字符替换成-得到的编码目录名。如果该转录文件中某条assistant记录的message.id没有msg_前缀即previous_message_id畸形那么之后每一次针对这个会话的--resume都会收到上面的 400。危害在于会话状态的连锁反应Paperclip 的claude_local适配器会在心跳之间持久化 Claude Code 的 session id以便下次唤醒时恢复完整上下文。如果不加防护Paperclip 会把同一个中毒的 session id 反复写回任务会话存储issue 就会被永久卡死stranded。注意区分另一种 resume 失败文档中提到的 unknown session error会话不存在之类是另一类问题适配器同样会用全新会话自动重试而previous_message_id400 是转录内容本身被污染需要下面这套专门的防护逻辑。适配器内置的自动恢复v2026.618.0 起会话自愈修复随 Paperclip v2026.618.0 发布见 releases/v2026.618.0.md 中 Adapter session self-healing 条目claude_localrecovers from a poisonedprevious_message_id400。如果你的实例版本包含该修复适配器看到这条 400 后会自动执行三步不需要人工介入Auto-rotate on resume如果某次--resume尝试返回这个 400适配器会用一个全新会话重试一次并best effort从本地 Claude 配置目录删除中毒的session.jsonl之后一直使用新的 session id。Validate-before-persist携带这个 400 的结果其session_id永远不会被写回任务会话存储——即使 Claude Code 在 result 事件中输出了 session id。适配器返回sessionId: null、sessionParams: null以及errorCode: claude_poisoned_previous_message_id。Clear-on-error适配器在结果上设置clearSession: true触发 heartbeat 服务丢弃该 issue 已持久化的会话行clearTaskSessions。下一次续跑从干净状态开始。验证确认防护是否生效生产环境看到这条 400 时的排查顺序与文档的 on-call checklist 一致先查 run 行的errorCode。确认它是claude_poisoned_previous_message_id——这说明上面三道防护正确触发了issue 会在下一次心跳自动恢复。这是最常见的结局通常排查到此为止。如果同一个 issue 在一个心跳之后仍在循环报错检查该(agentId, taskKey)对应的agentTaskSessions记录是否已被清除。如果没有被清除说明适配器的返回值丢失了例如 run finalization 格式异常。此时应升级处理不要手动编辑数据库行而是建一个子 issue 并附上 run id。远程执行目标sandbox/SSH的边界中毒的 JSONL 文件在远端适配器只记录清理意图不会真正删除远端文件。这不影响恢复——全新会话重试使用新的 session id 仍然会成功且服务端的clearSession: true以服务器状态为准与远端磁盘状态无关。清理修复前卡死的遗留会话行如果你的实例在适配器修复上线之前就存在被 400 卡死的会话旧版本或升级前已经 stranded 的行仓库提供一个一次性清理脚本 clean-poisoned-claude-sessions.ts用于回补修复那些在 adapter 修复发布前就被卡死的agent_task_sessions行。脚本会扫描所有claude_local适配器、且sessionParamsJson非空的会话行逐个读取对应 JSONL 分类最后一条assistant记录的message.id不以msg_开头即判定为 poisoned没有任何 assistant 记录的会话不会被动可以安全地从头 resume远程执行目标的行会被跳过skipped_remote。先以 dry-run 预览只报告、不删除tsx packages/db/scripts/clean-poisoned-claude-sessions.ts \ --config /path/to/paperclip/config.json \ --dry-run在 Paperclip 源码 checkout 的 shell 中也可以pnpm --filter paperclipai/db exec tsx scripts/clean-poisoned-claude-sessions.ts --dry-run关键参数的适用条件--config path指向 Paperclip 实例的config.json默认解析$PAPERCLIP_HOME/config.json或~/.paperclip/instances/default/config.json。脚本从该配置解析数据库连接postgres模式读取database.connectionString内嵌 Postgres 模式则使用postgres://paperclip:paperclip127.0.0.1:embeddedPostgresPort/paperclip端口默认 54329。--database-url url完全覆盖数据库连接串优先级最高。--claude-config-dir path覆盖 Claude CLI 配置目录默认为$CLAUDE_CONFIG_DIR或~/.claude必须与实际存放 JSONL 的位置一致否则会把行误判为missing_jsonl。--json以单个 JSON 摘要输出代替人类可读的行。dry-run 的副作用范围说明它只读数据库并读取 JSONL 文件不做任何写入。确认可清理清单无误后去掉--dry-run再跑一次脚本会把这些 poisoned 行从agentTaskSessions表中删除——这是脚本唯一的写操作。脚本是幂等的即使没有任何行被修复也以退出码 0 结束。输出摘要中的计数字段含义scanned扫描总数、healthy、poisoned、missingJsonlJSONL 已不存在的行默认跳过、noAssistantEntries、skippedRemote、skippedNoSession、unreadable、deleted实际删除行数、dryRun。如果存在引用了已不存在 JSONL 的会话行且你希望一并清掉可以加--delete-missing-jsonl不加的话这些行只会被报告跳过[skip] missing jsonl ...。清理完成后对应的 issue 不再持有中毒的 session id下一次心跳以全新会话续跑。如果清理后某个 issue 仍持续循环回到上一节的第 2 条按agentTaskSessions是否被清除来判断是否升级处理。适用前提回顾以上排查针对claude_local适配器本地需有claude命令且适配器或环境中有ANTHROPIC_API_KEY、CLAUDE_CODE_OAUTH_TOKEN或宿主机环境之一或可用的 Claude Code 订阅登录。配置字段与认证细节见 docs/adapters/claude-local.md。【免费下载链接】paperclipThe open-source app everyone uses to manage agents at work项目地址: https://gitcode.com/GitHub_Trending/papercl/paperclip创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考