代理运行时架构
OpenClaw 拥有内置代理运行时。运行时代码位于 src/agents/ 下,模型/提供商传输位于 src/llm/ 下,openclaw/plugin-sdk/* 桶文件暴露面向插件的契约。
运行时布局¶
| 路径 | 负责内容 |
|---|---|
src/agents/embedded-agent-runner/ |
内置尝试循环(run.ts、run/)、模型选择和提供商规范化(model*.ts)、按提供商的请求参数(extra-params.*)、压缩、转录与会话接线。 |
src/agents/sessions/ |
会话持久化(session-manager.ts)、资源发现(package-manager.ts、resource-loader.ts)、会话内 extensions 加载、提示模板、技能、主题,以及基于 TUI 的工具渲染器(tools/)。 |
packages/agent-core/ |
可复用代理核心(@openclaw/agent-core):代理循环、harness 类型、消息、压缩辅助函数、提示模板、技能以及会话存储契约。 |
src/agents/runtime/ |
OpenClaw 外观层,将 @openclaw/agent-core 连接到插件 SDK LLM 运行时,并重新导出它以及本地代理工具。 |
src/agents/agent-tools*.ts |
OpenClaw 拥有的工具定义、参数模式、工具策略、工具调用前后适配器,以及主机/沙箱编辑工具。 |
src/agents/agent-hooks/ |
内置运行时钩子:压缩保护、压缩指令、上下文修剪。 |
src/agents/harness/ |
内置和插件注册的 harness 的注册表、选择策略和生命周期。 |
src/llm/ |
模型/提供商注册表、传输辅助函数,以及特定提供商的流实现(src/llm/providers/)。 |
边界¶
核心通过 OpenClaw 模块和 SDK 桶文件调用内置运行时。不再保留外部代理框架包。插件使用有文档记录的 openclaw/plugin-sdk/* 入口点,并且不导入 src/** 内部实现。
@earendil-works/pi-tui 仍然是第三方依赖:一个终端组件工具包,供本地 TUI 和会话工具渲染器使用。将其内部化将是一项单独的 vendoring 工作。
清单¶
资源包在 package.json 元数据中声明 OpenClaw 资源。条目是相对于包根目录的文件路径或 glob:
{
"openclaw": {
"extensions": ["extensions/index.ts"],
"skills": ["skills/*.md"],
"prompts": ["prompts/*.md"],
"themes": ["themes/*.json"]
}
}
未在清单中列出的资源类型会回退到对约定目录 extensions/、skills/、prompts/ 和 themes/ 的发现。
运行时选择¶
- 内置运行时 id 为
openclaw。旧别名pi会规范化为openclaw。别名codex-app-server会规范化为codex。 - 插件 harness 会注册额外的运行时 id(例如
codex)。 - 运行时策略是模型/提供商范围的
agentRuntime.id配置(模型条目优先于提供商条目)。未设置或default会解析为auto。 auto会选择支持有效提供商路由的已注册插件 harness,否则选择内置 OpenClaw 运行时。仅提供商或模型前缀永远不会选择 harness。- OpenAI 可能会隐式选择
codex。这仅发生在精确的官方 HTTPS Platform Responses 或 ChatGPT Responses 路由且没有作者请求覆盖时。Completions 适配器、自定义端点以及具有作者请求行为的路由仍保持为openclaw。明文官方 HTTP 端点会被拒绝。参见 OpenAI 隐式代理运行时。
模型运行时代¶
Gateway 启动以及配置、插件或身份验证发布会为每个已配置代理构建一个准备好的模型运行时代。每一代将发现的 auth 模板、模型注册表和投影模型目录作为一个原子快照拥有。代理运行从该快照分叉可变 auth 和注册表存储。浏览、状态、cron、doctor、TUI、PDF 和图像路径读取已发布的目录,而不是重复文件系统发现。
独立嵌入式运行时在其激活边界发布相同形状的快照。失败或过时的代永远不会与较新的部分代一起提供服务。生命周期所有者必须先发布完整替换。
运行时选择在成为所有者键之前会在请求代理的作用域内解析。租约准入会携带该准备好的选择并读取确切所有者的快照。重试必须观察到变更的所有者或发布门;未变更的发布状态会以可重试错误失败,而不是阻塞 Gateway 事件循环。
计算 worker¶
代码模式执行、压缩规划和文件工具规划使用可复用的 WorkerTaskPool。
其调度器和任务协议位于私有 @openclaw/worker-runtime
包中。OpenClaw 主机适配器拥有原生 worker 创建、资源保管
和进程核算。插件使用公开的
worker SDK 入口。
该包将任务结果、执行结算和资源释放作为独立事实保留。一个保留的任务可以在其所有者仍持有工作器和输入占用时返回结果。原生操作、数据库资源和清理回执使这种区分成为必要;仅靠通用任务队列无法替代这些所有者。 包贡献者指南 解释了宿主边界、异步上下文生命周期和可复现基准测试。
这些计算池在调用方隔离环境中共享 max(1, availableParallelism() - 1) 的 CPU 准入限制,并尽可能为 Gateway 保留一个 CPU。有序数据库和模型生成工作器保留其现有独立限制。
读取池即使在多 CPU 主机上也限制为两个工作器;额外的读取隔离环境只会复制已加载的代码和缓存,对队列已经很短的工作负载没有帮助。计算池保留四个工作器的上限,而写入器和单例保持串行。池按需创建工作器,并使用其现有空闲退役机制。物理会话磁盘核算使用读取器限制,使独立存储能够并发扫描,而无需为每个存储创建工作器。 共享状态读取器保留至少两个槽位,因此已持有的结算读取不会阻塞新的目录读取。前台转录和 SQLite 代理池保留各自独立的规模策略。
文件工具工作器执行纯编辑匹配、Unicode 规范化和差异计算。一个已准备的补丁同时提供显示回执和统一补丁回执,包括预览。文件工具调用方保留变更队列、文件系统访问、持久化字节验证和权限检查;它会在规划后、修改文件前重新验证权限和取消状态。写入回执保留其现有大小和编辑距离限制。 共享运行时进程注册表会在已安装的包和密封的 portable-worker 包中解析规划工作器。
准入包括排队中、准备中和运行中的任务。每个池默认 128 个待处理任务和 256 MiB 生产者报告的保留输入;计算池也共享这些待处理限制。生产者提供已知输入大小,无需额外的序列化遍历。这限制的是报告的输入保留量,而不是工作器总堆使用量。超额工作会以 WorkerTaskError.code = "overloaded" 失败。
取消会保留执行许可和输入预留,直到工作器停止且异步输入准备完成。如果初始停止成功,结果拒绝将遵循其执行回执,而无需等待准备。失败的停止可以更早拒绝,同时保留原生托管和待处理回执以便重试。成功的池关闭会合并剩余的准备和输入清理;优雅轮换可以在被取消的准备完成前结束。
等待中的计算池会向代码模式宿主交换请求检查点,以便嵌套工作能够推进。空闲工作器会释放 CPU 准入,并在池的空闲超时后退役。本地 node:diagnostics_channel 对 openclaw.worker.task 的订阅者可以观察队列、准备、执行墙钟时间、消息传输时间以及待处理任务/输入计数。这些事件不包含任务输入;执行墙钟时间包括工作器启动和宿主等待。
相关¶
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw