Open Agent API

控制台使用说明

控制台由网关(本机运行的 Open Agent API 服务)自己提供(默认 http://127.0.0.1:8787),桌面版 macOS 应用内嵌的是同一个控制台。所有数据都用当前 API 密钥的权限读取(所有者(owner)与可访问的智能体),读取统计和时间线不会调用任何模型或工具。

接口细节、字段口径和上限,见协议文档里的「可观测内核:运行时间线、活动脉搏、排队与能力协商」和「控制台概览:修订号、ETag 与事件流」两节。

概览:运行驾驶舱

从上到下依次是:

  • 需要处理:等待你审批的任务,以及已中断或未完整完成、需要人工恢复的任务。数量来自概览的 metrics.requires_action;列表最多显示最近任务中的 3 条。待审批的任务如果早于最近 12 条任务,这里只显示数量,点「在任务页查看」会打开「需处理」筛选。
  • 指标带:统计窗口内的任务数(带趋势线)、成功率、中位耗时(P50,一半的任务在这个时间内完成;附 P95 耗时,即 95% 的任务在这个时间内完成,以及样本数)、当前进行中的任务(拆分为排队、运行、待审批;有任务在等调用方执行它自己的工具时,会注明「其中 N 个在等调用方」,这类任务计入运行、不计入待审批,较早版本的网关不提供这一项时不显示)。成功率的口径以协议文档为准,取消的任务不计入失败。
  • 活动统计(协议文档称「活动脉搏」):24 小时(每小时一格)或 7 天(每 6 小时一格)内的任务,按状态叠加显示:完成、进行中、取消、中断、失败。时段按 UTC 对齐,显示为本地时间;鼠标悬停可看该时段的明细。
  • 时间去向:最近至多 100 个已结束任务的耗时,沿每个任务的关键路径(决定总耗时的那条链)归因到模型推理、工具执行、排队等待、等待审批和其他五类。并行的工具调用不会重复计时,所以各项之和就是任务的实际耗时。下方给出一句解读,例如排队占比达到 25% 时,会提示执行容量可能不足。
  • 智能体:每个智能体在统计窗口内的调用次数、成功率和中位耗时。

统计窗口可以在活动统计卡片右上角切换,也可以在「设置 › 使用偏好 › 活动统计窗口」里设默认值。

任务与运行详情

  • 任务表格(一次调用就是一个任务):按状态筛选(全部、进行中、需处理、已完成、失败)。排队中的任务会显示排在第几位,以及预计多久开始;运行中的任务,如果当前这一步还在执行机器的队列里等待(执行机器满载或模型冷却),会显示「下一步约 N 秒后开始」。预计时间是根据近期执行耗时做的估计,不是承诺;排位只统计你自己的任务。运行中的任务,耗时会在本地持续累加。
  • 运行详情 › 时间线:按泳道显示一次任务的各个阶段。主线是排队、模型推理和审批,并行的工具调用各占一条泳道;颜色区分阶段类型。
    • 底部有深色描边的是关键路径。
    • 进行中的阶段带流动条纹;命中缓存的工具调用带斜纹;结果未知的步骤用橙色虚线框标出。本版本之前完成的任务没有记录模型轮次,它们的模型阶段是由工具调用之间的间隔推算出来的,用灰色虚线框标出,标题会注明「部分模型阶段为推算值」。
    • 排队阶段会注明原因:排队、公平调度让出、审批后重新排队、切换到备选智能体、等待执行机器。悬停在模型阶段上可以看到所用模型线路(智能体可选用的一个模型及其提供方)和重试次数;子智能体阶段可以点击,打开它自己的任务。
    • 调用方执行它自己的工具(桥接,见 harness.md)单独成段,名为「调用方执行工具」,颜色与工具阶段相同。
    • 如果某一段等待(审批、调用方执行工具或排队)占总时长 70% 以上,并且是其余工作的 8 倍以上,时间轴会把这段折叠成固定宽度,用斜纹和刻度标出它的实际时长,其余部分仍按真实比例显示。
    • 下方是这一次任务的「时间去向」;只有一种类别时(例如仍在排队)不显示。
  • 排队提示:排队中的任务会在详情顶部显示位置、预计开始时间和原因(等待执行槽位、公平调度暂时让出、审批通过后重新排队、执行机器繁忙、模型冷却中);运行中的任务如果当前步骤在执行机器的队列里等待,也会显示原因和预计等待时间。
  • 审批:待审批的操作排在详情最上面,可以直接批准或拒绝;拒绝、过期或取消都不会授予执行。发布时设为自动批准的智能体,它的权限请求由策略直接批准,不出现在这里,也不进入「需处理」;每次自动批准仍有记录(事件 approval.resolved,actor: "policy:auto")。
  • 发布时自动批准:发布对话框选「外部智能体」时有一个开关「自动批准它的权限请求」,默认关闭,下面一行警示说明开启的后果(它执行命令、修改文件前不再等你批准,能做的事和你在这台电脑上直接用这个软件时一样,只对信任的调用方开放)。开启后,智能体卡片上有「自动批准」标记,悬停说明含义;智能体详情「接入能力」的「审批」一行显示「自动批准(发布时设定)」。
  • 等待调用方:任务停在调用方自己的工具上(桥接模式)时,详情里单列「等待调用方」一节,说明「这个任务在等调用方执行它自己的工具,结果回传后继续。」,并列出每个待处理调用的工具名、参数摘要(点开可看全文)和剩余时间。这类调用不需要你处理,也不出现在「审批」里;待办全是这类调用时,详情顶部的状态显示「等待调用方」。到期仍未回传时任务以 client_tool_timeout 结束。任务列表与概览的最近任务也显示「等待调用方」(读列表行的 waiting_on),这类任务不出现在概览的「需要处理」卡片里,也不计入任务页的「需处理」筛选;概览的待审批数量同样不含它们。较早版本的网关不提供 waiting_on,这时仍按「待审批」显示。
  • 图片与结构化输出:任务带了图片时,详情里有一节「这次任务带了 N 张图片」,列出每张图片的名称、大小和缩略图(缩略图经带鉴权的文件下载读取,所以密钥需要 files 权限);以链接形式给出的图片只显示它的主机(「由模型提供方读取」)。请求要求了结构化输出时,状态与模型旁边的那一行会加上「结构化输出(json_schema)」(类别为 json_object、json_any 或 json_schema),网关曾让智能体修正过答案时再加「修复 N 次」。图片的字节不会出现在时间线或日志里。详见 images.md 与 structured-output.md。
  • 对话工作台(#workbench):侧栏内置的多轮对话与协议调试工作台。支持选择已发布智能体、模型选路(auto、@fast、@best、@eco 或具体线路,以及仅生成编排建议开关)、关联共享项目记忆与工具边界模式(auto / managed / bridge / reject);支持粘贴或上传图片,流式查看思考进度、工具步骤徽标与可下载产物;运行进入 requires_action 时可直接内联点击「批准 / 拒绝」(waiting_on === "owner")或回传外层桥接 tool_calls 模拟结果续接同一运行(waiting_on === "caller",基于 previous_response_id),并支持一键导出 curl、OpenAI、Claude 与 Gemini SDK 调用代码。
  • 调用地址 › 调用方自己也是智能体时:网关支持 client-tools-policy-v1 时显示。说明调用方带来的工具怎么处理,是一张四种模式的表:auto(默认,请求没有选择时用它:智能体能接管这些工具就桥接,否则照旧)、managed、bridge 与 reject。附一条带 X-OAA-Client-Tools: bridge 请求头的 curl 示例,并说明桥接支持内置内核智能体、Codex、Claude Code、Antigravity ACP 与 ACP 外部智能体。详见 harness.md;网关配置项 clientTools.default 可以改变 auto 所代表的处理方式。
  • 调用地址 › 事件回调:网关支持 webhooks-v1 且密钥是所有者级管理员密钥时显示(接口对其他密钥一律拒绝)。除 oaa webhook 与 /v1/webhooks 接口外,控制台直接提供完整的事件回调增删测管理:支持添加回调端点(填写 URL、勾选订阅事件、备注与可选 include_output,创建后一次性展示签名密钥 secret 供复制)、行内一键发送测试(Test)、二次确认删除(Delete),以及查看最近投递状态、HTTP 状态码与重试次数。详见 webhooks.md。

开发者平台(运营者)

「接入」分组下的「开发者平台」页,给运营者上架智能体并定价、管理开发者账号与余额、生成兑换码。需要管理员权限(admin)。接口见 platform.md「接口一览」;页面显示的金额单位都是「点」。

  • 未启用时:网关的 GET /health 没有 platform-v1 特性时,页面只显示一页说明:用途(把智能体开放给别人用)、什么时候不需要它、「API 密钥」与「开发者平台」两种分发方式的对照,以及「启用」按钮(填站点名、注册方式、新账号赠送点数)。设置经 PUT /v1/platform/setup 保存在网关数据里,重启网关后生效;保存后、重启前页面提示「重启后生效」(pending_restart)。配置文件里写了 platform 段时(managed_by_config)设置只读。不显示数据区,除 GET/PUT /v1/platform/setup 外不读取平台接口。
  • 概况:开发者账号数(有效 / 已停用)、余额合计、累计消耗、任务数,以及站点名和注册方式(closed、invite、open,在网关配置里修改,这里只读);右上角可复制开发者门户地址(/portal/)。
  • 用量(在「概况」与「上架与定价」之间):标题右侧的「任务数 / 消耗」切换一张近 30 天按天的柱状图(日期按 UTC,画法与概览页「最近活动」一致,悬停柱子可看当天的任务数、消耗和 token);图右上是 30 天的合计。30 天内没有任务(或在「消耗」口径下没有消耗)时,图换成一句空状态。图下并排两张小表:按智能体(智能体、任务、token、消耗)与按账号(邮箱、任务、token、消耗;网关最多返回消耗最高的 50 个账号);点邮箱会把顶栏搜索框填成这个邮箱,开发者表随之按邮箱搜索并滚动到那一节。数据读自 GET /v1/platform/usage?days=30,跟随这一页的刷新节奏。
  • 上架与定价:表格列出智能体、标题、每个任务的价格、每千 token 的价格和是否上架。「上架智能体」从已发布、还没上架的智能体里选,填标题、简介、标签和两个价格。每个任务的价格在任务开始时预扣,任务完成才收取,未完成则退回(0 表示不按次收费)。不上报 token 用量的智能体(多数外部智能体)只能按次定价:「每千 token」价格必须为 0,否则保存会被拒绝(usage_pricing_unsupported)。对于以本机权限运行的智能体(外部智能体,或带本机工具的智能体),对话框里还有一个开关允许平台账号在本机运行这个智能体,默认关闭,并说明它的含义:打开后,平台账号会让这一个智能体以运行网关的系统用户的权限运行,受它的审批策略约束(审批只由你处理);智能体的审批策略是 auto 时还会多一条提醒。关闭时,平台账号调用它会被拒绝(isolation_required),门户目录里也不显示这个智能体。上架列表的状态列说明每一项的情况:「已上架」、「已下架」、智能体已被删除的上架记录标出「智能体已移除」,或者「平台账号调不了」,指已上架但账号暂时调不了,因为它或它委派的某个智能体还没打开这个开关(悬停可看是哪一个);开关打开时,标题下面有一行「平台账号以本机权限运行」。详见 platform.md。行内可修改、下架 / 重新上架、移除上架记录;下架和移除要二次确认。
  • 开发者:表格列出邮箱、名称、状态、余额、密钥数、任务数、累计消耗和最近活动,数据多时用「加载更多」翻页。顶部搜索框按邮箱在网关里搜索。行内操作:调整余额(增加或扣减,备注必填,结果不能小于 0;可选填「外部单号」,同一个单号只会入账一次,适合对接支付回调,重复提交时提示「这个单号已经入过账,没有重复入账」,不会再加点数)、查看流水(带外部单号的行在备注下面以小字显示单号)、重置密码、停用 / 启用;停用和重置密码要二次确认。「重置密码」有两种做法:生成一次性重置码(默认、推荐)——明文只在结果页显示一次,可复制,注明到期时间(24 小时有效,生成新的会使旧的失效),关闭对话框后页面上的副本即被清除;你把重置码发给开发者,由他在门户登录页自己设新密码,你不会知道他的密码;或直接设置新密码(你替他设,你会知道这个密码)。「新建账号」不受注册方式限制,初始密码可以用「生成」得到一个随机密码。
  • 密钥的「充值(billing)」权限:生成 API 密钥时,如果网关启用了开发者平台,权限里多一项「充值(billing)」,说明是只能给开发者账号加点数、按邮箱查账号,用于支付回调;没有 platform-v1 特性时不显示这一项。「设置 › 连接」与密钥列表里把它显示为「充值(billing)」。
  • 兑换码:表格列出类型(点数码、邀请码)、点数、已用 / 可用次数、到期、备注和状态,行内可作废(要二次确认,已兑换到账的点数不会收回)。「生成兑换码」可设类型、点数、可用次数、数量(1 到 100)、有效期和备注;兑换码明文只在生成后的结果页显示一次,可整批复制,关闭对话框后页面上的副本即被清除,网关里只有散列。

这一页的数据只在页面上显示时才读取,约每 20 秒或点顶栏的刷新按钮时更新,每次操作后立即更新;读取失败时已有的数据继续显示,并在页首提示原因。

实时同步与兼容

  • 网关提供 /v1/overview/events 时,顶栏显示「实时同步」,变化约 250 毫秒内推送到控制台;不提供时按设置的间隔轮询。
  • 每个变化事件都带有原因(runs、catalog、nodes),控制台只重新读取受影响的数据。例如执行机器负载变化不会重新读取活动统计。所有读取都使用 ETag 条件请求,数据没变时网关返回 304,不传正文。
  • 能力协商:控制台从 GET /health 的 features 判断网关支持哪些功能。连接到较早版本的网关时,活动统计、时间线和排队提示会自动隐藏,其余功能照常使用。

设置

  • 外观:语言(中文、English;首次打开跟随浏览器语言,切换后页面重新载入,选择保存在 localStorage 的 oaa.console.lang;macOS 应用自己的菜单与对话框改为跟随系统语言,见下文)、主题(跟随系统、浅色、深色)、深色配色(墨黑、深潮)、界面密度、动效、侧栏。窗口宽度在 901 到 1180 像素之间时,侧栏自动收成只有图标的窄栏(悬停或用键盘聚焦某一项会显示名称,进行中的任务数变成图标角上的一个小点);再窄就变成页面上方的一条横栏。「收起侧栏」仍然把侧栏整个藏起来。
  • 使用偏好:默认首页、数据刷新间隔、时间显示(相对或具体时间)、活动统计窗口、默认优先考虑(模型线路的选择策略)、快速上手清单。
  • 连接:密钥名称、权限范围、可访问的智能体和网关地址(Base URL),以及「切换密钥」「断开连接」;管理员密钥还有「管理 API 密钥」。
  • 桌面应用(在跨平台统一 Electron 桌面应用中显示,覆盖 macOS、Windows 与 Linux):Dock / 托盘角标、审批通知、开机自动启动、打开数据目录、在浏览器中打开、复制管理员密钥、重启网关。
  • 快捷键:⌘K 命令面板,⌘, 设置,⌘\ 切换侧栏,/ 聚焦搜索,⌘↵ 提交智能体任务,Esc 关闭弹层或对话框。在 Windows 和 Linux 上,⌘ 换成 Ctrl。

偏好只保存在本机浏览器里(localStorage 的 oaa.prefs.v1),不会上传到网关。

跨平台统一桌面应用(macOS、Windows 与 Linux)

  • 原生窗口:macOS 上顶部没有标题栏条(hiddenInset,红黄绿按钮位于 { x: 20, y: 18 }),嵌在侧栏顶部,跟侧栏折叠按钮、页面路径和搜索框在同一行;双击空白标题区域按系统设置缩放或最小化窗口。Windows 与 Linux 共用同一套开启严格安全沙箱的 Electron 外壳(nodeIntegration: false、contextIsolation: true、sandbox: true)。
  • Dock 角标、系统托盘快捷审批与开机自启:macOS Dock 与系统托盘实时显示待人工审批的任务数量。点击菜单栏 / 系统托盘图标可弹出沙箱化的托盘快捷面板,无需打开主窗口即可查看网关状态与端口、运行中任务数、待 owner 审批列表并一键点击「批准 / 拒绝」(调用 /v1/runs/{id}/actions/{actionId}),同时提供「开机自动启动」开关(在 --oaa-data-dir / OAA_DESKTOP_HOME 隔离运行模式下自动禁用保护)。
  • 审批通知:默认关闭。第一次开启时,macOS 会询问是否允许通知;之后可以用「发送测试通知」确认权限。控制台窗口在前台时不会弹通知。通知里只有智能体名称,不含任务内容,因为通知可能显示在锁屏上。点击通知会打开对应的任务。
  • 首次启动:应用会发布离线示例智能体、启用它在这台 Mac 上找到的智能体引擎,并弹出一次对话框,如实说明这些,以及去哪里关掉某个引擎(本页的「执行机器」)。详情见 install.md。
  • 语言:应用自己的菜单、对话框和提示跟随系统语言(首选语言以 zh 开头用中文,否则用英文),与控制台、命令行的规则一致。窗口里的控制台保留它自己的语言选择(设置;页面本地存储里的 oaa.console.lang),应用从不写它,所以没切换过的控制台仍然跟随浏览器语言。
  • 关闭窗口不会停止网关:网关继续在菜单栏里运行;从菜单栏图标可以重新打开控制台,也可以退出应用。

隐私与安全

  • 统计与时间线只读取持久化的运行事件,不调用模型或工具,也不新增存储内容。
  • 时间线只包含阶段类型、时间和机器可读的标识(例如工具名、步骤 ID),不包含任务输入、工具参数或输出内容;这些内容只在你展开对应步骤或下载时才读取。
  • 控制台页面遵循严格的内容安全策略(CSP):不加载第三方脚本,不使用内联脚本和内联样式,密钥不会出现在 URL 里。
本页内容