迁移同步 SQLite API

将同步 SQLite SDK 调用迁移到下面等待或准备的替换。 最终兼容日是 2026 年 12 月 31 日 （2026-12-31）。 删除在 2027 年 1 月第一个稳定版本 中发货，没有插件 SDK 主要版本。此弃用版本保留了列出的合约；它不会删除它们。请参阅 移除时间表 了解释放和装运表面闸门。

从您的插件使用的系列开始。对于直接替换 Async，保留参数并等待结果。返回适配器或准备好的读取器的工厂可以保持同步：等待对返回对象的操作，如下所述。围绕本机数据库回调的 Promise 返回包装器仍然在调用者的线程上运行该回调；迁移回调合约，而不仅仅是其调用站点。

这些更改保留了存储的数据、架构、保留和更新行为。在读取其结果或发布外部效果之前等待写入。切勿通过已弃用的同步路径重试失败的等待操作。捆绑插件以当前主机为目标，不需要旧主机后备。外部插件应该声明提供它们使用的功能的主机版本。

Session 读取和入站信封

使用 session-store-runtime 进行会话读取器，使用 channel-inbound 进行准备好的信封结构。相同的方法映射适用于 api.runtime.agent.session 和通道运行时别名。

// Beforeconst entry = api.runtime.agent.session.getSessionEntry(target);// Afterconst entry = await api.runtime.agent.session.getSessionEntryAsync(target);

历史记录密钥解析器包括会话重置后保留的 session_windows。 getSessionEntryByIdAsync(...).sessionKey 不能替代历史查找。查看精确历史查找合约。

每条入站消息准备一次信封生成器。它返回一个同步格式化程序，生成正文字符串；旧的通用构建器返回 { storePath, body }。如果调用者仍然需要存储路径，请从同一配置的存储中解析它并通过 runtime.channel.session.resolveStorePath 进行路由。对于自定义格式化，等待 readSessionUpdatedAtAsync 一次并将该时间戳传递到格式化程序中，而不是保留数据库读取回调。

listSessionEntriesAsync 返回只读元数据投影，而不是分离的快照，例如保存的技能提示。它不采用同步列表的 readOnly、快照水化或源捕获选项。使用 getSessionEntryAsync 获取完整的公开条目。在现有效果边界保留对转录本或元数据披露的授权。内存统计信息和存档读取器保留在其现有的记录或本地子路径上；此迁移不会将私有主机外观公开。

对于条目写入，用所有者准备或已经准备好的补丁替换不透明回调：

// Before: a callback depends on the stored entry.await patchSessionEntry({ ...target, update: choosePatch });// After: preparation happens outside the transaction; the owner detects conflicts.await prepareSessionEntryPatch({ ...target, prepare: choosePatch });

转换事务本地回调行为时，请参阅 entry 补丁冲突和权限 。

Auth 配置文件和提供商准备情况

使用公共 provider-auth 表面进行配置文件存储和写入。捆绑插件还使用私有 provider-auth-runtime 表面来存储配置文件元数据，使用 agent-sessions 来存储 AuthStorage 和 ModelRegistry。现有的 agent-runtime 和运行时 modelAuth 别名遵循相同的映射；更喜欢焦点公共子路径（如果存在）。

// Beforeconst auth = AuthStorage.forAgent(agentDir, config);auth.set(providerId, credential);// Afterconst auth = await AuthStorage.forAgentAsync(agentDir, config);await auth.setAsync(providerId, credential);

harness应使用主机准备的 params.authStorage。 AuthStorage get、list 和 has 保持对其准备视图的同步读取； login 和 getApiKey 已返回承诺。不要用以前加载的快照替换较新的整个身份验证存储：使用 updateAuthProfileStoreWithLock 进行所有者支持的突变。

物理数据库路径显示在 2026 年 12 月 31 日后停用。外部插件应显示 provider/profile 标识符；所选数据库路径没有公共异步 API。私有捆绑插件帮助程序 AuthStorage.resolvePathForDisplayAsync 保留代理本地与共享数据库选择，包括尚不存在的配置文件的定位器。元数据助手返回 profile/account 身份，并且不是路径替代品。

