跳转至

Agent 运行时架构

OpenClaw 拥有内置代理运行时。运行时代码位于 src/agents/ 下，模型/提供商传输位于 src/llm/ 下，openclaw/plugin-sdk/* barrel 文件暴露面向插件的契约。

运行时布局

路径 负责内容
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 加载、Prompt 模板、技能、主题，以及基于 TUI 的工具渲染器（tools/）。
packages/agent-core/ 可复用代理核心（@openclaw/agent-core）：代理循环、harness 类型、消息、压缩辅助函数、Prompt 模板、技能以及会话存储契约。
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 barrel 文件调用内置运行时。不再保留外部代理框架包。插件使用已文档化的 openclaw/plugin-sdk/* 入口点，并且不导入 src/** 内部实现。

@earendil-works/pi-tui 仍然是第三方依赖：一个由本地 TUI 和会话工具渲染器使用的终端组件工具包。将其内部化将是一项独立的依赖内嵌工作。

清单

资源包在 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 启动以及配置、插件或身份验证发布会为每个已配置代理构建一个准备好的模型运行时代际。每个代际拥有已发现的身份验证模板、模型注册表和投影模型目录，并将其作为一个原子快照。代理运行从该快照分叉可变身份验证和注册表存储。浏览、状态、cron、doctor、TUI、PDF 和图像路径读取已发布的目录，而不是重复文件系统发现。

独立嵌入式运行时在其激活边界发布相同的快照形状。失败或过期的代际永远不会与较新的部分代际一起提供服务。生命周期所有者必须先发布完整替换。

运行时选择在成为所有者键之前，会在请求代理的作用域内解析。租约准入会携带该准备好的选择继续，并读取确切所有者的快照。重试必须观察到变更的所有者或发布门；未变更的发布状态会以可重试错误失败，而不是阻塞 Gateway 事件循环。

计算工作器

代码模式执行、压缩规划和文件工具规划使用可复用的 WorkerTaskPool。它们的池在调用 isolate 内共享 max(1, availableParallelism() - 1) 的 CPU 准入限制，并尽可能为 Gateway 保留一个 CPU。有序数据库和模型生成工作器保留其现有的独立限制。

文件工具工作进程执行纯编辑匹配、Unicode 归一化和差异计算。一个已准备的补丁同时提供显示回执和统一补丁回执，包括预览。文件工具调用方保留变更队列、文件系统访问、持久化字节验证和权限检查；它在规划之后、修改文件之前重新验证权限和取消状态。写入回执保留其现有的大小和编辑距离限制。 共享运行时进程注册表在已安装包和密封的可移植工作进程包中解析规划工作进程。

准入包括排队中、准备中和运行中的任务。每个池默认有 128 个待处理任务和 256 MiB 的生产者报告的保留输入；计算池也共享这些待处理限制。生产者提供已知输入大小，无需额外的序列化遍历。这限制的是报告的输入保留量，而不是工作进程的总堆内存使用量。超额工作会以 WorkerTaskError.code = "overloaded" 失败。 取消会保留执行许可和输入预留，直到工作进程停止且异步输入准备完成。如果初始停止成功，结果拒绝将跟随其执行回执，而无需等待准备。失败的停止可以更早拒绝，同时保留原生托管和待处理回执以便重试。成功的池关闭会连接剩余的准备工作与输入清理；优雅轮换可以在已取消的准备完成之前结束。

等待中的计算池会从代码模式主机交换请求检查点，以便嵌套工作能够推进。空闲工作进程会释放 CPU 准入，并在池的空闲超时后退出。本地 node:diagnostics_channel 对 openclaw.worker.task 的订阅者可以观察队列、准备、执行墙钟时间、消息传输时间以及待处理任务/输入计数。这些事件不包含任务输入；执行墙钟时间包括工作进程启动和主机等待。

本页原文 Markdown：在 AtomGit 查看·内容源自开源项目 cl/openclaw