跳转至

Agents API

Agents API 是什么?

捆绑的 agentsapi 插件将 OpenClaw 内置的代理框架替换为 Agents API 代理框架,后者底层使用 Codex 框架。代理框架运行在 OpenAI 的云端。 它管理对话以及调用模型、使用工具和继续任务的循环。

OpenClaw 将该代理框架连接到你的聊天渠道、个人指令、记忆和已配置的工具。你可以继续通过相同的渠道与助手交互,进度、回复和生成的文件会回传至对话中。

借助本指南中的托管设置,OpenAI 还会提供你的代理运行代码和处理文件所需的 Linux 环境。你可以让它分析数据、研究某个主题或生成文件,然后通过后续消息完善结果,而无需另外准备执行机器。

你可以做什么

  • 运行代码和分析数据。 让代理使用 Python、Node.js 或 shell 命令计算结果、处理数据集或自动化任务。
  • 在聊天中处理文件。 发送文档或数据文件,让代理对其进行转换,并从回复中下载最终输出。
  • 搜索研究并使用已连接的工具。 将内置网络搜索与已启用的 OpenClaw 工具、记忆和已连接的 MCP 服务器结合使用。
  • 通过后续消息持续工作。 在同一对话中完善结果、添加另一个文件或在任务运行期间调整方向。
  • 保留助手的上下文。 新会话会接收你的 OpenClaw 人设和指令,因此代理从一开始就能按照你的偏好工作。

托管设置面向个人、单用户的 Gateway。如果你希望命令在你管理的基础设施上运行,请参阅自托管执行。

设置 Agents API

首先需要一个可运行的 OpenClaw Gateway 和一个聊天渠道。你还需要 OpenAI API 密钥以及可供你的 Agents API 项目使用的模型。

1. 使用 API 密钥登录

运行:

openclaw models auth login --provider openai --method api-key

使用具有 Agents 和 Responses 读写权限以及 Models 读取权限的密钥。运行时使用官方 https://api.openai.com/v1 端点并采用 openai-responses 适配器。有关身份验证帮助,请参阅 OpenAI 设置。

请求通过 User-Agent: openclaw/<version>、originator: openclaw 和 version: <version> 标识 OpenClaw,与其他原生 OpenAI 请求使用相同的归属标头。

2. 启用插件并选择模型

将此配置合并到现有的 openclaw.json 中,保留你的渠道设置和其他插件。将两处 YOUR_MODEL_ID 替换为你的 Agents API 项目可用的模型。

{
  plugins: {
    entries: {
      agentsapi: { enabled: true },
    },
  },
  agents: {
    defaults: {
      model: { primary: "openai/YOUR_MODEL_ID" },
      models: {
        "openai/YOUR_MODEL_ID": { agentRuntime: { id: "agentsapi" } },
      },
    },
  },
}

如果你使用 plugins.allow,请将 agentsapi 和 openai 添加到该列表中。启用插件后即可使用;模型的 agentRuntime 设置会为对话选择该插件。有关提供商和每个代理的模型设置,请参阅运行时配置。

3. 开始对话并尝试任务

在 Control UI 中,打开 New session → Environments,然后在 Hosted workspaces 下选择 OpenAI (Agents API)。该选项使用 Gateway 配置的模型/运行时选择以及 API 密钥可用性。如果希望另一个运行时保持为默认,请将 pickerRuntimes: ["agentsapi"] 添加到具体的模型条目中,而不是更改其 agentRuntime。请参阅模型运行时选择。托管选项不会复制你选择的本地文件夹、项目或工作树;请将输入文件作为聊天附件发送。切换回来会恢复你的本地草稿选项,并且需要可用的兼容主机运行时。

通过你惯用的 Gateway 工作流应用配置。在你的聊天渠道中发送 /new,然后尝试:

使用 Python 计算 1 到 100 的平方和,并向我展示结果。

查找计算结果 338350。这会验证从你的聊天到托管代码执行再返回的路径。然后让代理重复计算 1 到 200,以在同一会话中尝试后续消息。你可以在处理文件和工具中探索附件和生成的文件。

继续任务

后续消息使用相同的 Agents API 会话。让代理修改其回答、处理另一个附件或采取下一步操作。在代理工作期间发送消息可以改变其方向;停止任务会取消其远程轮次。