提供者就绪挂钩添加等待的回调：

// BeforeisConfigured: (context) => isProviderApiKeyConfigured(context),// After// Preserve synchronous SDK callers through 2026-12-31.isConfigured: (context) => isProviderApiKeyConfigured(context),isConfiguredAsync: async (context) => await isProviderApiKeyConfiguredAsync(context),

使用挂钩的现有上下文和特定于提供者的输入。主机等待准备就绪并更喜欢异步钩子；失败的异步挂钩不会通过旧挂钩重试。准备情况结果并不授权以后使用凭证。在 2026 年 12 月 31 日之前保留提供程序类型所需的同步挂钩。捆绑提供程序还保留同步挂钩，以支持公共同步 SDK API 的调用者，直到该日期；普通运行时调用者使用异步钩子。请参阅 auth 和可用性详细信息。

审批路由及命令授权

直接解析器返回承诺。以下名称以Async结尾的工厂仍然同步返回适配器；他们的路由和资格回调返回承诺，主机等待他们。

// Beforeconst auth = resolveCommandAuthorization(input);// Afterconst auth = await resolveCommandAuthorizationAsync(input); // Factory migration: construction itself stays synchronous.const adapter = createChannelApprovalNativeRuntimeAdapterAsync(options);

如果一项操作需要多个路由决策，则准备一次 resolveApprovalRequestSessionDeliveryAsync 并将其 sessionDelivery 传递给助手。将当前的批准、命令执行和交付权限保持在其效果范围内。请参阅 批准路由和导入路径 。

对话和本机会话绑定

使用 createAccountScopedConversationBindingManagerV2 创建当前主机管理器，并使用 registerSessionBindingAdapterV2 注册自定义适配器。 V2 管理器工厂保持同步并返回仅异步接收器。

// Beforeconst manager = createAccountScopedConversationBindingManager(options);const binding = manager.getByConversationId(conversationId);// Afterconst manager = createAccountScopedConversationBindingManagerV2(options);const binding = await manager.getByConversationIdAsync(conversationId);

特定于通道的设置器名称保留在其现有的本地通道表面上。它们不会创建新的跨插件导入。自定义适配器拥有自己的存储，并且必须实现 V2 异步和当前所有者合约。

原生harness必须迁移所有权，而不仅仅是重命名getter：

对于新的工具代码，请遵循 native 会话沿袭 ：等待 resolvePreparedNativeSessionBinding 或 retainNativeSessionGenerationAuthority，使用拥有的捕获，并在 finally 中调用 release()。通过效果和终端清理让主人活下去。冷的或无效的缓存绑定不能替代当前所有者权限。

键控状态

提供显式插件所有者时，使用 api.runtime.state.openKeyedStoreV2 或 plugin-state-store-runtime 中的惰性 createPluginStateKeyedStoreV2 工厂。这些工厂立即返回；他们的方法执行工人操作。

// Beforeconst store = api.runtime.state.openSyncKeyedStore(options);store.register("item", value);const stored = store.lookup("item");// Afterconst store = api.runtime.state.openKeyedStoreV2(options);await store.register("item", value);const stored = await store.lookup("item");

V1 回调方法已经返回承诺，但其不透明的 JavaScript 回调仍然在本机主机事务中执行。不要用无条件查找替换原子更新并写入：

// Beforeawait legacyStore.update("counter", (value) => (value ?? 0) + 1);// Afterconst observed = await store.observe("counter");const result = await store.compareAndApply("counter", observed.comparison, {  operation: "update",  action: "set",  value: (observed.value ?? 0) + 1,});if (result.status === "conflict") {  // Recompute from a new observation or report the conflict to the caller.}

对于 deleteIf，根据观察评估谓词，然后有条件地将 { operation: "delete", action: "delete" } 与该观察的比较应用。冲突意味着没有提交请求的突变。不要重放具有外部副作用的未知写入或回调。有关多键条件和工作器操作，请参阅 键状态迁移。普通的 V1 仅数据方法不是回调删除目标。

