Agents API

Agents API 是什么？¶

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

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

按照本指南中的托管方案，OpenAI 还会提供你的代理运行代码和处理文件所需的 Linux 环境。你可以让它分析数据、研究某个主题或生成文件，然后通过后续消息优化结果，无需单独准备一台执行机器。

你可以做什么 ¶

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

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

设置 Agents API¶

首先，你需要一个可正常运行的 OpenClaw Gateway 和一个聊天渠道。此外，你还需要一个 OpenAI API 密钥，以及一个可供你的 Agents 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. 开始对话并尝试一个任务¶

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

使用 Python 计算从 1 到 100 的平方和，并告诉我结果。

查看计算结果 338350。这验证了从你的聊天到托管代码执行再返回的完整链路。然后让代理对从 1 到 200 重复同样的计算，以在同一会话中尝试后续消息。你可以前往处理文件和工具体验附件和生成的文件。

继续任务 ¶

后续消息会使用同一个 Agents API 会话。你可以要求代理修改答案、处理另一个附件，或执行下一步。在代理工作期间发送消息可以改变它的工作方向；停止任务会取消其远程轮次。

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

处理文件和工具 ¶

在消息中附加一个文件，并描述你想要的结果。例如：

按月汇总这个 CSV，然后把包含总计的新 CSV 发给我。

附件会到达代理的托管工作区。要接收生成的文件，请让代理将其保存到 /workspace/outputs 下，并在回复中返回该文件。请下载你想要保留的输出：托管工作区与你的 Gateway 文件相互独立，保存对话并不能保证文件会被永久存储。

新会话中可使用内置网络搜索。你启用的 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 开始新对话。插件参考包含连接设置、请求头参考和工具过滤器。

自托管执行¶

对于在你自己的基础设施上运行的命令，请配置一个自托管环境，使用由操作员管理的执行器控制器和匹配的工作区路径。 hostExecutorSkillDirectories 可以暴露安装在该执行器上的技能目录。环境设置参考涵盖控制器先决条件、附件暂存和会话重置。

会话设置和诊断¶

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

OpenClaw 会显示进度，并在其常规转录中记录对话和工具历史。频道设置控制进度和推理可见性。当 API 可用时，会报告 token 用量；它衡量的是用量，而不是剩余上下文容量。

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

当前限制 ¶

这些限制描述了当前的 OpenClaw 集成，并可能随着支持扩展而变化。

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

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