来自 v2026.9.9 的已保存会话会在首次续接时升级,且不会更改远程会话 ID。请保留原始 API 密钥和配置,直到续接成功。如果它们不再匹配,插件会保留绑定关系,并说明如何恢复它们,或如何使用一个能够解决原始原生会话的密钥进行显式重置。升级失败绝不会静默创建替代会话。有关密钥轮换和回滚,请参阅已保存会话升级说明。

新会话会接收你的 OpenClaw 指令和人设,包括 AGENTS.md、SOUL.md 以及你的用户上下文。编辑这些指令后,发送 /new 或 /reset 以使用更新后的上下文开始对话。你已启用的记忆工具也可以通过 Gateway 搜索和调用信息。

处理文件和工具

Attach a file to a message and describe the result you want. For example:

按月份汇总这个 CSV,并发送给我一份包含总计的新 CSV。

附件会到达代理的托管工作区。要接收生成的文件, 请要求代理将其保存到 /workspace/outputs 下,并在回复中返回它。 下载你要保留的输出文件:托管工作区与你的 Gateway 文件是分开的,保存的对话不保证永久文件 存储。

除非通过 tools.web.search.enabled: false 全局禁用, 或通过会话的 网络搜索 控件禁用,否则新会话中可用内置网络搜索。 更改生效的搜索设置需要 /new 或 /reset;现有 会话会拒绝以不同的原生搜索策略继续。 你已启用的 OpenClaw 和插件工具仍可在你配置的工具策略下使用,包括 记忆搜索和召回。你还可以通过 MCP 连接远程工具;请参阅下文中的 MCP 连接。

高级配置与参考

以下各节涵盖存储、工具连接、自托管执行和 当前限制。上述设置足以开始使用托管 环境。

文件和存储

传入文件会被放置在 /workspace/inputs。随已完成回复返回的文件 来自 /workspace/outputs。传输支持每个文件最多 5 MiB、 总计 10 MiB,以及每个方向每轮最多 50 个文件。

你的 Gateway 工作区和托管文件系统用途不同。 说明作为上下文提供;当代理需要其工作区中的文件内容时,请以附件形式发送文件。请参阅 托管环境指南 了解环境生命周期和存储行为。

MCP 连接

在 mcp.servers 中配置远程 MCP 服务器,或在已启用插件的 MCP 捆绑包中使用 streamable-http 传输。托管环境必须能够访问 该服务器的 URL。如有需要,请提供 HTTP 身份验证头;localhost 指的是托管环境。

更改 MCP 配置或凭据后,使用 /new 或 /reset 开始新对话。 插件参考 包含连接设置、请求头参考和工具过滤器。

自托管执行

自托管执行将代理框架保留在 OpenAI 云中,并在你管理的基础设施上运行命令 和文件操作。内置的 agentsapi 插件 负责对话和原生会话。可选的执行器控制器 插件会将该会话连接到你的主机上的 codex exec-server 进程。

每个会话一个执行器

每个原生 Agents API 会话都有自己的环境 ID、连接 URL 和 执行器进程。后续轮次会复用该会话和执行器。开始 另一个对话会创建另一个拥有其自身执行器的会话。

所有执行器都可以在同一个持久化环境中运行,例如一台虚拟机、 远程主机或容器,并使用相同的工作区目录。这是一种 可能的部署方式,而非要求。你也可以根据隔离和持久化需求,将执行器 放置在独立环境中。

例如,两个对话可以具有如下布局:

OpenClaw Gateway                 One persistent remote host
  Conversation A -> Session A -> Executor A --+--> /srv/agent/workspace
  Conversation B -> Session B -> Executor B --+

这些会话具有独立的对话历史和执行器连接,但 共享该主机上的文件和已安装软件。会话隔离不是 文件系统或凭据隔离。并发会话可能会修改相同的 文件;当工作负载需要隔离时,请使用独立的工作区、用户或主机。 退役某个会话的执行器时,必须保持其他执行器和共享 工作区完好无损。你的主机的存储和备份策略决定文件的持久性。

1. 准备执行主机

完成上述 API 密钥和模型设置。在执行主机上,准备一个 绝对工作区路径,安装你的代理所需的工具和依赖项, 并安装支持 codex exec-server 的 Codex CLI 版本。请遵循 官方自托管设置 了解当前安装和出站网络要求。