SessionManager，扩展持久性和重放

使用 agent-sessions 作为管理器 API。下面的每个持久性方法都必须在读取结果视图或发布依赖效果之前解决。

// Beforeconst manager = SessionManager.open(target);const id = manager.appendCustomEntry("checkpoint", { stage: "ready" });// Afterconst manager = await SessionManager.openAsync(target);const id = await manager.appendCustomEntryAsync("checkpoint", { stage: "ready" });

使用 ExtensionActionsV2、ExtensionRuntimeV2 和 bindCoreAsync 提供等待的扩展操作。原始 action/runtime 类型和 bindCore 不会仅仅因为它们可以托管旧操作而被删除。 SQL-free 准备好的视图获取器、inMemory() 和 fromEntries() 保持同步。有关完成语义和类型，请参阅 session persistence 和 provider replay。

Transcript 写入回调、读取器和目录

// Beforeawait withSessionTranscriptWriteLock(target, async (writer) => {  await writer.appendMessage({ message, prepareMessageAfterIdempotencyCheck: prepareSync });});// Afterawait withSessionTranscriptWrite(target, async (writer) => {  await writer.appendMessage({    message,    preparation: { prepareMessage: prepareAsync, source: sourceAuthority },  });});

准备工作在重复检测之后并在数据库事务之外运行。返回 undefined 以抑制新的追加；副本保留其存储的字节并跳过准备。避免外部可见的副作用发生。新的写入范围不承诺旧回调的本机事务视图或回滚已提交的附加。参见锁定转录本制备。

回复、观察者和harness准备

// BeforesessionObserver.handleEvent(event);// Afterawait sessionObserver.handleEventAsync(event);

onPreparedAgentRunStart仍必须同步返回完成所有权；在调用之前准备好转录事实。等待政策准备并不意味着允许以后执行或披露。在生效前保留宿主当前的权限。参见回复权限和观察者可见性。

帐户服务、运行时配置、工作区和 TTS

// Beforeconst hint = buildTtsSystemPromptHint(config, agentId);// Afterconst prepareHint = api.runtime.tts.buildSystemPromptHintAsync;if (!prepareHint) {  throw new Error("Update OpenClaw to use async TTS prompt preparation.");}const hint = await prepareHint(config, agentId);

捆绑的插件可以每回合调用一次私有 prepareTtsPreferences 并将该结果传递给支持的准备重载。这些 SQL-free 同步重载并未被弃用。外部插件使用上面的公共运行时方法。参见公共TTS制备配方。

调试代理捕获和原始 SQLite

// Beforeconst store = acquireDebugProxyCaptureStore(options);// Afterconst lease = await acquireDebugProxyCaptureStoreAsync(options);try {  // Await capture operations on lease.store.} finally {  await lease.release();}

以下 sqlite-runtime 操作没有机械异步 SQL 包装器。使用 openOpenClawAgentSqliteWorkerStoreV2 和可序列化所有者命令进行普通运行时存储。使用 sqlite-worker-runtime 将本机实现移至配对的工作后端：

// Before: awaiting admission does not move this callback off the host.await withOpenClawAgentDatabaseWrite(options, ({ db }) => updateRows(db, input));// After: updateRows and its transaction belong to the paired worker backend.await store.execute({ type: "updateRows", input }, owner.assertCurrent);

保留显式只读检查、离线 Doctor/CLI 维护保管以及支持的工人本地原语。不要将它们视为网关处理程序中可写本机句柄的权限。请参阅 worker 存储构建、清理和缺失存储语义。

验证迁移

在等待每个迁移所有者的进程内写入后执行一次读取。对于条件状态更新，证明竞争写入会产生冲突而不是丢失。检查回调完成并释放finally中的资源。确认迁移的流不会发出同步 SQLite 弃用警告，并且错误会在没有旧版重试的情况下传播。

本指南涵盖同步 SQLite 删除窗口。不相关的别名、活动兼容性记录、准备好的 SQL-free 重载和 private/internal 实现内核保留自己的合同。一月份删除公共适配器并不授权删除实时安全检查或更改存储的数据。