OpenAI 浏览器与桌面驱动
驱动把允许的工具调用转为自己控制的浏览器或桌面动作。能提供页面文字、控件和标签页时使用浏览器驱动;必须依靠截图和坐标时使用计算机驱动。SDK负责发请求和分派调用,应用负责会话、权限与清理。
配置通用控制
可从浏览器示例开始,它包含驱动、确认策略和有界Responses运行。运行结束前保持会话。Python也提供同步 BrowserToolset、ResponsesToolRunner。
| 目标 | 设置位置 | 行为 |
|---|---|---|
| 限制浏览器方法 | 构造BrowserToolset或AsyncBrowserToolset时设members | 仅暴露已实现的选定方法,只读例子可仅用read_page |
| 批准浏览器变更 | 构造时传confirm | 仅精确true或True批准,检查方法、目标和参数 |
| 限制导航 | Node传urlPolicy,Python传url_policy | 启用navigate或new_tab时必需,先检查URL再确认 |
| 批准桌面动作 | Node运行选项computerOptions;Python运行参数approve_safety_checks和before_action | 待处理安全检查须明确批准,可选逐动作回调可拒绝任一步 |
| 限制运行 | maxSteps或max_steps | 默认20次请求,最后允许的请求不得启动新副作用 |
| 测量用量 | 同步onDiagnostic或on_diagnostic | 汇总完成请求的用量,缺少usage时总量应标为不完整 |
批准动作并管理会话
驱动及批准回调应由可信应用代码创建。可执行配置与不可信页面数据分离,页面数据通过声明的报告字段返回。
会改变状态或读取诊断的方法要求 confirm;Node只有精确 true、Python只有 True 才批准。导航和新标签还要求URL策略。两个回调都接收独立副本,包含 member、已验证 arguments、先前 state、call_id;URL回调还接收目标URL。修改副本不会改变已验证动作。
确认针对固定参数,先前state不是文档或焦点锁。用户决定期间页面可能导航或焦点改变。需绑定具体页面或控件时,驱动应在执行时复查原目标;此流程禁用key,并拒绝target为空的type,因为它们依赖当前焦点。其他依赖当前状态的动作也应绑定目标。
读取私有页面前要询问时,在 confirmReads 或 confirm_reads 列出读取方法。相同confirm在读取任何状态或内容之前调用,此时 phase: before_read、state为null或None;处理时不能先读取页面元数据。拒绝后不返回内容或状态。未配置时保持原读取行为,强制动作批准仍有效。
桌面动作执行前必须批准全部待处理安全检查。approveSafetyChecks 或 approve_safety_checks 须精确返回true;缺失或拒绝会停止运行。可选 beforeAction 或 before_action 在每个动作、包括最终截图前调用,若提供也须明确批准。模型选择或完成消息不能代替授权,参见安全指导。
Node向两个桌面批准回调追加 { signal },Python在回调接受时传 cancelled。旧版较少参数回调仍支持。可用此上下文在运行停止时关闭审批提示;辅助器等回调结束再释放会话。审批不冻结屏幕或焦点,目标改变时驱动须重新绑定或拒绝;桌面应隔离且限制网络。
限制URL
仅任务需要时开放navigate或new_tab,并同时提供confirm及URL策略。URL回调接收 (context, url),Node还可接执行上下文,Python可接cancelled;必须精确返回true才进入confirm。URL为空的新空白标签仍需确认,但无URL可检查。
解析协议、主机和端口,不能只比字符串前缀:https://example.com.evil.test 不属于 https://example.com。不提供导航的驱动无需URL回调,浏览器示例默认关闭导航。
浏览器或环境也应执行网络策略:URL回调无法限制重定向、弹窗、脚本和嵌入资源。请求间保持同一隔离会话,关闭自己创建的资源,借用资源留给其所有者。
检查用量和耗时
ResponsesToolRunner的同步诊断回调接收每个完成请求的记录:api: responses、stage: request、reason: completed、usage。若API提供,usage含input_tokens、output_tokens、total_tokens,否则为null或None。逐字段汇总,任何缺失都应说明不完整。
ComputerToolset.run的诊断回调不报告请求用量,最终响应可能只有最后一次请求用量。需逐请求统计时,将ComputerToolset交给ResponsesToolRunner。
诊断还含API、阶段、原因、调用ID、方法和耗时,不含原始错误、页面文字、参数或图像。观察器失败不能批准动作或改变结果。若调用ID与方法名含私有信息,不放公共日志。观察器应同步,异步保存由应用调度。eager运行中阶段耗时可能重叠,不可相加当作总耗时。
关闭与取消
辅助器拒绝重叠调用,runner也拒绝同实例第二个活动运行。每个会话保留一个所有者。close() 拒绝新工作;无活动调用为closed,仍可能产生效果的旧调用存在时为draining。draining时等待原execute结束,再关闭驱动或交接。辅助器不替你关闭浏览器或桌面;在驱动回调内部调用close不会等待该回调自身。
协作式Node方法和普通函数可接第二参数signal,Python可接cancelled,应在导航、截图等长工作中检查。单参数旧方法仍有效,但SDK无法强制终止或撤销其副作用。
浏览器驱动协议
实现 state() 及打算暴露的操作。Node方法可同步或返回Promise;Python区分同步异步类。每项操作接一个已验证参数对象或字典,可为空的tab_id及target用显式null或None。
Python构造辅助器时拒绝已知同步异步不匹配。AsyncBrowserToolset使用async def;包装方法须保留装饰器元数据或返回注解,不透明包装器到调用时再检查。BrowserReadDriver、AsyncBrowserReadDriver可为部分驱动提供类型。Node提供 BrowserArguments<Member>、BrowserResult<Member>。
state返回tabs数组,每项含id、title、url、active。使用稳定ID和真实活动标签,标题URL排除凭证与私密信息。普通操作成功或失败后SDK返回当前state,拒绝受保护读取则返回固定拒绝,不读state;必需state读取失败则停止。Node的state读取器接signal,Python可接cancelled,以便终止待处理读取;旧无参数方法仍支持。
状态中的HTTP/HTTPS URL仅报告源,例如 https://example.com:8443,不含凭证、路径、查询和片段。旧式无观察元数据状态保留about:blank,其他URL只报scheme;2048字节UTF-8限制作用于报告值。V1观察元数据将标题按字符边界截到1024字节,需要时标记title_truncated。应用仍需执行隐私规则。
选择方法
默认在已实现时暴露以下18项,list_tabs由state派生,不要自行实现list_tabs。members可缩减或显式加入默认关闭的方法;名称须唯一、固定且已实现。空列表不暴露方法,SDK构造时复制选择并保持自己的顺序,禁用调用在读取状态或审批之前拒绝。
也可用 additionalMembers 或 additional_members 添加可选方法,不能与members同用,新增必须已实现。BROWSER_MEMBERS及DEFAULT_BROWSER_MEMBERS提供固定名称,不检查驱动。关闭list_tabs不隐藏其他操作返回的state;Python的members仅过滤浏览器辅助器,普通函数可用browser_前缀,但不能与启用工具重名。
| 方法 | 参数 | 返回 | 确认 |
|---|---|---|---|
| navigate | url, tab_id | 文本或无值 | 是,另需URL策略 |
| read_page | filter(all或interactive), tab_id | 文本或结构化读取 | 否 |
| get_page_text | tab_id | 文本或不含元素的结构化读取 | 否 |
| find | query, tab_id | 文本或结构化读取 | 否 |
| click | target, tab_id | 文本或无值 | 是 |
| type | text, target(可空), tab_id | 文本或无值 | 是 |
| key | keys, tab_id | 文本或无值 | 是 |
| scroll | direction, amount(非负), tab_id | 文本或无值 | 是 |
| scroll_to | target, tab_id | 文本或无值 | 是 |
| wait_for | text, timeout_ms, tab_id | 文本或无值 | 否 |
| select_option | target, values, tab_id | 文本或无值 | 是 |
| hover | target, tab_id | 文本或无值 | 是 |
| screenshot | tab_id | 原生输入图像 | 否 |
| zoom | region, tab_id | 原生输入图像 | 否 |
| new_tab | url(可空) | 文本或无值 | 是,另需URL策略 |
| list_tabs | 无 | 当前派生状态 | 否 |
| switch_tab | 必需tab_id | 文本或无值 | 是 |
| close_tab | 必需tab_id | 文本或无值 | 是 |
除switch_tab、close_tab外,表列tab_id可空;direction为up、down、left、right。Python提供TabInput、ReadPageInput、ClickInput等类型。read_page、find、get_page_text返回null、无值或None表示仅更新state;完成读取但无文本时返回空字符串。
除list_tabs走state读取器外,Node操作第二参数为signal;Python接受时传cancelled,可停止导航或输入等待。wait_for的非空文字经空白规范化后最多256字节,超时1—30000毫秒。scroll_to后对控件操作前重新读取页面。
报告结构化读取
read_page、find、get_page_text可返回BrowserReadV1,含version:1、可见text、elements和omitted数组。每个元素有唯一ref、非空label和七种role之一:button、textbox、combobox、checkbox、radio、slider、listbox。
应用允许模型查看时才报告value及options(label/value对)。checkbox、radio可报布尔checked;listbox选项可报selected,其他role不保留这些字段。Node省略undefined可选字段,但拒绝null。get_page_text必须返回空elements。普通字符串不会自动解析为结构化读取。
SDK不限制元素数、选项数、页面文本或总报告大小。ref和label最多256字节,value最多512字节,必须是合法Unicode标量。部分覆盖用唯一omitted代码:report_limit、text_limit、target_limit、work_limit、frame_limit、unsupported_root、unsupported_control、remote_action、private、value、name_limit。
可见性、字段隐私和ref有效性由驱动负责。批准后、动作前对当前页面复查ref;控件label不授予读取value的权限,大小限制也不使页面内容天然安全。
返回浏览器图像
screenshot和zoom返回原生input_image,至少有非空image_url或file_id,可同时提供,每个非null来源必须是非空字符串。支持type、image_url、file_id、detail、prompt_cache_breakpoint;显式缓存断点为 {mode: "explicit"},原生类型允许处也接受null。SDK验证并复制字段。Node返回ResponseInputImageContent,detail可省略或null,设值时为auto、low、high、original。
zoom的region为 [left, top, right, bottom],非负安全整数且宽高为正。驱动负责裁剪和边界检查;后续坐标仍以完整可视区域为准。
显式启用分区与指针方法
以下六项默认关闭,即使已实现也需通过members或additionalMembers/additional_members启用;用members时记得列入仍需保留的默认方法。
| 方法 | 必需字段 | 返回 | 确认 |
|---|---|---|---|
| read_page_scoped | tab_id, root, depth, filter | BrowserScopedReadV1 | 否 |
| click_at | tab_id, x, y, button, click_count, keys | 文本或无值 | 是 |
| drag_path | tab_id, path, keys | 文本或无值 | 是 |
| hold_keys | tab_id, keys, duration_ms | 文本或无值 | 是 |
| hover_at | tab_id, x, y | 文本或无值 | 是 |
| set_checked | tab_id, target, checked | 文本或无值 | 是 |
Node使用BrowserArguments,Python提供ReadPageScopedInput、ClickAtInput、DragPathInput、HoldKeysInput、HoverAtInput、SetCheckedInput。字段全部必需,tab_id可空表示活动标签,拒绝未知字段,包括路径点多余字段。数值必须有限且为安全整数,Python不接受布尔代替数值。
click_at坐标非负,button为left/right/middle,click_count为1、2、3。drag_path为2—100个精确 {x,y} 非负坐标点。两者都用完整可见页面CSS像素,缩放后也不改变;驱动复查当前边界。keys为不重复Control、Alt、Meta、Shift,可空。
hover_at只移动指针不按按钮。set_checked设置明确布尔状态,连续两次true仍保持选中;即使无变化也需确认并使用原来的当前目标,拒绝失效或替换控件。
hold_keys接1—8个唯一非空键名,每个合法Unicode且最多64字节;duration_ms为1—3000。改变状态的方法必须精确批准。协作方法可接逐调用取消上下文,旧单参数方法仍有效。
在分区内读取
read_page_scoped中root为空表示发现可见分区,否则必须是驱动签发的scope ref,不能是选择器;须非空、合法Unicode、最多256字节。depth为1—32,filter为all或interactive;深度只计算根内DOM遍历,独立于frame或shadow限制。
返回扩展了 scopes: [{ref,label}] 的BrowserScopedReadV1。ref和label非空且最多256字节;scope ref必须唯一且不与元素ref冲突。拒绝字符串或null返回,SDK复制已知字段后才请求最终state。
scope ref只用于选择读取根,元素修改必须拒绝它们。标签、文档、代次或可见性变化时,使scope及元素ref一起失效。继续执行字段隐私、总工作量和读取限制。
显式启用诊断、脚本及文件传输
以下四项默认关闭,须显式选择并提供confirm,诊断读取也需要批准。
| 方法 | 必需参数 | 返回 |
|---|---|---|
| read_diagnostics | tab_id, source, limit | 仅文本结构化读取 |
| run_script | tab_id, source, timeout_ms | 文本 |
| upload_file | grant_id | BrowserFileOutcome |
| download_file | grant_id | BrowserFileOutcome |
read_diagnostics的source为console或network,limit为1—100,返回空elements的结构化读取,Node用BrowserTextReadV1。驱动限制历史并过滤私有数据,不能返回原始头、cookie、凭证或未筛选控制台消息。
run_script源码非空且合法Unicode,超时1—30000毫秒,SDK保留完整源码。返回合法Unicode文本,可为空字符串但不可null,大结果也保留。脚本拥有页面权限,应使用无凭证新会话并限网;执行结果不确定时停用会话,停止本地等待不证明页面脚本已停。
文件方法只接受调用方签发的grant_id,非空合法Unicode且最多256字节,代表一个已批准、限定任务的文件,不是路径或URL。文件所有者另行取得文件批准,复查有效期与所有权,限制大小并确保一次使用。浏览器确认不能替代文件批准。
返回恰好含version、status、effect、cleanup;version为1,cleanup为not_started、pending或completed。有效配对:completed/completed;refused/none;unknown/unknown;interrupted/none或unknown。
SDK验证并复制后再读最终浏览器state。只有completed使ok为true,其他保留结构化结果且ok为false,runner跳过本响应依赖的浏览器调用。未知传输重试前检查实际文件和应用,文件结果不证明后续表单提交成功。
run_script、upload_file、download_file接逐调用取消上下文;Python提供ReadDiagnosticsInput、RunScriptInput、BrowserFileInput。
计算机驱动协议
驱动接收原生动作并返回截图。Node从openai导入ComputerDriver、ComputerToolset,Python按同步或异步选择ComputerDriver/AsyncComputerDriver与对应Toolset。
| 方法 | 接收内容 |
|---|---|
| click | 坐标、按钮、按住的键 |
| double_click | 坐标与按住的键 |
| drag | 路径与按住的键 |
| keypress | 键组合 |
| move | 指针坐标 |
| scroll | 坐标、scroll_x、scroll_y |
| type | 向焦点控件输入的文字 |
| wait | 等待环境稳定 |
| screenshot | 无参数,返回当前显示 |
动作接收已生成的snake_case字段对象且无返回值。不能执行时必须抛错,不可静默忽略。Node可同步或Promise;Python异步方法须await,与对应同步异步Toolset匹配。包装器保留元数据,不透明包装器自身代码可能先执行才发现不匹配。
Node的execute使用ComputerCallInput,接受原生调用及带actions的现代调用,允许省略pending_safety_checks;此时审批回调得到空检查表副本,重放仍保留原字段。
screenshot返回computer_screenshot,至少包含image_url(包括data URL)或file_id,也可两者兼有。辅助器不读本地文件。动作按序只执行一次,最后统一截图,不自动重试驱动动作。
纯computer循环可用ComputerToolset.run或AsyncComputerToolset.run;混合循环将辅助器作为runner的computer选项。Node审批回调在computerOptions中,Python直接传运行关键字。浏览器例子只验证浏览器,不等于验证原生桌面。
两种runner均接受Responses原生context_management压缩,验证必需字段并原样重放加密内容。ResponsesToolRunner只能选择原生压缩或本地contextBudget/context_budget,不可混用。
运行截图任务
首个任务提供完整Python与Node取件页面示例。
使用隔离桌面
Python完整示例与Node示例使用隔离Linux客户机。Apple silicon Mac通过VM,x86-64 Linux通过Docker。均含无密钥演练,真实任务同时检查浏览器记录和保存文件。自管环境可从Docker方案调整。
浏览器动作与其他工具混用
runner可组合浏览器、computer、普通函数、网页与文件搜索、代码解释器、图像生成和远程MCP。重放时服务端工具保留原生内容和容器ID;服务端失败、不完整或未完成会在本地动作前停止。
声明服务端工具后,即使eager开启,本地调用也等完整响应,因为需先检查后续服务端结果和审批。完整轮次中,允许覆盖的普通函数可由supplyOutputs/supply_outputs替换尚未尝试的结果,无需显式早执行策略;不能替代浏览器、computer或MCP审批结果。
图像生成续接要求存储响应。声明image_generation而store为false时runner拒绝;适当时显式开启,或单次无状态调用responses.create,runner不会代你开启存储。
复用带类型函数以避免重复验证:Node用runnerFunction包装含回调的zodResponsesFunction或standardResponsesFunction;Python用RegisteredFunction.from_tool或AsyncRegisteredFunction.from_tool,传现有pydantic工具及显式带类型执行器。非法参数在执行前停止,非法回调输出停止但不重复副作用。原始注册方式保留原参数行为。
MCP配置approveMcp或approve_mcp,接收真实审批请求副本并返回布尔,runner绑定原请求ID和声明服务器;不能编造批准或把最终消息当同意。声明MCP会禁用SDK自动重试,无论有无ledger。失败后重新运行前先检查远端实际执行情况。
处理失败
可恢复错误如失效ref,可抛出仅含模型可见安全文字的BrowserError;其他操作错误显示通用失败。runner为每个浏览器调用提供输出,跳过该响应剩余浏览器动作,让模型下轮重新选择。无效返回或state停止运行;无法报告state、普通函数失败、原生安全检查未获批准也停止。
maxSteps/max_steps默认20,限制API请求,最后一轮不启动新副作用。HTTP重试不重试驱动动作。signal/cancelled可在操作间停止,但进行中的任意调用不一定能撤回。
runner每次保留tool_choice。若一直强制本地工具,循环无法结束,因此在任何工作前拒绝;循环用auto,单次强制用responses.create。若required也允许声明的服务端工具,仍有效。
运行排错
| 现象 | 检查与修复 |
|---|---|
| 无法导入辅助器 | 检查脚本实际环境,使用openai Python3.31.0、Node7.33.0或含相应能力的后续版 |
| Chromium启动失败 | 同环境安装Playwright浏览器与Linux系统库,用非root;不要关闭沙箱掩盖问题 |
| 模型或工具被拒绝 | 查项目权限和模型Tools栏,原生computer与浏览器函数要求不同 |
| 动作或安全检查被拒绝 | 查批准策略并对照当前状态,不要为通过测试而全部批准 |
| 达到步数上限 | 先检查实际页面或文件,确认是否缺少驱动能力,简化任务后才考虑提高上限 |
| 未读页面就回答 | 启用已实现read_page等读取方法,要求读取再运行,实际验收结果 |
| 点击偏移 | 检查截图与坐标空间 |
修复点击偏移
新截屏确认目标窗口。截图与动作必须使用一致坐标;1600×1200显示缩为800×600时,点击前两坐标都乘2;裁剪截图缩放后还要加裁剪偏移。浏览器指针使用全可见页面CSS像素,不能混同显示像素。尺寸影响词元与成本,参见截图要求。
流式与恢复
默认非流式。启用stream及onEvent/on_event后,runner返回事件副本,完整响应后执行。eager可按序提前执行完整输出项,绝不执行参数增量。
只有完成项可在整响应验证前安全执行才开启eager。后续事件若改变或移除该项,runner停止并保留记录,无法撤销动作;若所有动作需等完整验证,关闭eager或使用空早执行策略。完成项乱序或索引有缺口时,该段等完整响应;流失败不抹掉已完成副作用。
earlyExecution/early_execution按函数线上名称限制提前执行,并单独控制原生computer分派。空对象延迟全部本地工具;省略则保留eager统一行为。第一个延迟工具会使后续都延迟以保序。iterate在完整轮次边界先检查再前进,此处关闭不会执行延迟工具。这些只改变时间,不改变授权。
beforeEarlyCall/before_early_call可对完整调用返回defer,不能让允许列表之外提前执行。普通函数仅在不依赖其他动作时标记independent:true。无ledger时独立函数可在流推进时运行,持久运行、浏览器与computer保持顺序。其他调用失败也保留已开始工作记录。
默认最多并发两个独立eager调用;maxConcurrentCalls/max_concurrent_calls可设正整数。runner等当前组完成才读更多流调用,仅适用于无ledger的独立eager,每个函数还应限制自己启动的工作。
中断后检查错误中的attemptedCallIds/completedCallIds,或Python的snake_case名称;它们只有ID,不含结果、参数或驱动消息。副作用可能已发生,重试前读取权威应用状态。
contextBudget/context_budget限制下次输入字节和图片,可有无持久存储。压缩投影保留当前观察及必需工具关系;内存限制不意味着进程退出后可恢复。
完整轮次边界可用appendUserText/append_user_text排队人工指导,写入待处理输出后再追加。只接受文本,不接受任意工具输出或审批对象,也不重置请求预算。用于澄清当前任务;替换任务则先停止并等待旧运行,重读状态、重新批准新动作,保留旧记录,因为改指令不撤销效果。
持久恢复需ledger在独占运行所有权下保存每个检查点,只能从完整边界恢复。待处理或不确定动作须先对账。剩余预算及完成历史在恢复时保留;本地上下文压缩在ledger保留完整证据,并固定当前观察、安全检查、消息和推理,不授予权限。
每次保存接收独立完整检查点,包含完整批次及累积历史,包括副作用前后。大批次复制存储累计可能为平方级工作量,应选择合适存储;contextBudget只限制请求,不限制ledger存储。中断的pending检查点只包含最后保存前缀,可能缺少后续文字和未尝试建议,不授权重放。
含MCP时每个请求前保存pending;连接失败先查远端,pending不能自动恢复。保存的MCP声明去除authorization与自定义头,以SHA-256指纹代替服务器URL,原生请求仍用原URL。需轮换凭证放头中;改变URL路径或未识别查询会改变身份,需新运行。含原始MCP URL的检查点不能恢复;Node保存需crypto.subtle.digest。其他检查点输入输出仍属私有应用数据。
恢复时提供当前凭证并核对服务器及账户。代码解释器声明保留凭证名、域名但清除值,恢复需重供。MCP批准过滤器空always:{}或never:{}适用于全部工具。
初始输入或ledger有已批准但无匹配完成调用的MCP请求时,须提供approveMcp/approve_mcp;第一次保存或API请求前逐项重新询问,无论是否有ledger或contextBudget。已完成调用和先前拒绝保持不变;需新批准但无回调则停止。
本地检查自定义驱动
先运行预约或隔离桌面的本地演练,再调整;为实际页面状态、输入效果和清理补充检查。SDK验证不证明环境正确执行。每次改动后,报告成功前检查实际保存的表单、文件或应用记录。