从平台仪表板为与会话所有者相同的组织、项目以及用户或服务账户配置一个受限环境密钥。将该密钥 作为 CODEX_API_KEY 提供给执行器;不要让 Gateway 的应用程序 API 密钥进入执行器环境。控制器插件负责安全凭据 交付、主机访问、进程监管和文件系统配置。

2. 安装并配置控制器插件

使用插件安装工作流为你的部署安装一个执行器控制器插件。OpenClaw 提供控制器 契约,而不是捆绑的 SSH 启动器或通用主机管理器。该插件必须 注册 api.registerAgentExecutorController({ workspaceDirectory, ensure, retire }) ,并在其清单中声明 activation.onAgentHarnesses: ["agentsapi"]。插件 作者可以遵循 控制器 SDK 参考。

根据该插件的文档配置插件的主机、凭据和现有绝对工作区路径。 这些设置属于控制器插件;它们不是通用的 agentsapi 设置。其 workspaceDirectory 是 执行主机上的路径,可能与 Gateway 工作区不同。

3. 选择控制器

将此合并到你的现有配置中。将 my-executor 替换为 已安装控制器插件的实际 ID,并保留上述设置中你的模型的 agentRuntime.id: "agentsapi" 设置。

{
  plugins: {
    entries: {
      agentsapi: {
        enabled: true,
        config: {
          environment: "self_hosted",
          executorController: "my-executor",
        },
      },
      "my-executor": { enabled: true },
    },
  },
}

my-executor 是示例 ID,不是内置插件的名称。如果使用 plugins.allow,请将你的控制器 ID 与 agentsapi、openai 以及其他允许的插件一起包含。保持内置 Agents API 框架启用;控制器添加执行器管理,而不是第二个框架。

可选地,将 plugins.entries.agentsapi.config.hostExecutorSkillDirectories 设置为执行主机上的绝对技能目录路径。自行准备其文件和依赖项。OpenClaw 会转发这些路径以进行原生发现;它不会将 Gateway 技能复制到主机。

应用配置,并使用 /new 或 /reset 开始新对话。更改现有对话的环境、工作区或控制器需要重置。它不会在主机之间迁移文件。

启动、重连和清理的工作方式

  1. Agents API 框架会创建或恢复原生会话。当 API 要求 environment_connection 时,OpenClaw 会获取并验证该会话的环境,并保存其绑定和控制器所有者。
  2. OpenClaw 在所选控制器上调用 ensure(binding, context)。它只会启动或重连该会话的执行器,并使用绑定中精确的 environmentId、未更改的 remoteUrl 和 workspaceDirectory。
  3. OpenClaw 会等待 API 确认的连接就绪状态。在执行器启动期间,原始输入请求可以保持待定状态;它不会被重新提交。正常的后续轮次不会调用控制器,也不需要主机探测。
  4. 完成或中断一个轮次后,执行器仍保持可用。Gateway 释放也会保留其已保存的绑定和执行器。正在运行的执行器会处理原生重连;未完成的连接操作可以要求控制器再次确保同一会话。
  5. 重置、会话删除或已确认的终止性原生会话失败会在原生工作稳定后尝试 retire(binding, context)。它只会停止该绑定的执行器。如果无法确认原生工作已稳定,重置或删除会失败并保留绑定,以便你恢复连接或 API 密钥认证并重试。稳定后,执行器退役是尽力而为:无法访问的主机或停止失败会被报告,但不会阻塞重置或删除。Gateway 重启后,清理会重新获取所属代理的 OpenAI API 密钥认证,然后再检查已保存的原生会话。

控制器通常会在执行主机上、在其准备好的工作区中启动此命令,并安全地以 CODEX_API_KEY 提供环境密钥:

codex exec-server \
  --remote "<binding.remoteUrl>" \
  --environment-id "<binding.environmentId>"

为每个原生会话使用单独的受管进程,并使重复的 ensure 调用具有幂等性。重连不保证被中断的命令能够存活。在重复可能已经更改文件或调用服务的工作之前,请检查原始轮次的结果。输入提交有 60 秒的 HTTP 截止时间,包括连接等待,因此请确保主机能够快速连接。

改用外部控制器

你可以省略 executorController,并在 OpenClaw 外部管理执行器,例如通过 Agents API webhook 生命周期。 外部控制器负责会话范围的启动、重连和清理。 它必须对 API 读取进行身份验证,只处理其预期会话,并使用每个 会话的环境 ID 和未更改的远程 URL。在此模式下,OpenClaw 发送的工作区 路径必须已在执行器上的相同绝对路径处存在。 为每个会话选择一个生命周期所有者。

检查设置和文件边界

从托管设置中的计算开始,然后要求代理在其工作区中写入一个小文件,并在后续轮次中读取它。对于共享主机设置, 开始第二个对话,并检查它是否使用不同的执行器,同时 看到相同的文件。重置一个对话,并确认另一个对话仍然可用,且共享文件仍然存在。检查控制器进程记录和 Gateway 日志,以及聊天回复;模型身份验证探测不会测试执行器连接。

执行器管理不会自动同步 Gateway 文件,也不会添加附件传输。自托管输入附件需要一个已注册的工作区提供程序,并具备附件暂存功能。此控制器契约不会添加自动的自托管输出传输。为你的部署配置相应的工作区/文件集成,或使用托管环境及其内置传输。 Gateway 内存和工具保留其自身的存储和权限。有关这些边界和升级说明,请参阅 包参考。

会话设置和诊断

使用 /new 或 /reset 采用对会话指令、MCP 连接或推理摘要显示的更改。这些命令会在下一条消息时开始新会话。远程历史和工作区资源仍通过 Agents API 管理。

重置和删除会在移除会话绑定之前确认原生工作已停止,包括在 Gateway 重启之后。如果该确认失败,绑定会被保留以便恢复。这不会删除远程对话或其保留的文件。回退或切换本地转录分支也会使其旧的原生绑定失效,并在本地更改提交后退役其受控执行器。

OpenClaw 会显示进度,并在其正常转录中记录对话和工具历史。通道设置控制进度和推理可见性。当 API 可用时,会报告 Token 使用情况;它衡量的是使用情况,而不是剩余上下文容量。

要进行端到端设置检查,请使用上面的 Python 计算。 openclaw models status --probe 检查模型身份验证,而不是完整的 Agents API 会话。

当前限制

这些限制描述当前 OpenClaw 集成,并可能随支持范围扩大而变化。

  • 身份验证: ChatGPT 订阅身份验证、自定义端点以及用户编写的请求传输覆盖均不受 Agents API 运行时支持。请使用上面的 API-key 设置。
  • 托管环境设置: 插件不公开托管技能安装,也不公开操作员配置的启动命令、软件包、环境变量或环境模板。Gateway 脚本、仓库和技能目录不会自动复制到托管环境中。自托管执行器必须由操作员自行配置。
  • 指令和技能: 对工作区指令或人设的更改需要新会话。Gateway 技能文件访问、技能目录分发以及插件命令提示词注册目前尚不受此运行时支持。
  • 代理功能: 不支持原生委派(包括 ultra 委派)和原生会话分叉。原生 Codex 项目发现、协作和延迟工具搜索不适用于此运行时。
  • 图像和运行时自定义: 不支持图像输入、图像生成、Gateway 沙箱放置和自定义上下文引擎。
  • MCP 连接: 不支持 Stdio、旧版 SSE、请求方作用域连接和自定义 TLS 设置。Gateway OAuth 配置不会被转发。不支持的定义会被记录并省略,即使某个服务器不可用,回合仍可继续。
  • 工具限制和钩子: 限制原生 shell、文件或网络搜索能力的策略会在回合开始前被拒绝。钩子 toolsAllow 限制不会被强制执行;如果你依赖这些逐回合限制,请使用其他运行时。Gateway 工具策略仍然适用。引导和隔离补全不会运行对话提示词钩子。
  • 历史记录和诊断: 不提供结构化计划、差异、压缩事件、原生子代理事件以及执行前审批或钩子事件。在工具结果仍在返回期间,历史记录可能不完整或顺序错乱。可以看到网络搜索活动,但没有结果正文或摘要。命令退出事实可能不可用,并且 Token 用量不能确定剩余上下文容量。
  • 重试: OpenClaw 可以在临时提供商故障后继续现有会话。它不会自动重放已接受的回合,因为命令或工具可能已经执行。

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