OpenAI Computer use 文档

翻译一下 OpenAI Computer use 文档，供大家一起学习使用。

概述

Computer use 是我们 Computer-Using Agent (CUA) 模型 computer-use-preview 的实际应用，该模型结合了 GPT-4o 的视觉能力与高级推理功能，可模拟控制计算机界面并执行任务。

Computer use 通过 Responses API 提供，Chat Completions 接口暂不支持该功能。

当前 Computer use 处于测试阶段。由于该模型仍处于预览状态，可能存在安全漏洞和意外错误，建议不要在完全认证的环境或关键任务中依赖其输出。具体限制和风险防控措施请参阅下方的限制及安全最佳实践章节。使用 Computer Use 工具时须遵守 OpenAI 的使用政策和商业条款。

工作原理

Computer use 工具以循环方式工作。模型会发送计算机操作指令（如 click(x,y) 或 type(text)），您的代码在计算机或浏览器环境中执行这些操作后，将执行结果的截图返回给模型。

通过这种方式，您的代码可以模拟人类操作计算机界面的行为，而我们的模型则利用截图来理解环境状态并规划下一步操作。

这种循环机制可自动化完成需要点击、输入、滚动等操作的任务，例如预订航班、搜索商品或填写表单。

关于如何集成该工具的详细信息，请参阅下方的集成指南部分，或查看我们的示例应用仓库以配置环境并尝试集成方案。

CUA 示例应用

不同环境下集成 computer use 工具的示例

环境配置

在集成工具前，需准备好能够捕获屏幕截图并执行推荐操作的环境。出于安全考虑，建议使用沙盒环境。

配置本地浏览环境

配置本地虚拟机

集成 CUA 循环

在应用中集成 computer use 工具需遵循以下步骤：

1. 向模型发送请求 ：将 computer 工具作为可用工具之一，并指定显示尺寸和环境参数。首次请求时可包含环境的初始状态截图。
2. 接收模型响应 ：检查响应中是否包含 computer_call 条目。该工具调用包含推进任务目标的建议操作，例如点击指定坐标、输入文本、滚动或等待。
3. 执行请求的操作：通过代码在计算机或浏览器环境中执行对应操作。
4. 捕获更新后的状态：操作执行后，对环境的新状态进行截图。
5. 循环执行 ：将更新后的状态以 computer_call_output 形式发送新请求，循环该过程直至模型停止返回操作请求或您主动终止流程。

1. 向模型发送请求

使用配备 computer_use_preview 工具的 computer-use-preview 模型创建响应请求。该请求需包含环境参数和初始输入指令，可选包含环境初始状态截图。

注意：使用 computer_use_preview 工具时需将 truncation 参数设为 "auto"（默认情况下该参数处于禁用状态）。

发送 CUA 请求

import OpenAI from "openai";
const openai = new OpenAI();

const response = await openai.responses.create({
  model: "computer-use-preview",
  tools: [
    {
      type: "computer_use_preview",
      display_width: 1024,
      display_height: 768,
      environment: "browser", // 可选值："mac", "windows", "ubuntu"
    },
  ],
  input: [
    {
      role: "user",
      content: "Check the latest OpenAI news on bing.com.",
    },
    // 可选：包含环境初始状态截图
    // {
    //     type: "input_image",
    //     image_url: `data:image/png;base64,${screenshot_base64}`
    // }
  ],
  reasoning: {
    generate_summary: "concise",
  },
  truncation: "auto",
});

console.log(JSON.stringify(response.output, null, 2));

2. 接收建议操作

模型返回的响应可能包含 computer_call 条目、纯文本或其他工具调用，具体取决于对话状态。computer_call 条目可能包含点击、滚动、按键等操作（完整列表请参阅 API 参考）。以下示例为点击操作：

CUA 建议操作

"output": [
    {
        "type": "reasoning",
        "id": "rs_67cc...",
        "summary": [
            {
                "type": "summary_text",
                "text": "点击浏览器地址栏"
            }
        ]
    },
    {
        "type": "computer_call",
        "id": "cu_67cc...",
        "call_id": "call_zw3...",
        "action": {
            "type": "click",
            "button": "left",
            "x": 156,
            "y": 50
        },
        "pending_safety_checks": [],
        "status": "completed"
    }
]

推理条目

模型可能在某些操作的响应中返回 reasoning 条目。若存在此类条目，下次向 CUA 模型发送请求时必须包含这些推理条目。

注意：推理条目仅与生成它们的模型兼容。若在对话历史中混用多个模型，需过滤掉其他模型不兼容的推理条目。

安全检查

模型可能通过 pending_safety_check 参数返回安全检查信息，具体处理方式请参阅下方的确认安全检查章节。

3. 在环境中执行操作

在计算机或浏览器环境中执行对应操作。操作映射方式取决于具体环境，以下代码展示常见操作的实现示例：

PlaywrightDocker

执行操作

async function handleModelAction(vm, action) {
    // 根据 computer action（如点击、滚动等）
    // 在 Docker 环境中执行对应操作
  
    const actionType = action.type;
  
    try {
      switch (actionType) {
        case "click": {
          const { x, y, button = "left" } = action;
          const buttonMap = { left: 1, middle: 2, right: 3 };
          const b = buttonMap[button] || 1;
          console.log(`Action: click at (${x}, ${y}) with button '${button}'`);
          await dockerExec(
            `DISPLAY=${vm.display} xdotool mousemove ${x} ${y} click ${b}`,
            vm.containerName
          );
          break;
        }
  
        case "scroll": {
          const { x, y, scrollX, scrollY } = action;
          console.log(
            `Action: scroll at (${x}, ${y}) with offsets (scrollX=${scrollX}, scrollY=${scrollY})`
          );
          await dockerExec(
            `DISPLAY=${vm.display} xdotool mousemove ${x} ${y}`,
            vm.containerName
          );
          // 垂直滚动使用 button 4（上滚）和 button 5（下滚）
          if (scrollY !== 0) {
            const button = scrollY < 0 ? 4 : 5;
            const clicks = Math.abs(scrollY);
            for (let i = 0; i < clicks; i++) {
              await dockerExec(
                `DISPLAY=${vm.display} xdotool click ${button}`,
                vm.containerName
              );
            }
          }
          break;
        }
  
        case "keypress": {
          const { keys } = action;
          for (const k of keys) {
            console.log(`Action: keypress '${k}'`);
            // 常见按键映射（可根据需要扩展）
            if (k.includes("ENTER")) {
              await dockerExec(
                `DISPLAY=${vm.display} xdotool key 'Return'`,
                vm.containerName
              );
            } else if (k.includes("SPACE")) {
              await dockerExec(
                `DISPLAY=${vm.display} xdotool key 'space'`,
                vm.containerName
              );
            } else {
              await dockerExec(
                `DISPLAY=${vm.display} xdotool key '${k}'`,
                vm.containerName
              );
            }
          }
          break;
        }
  
        case "type": {
          const { text } = action;
          console.log(`Action: type text '${text}'`);
          await dockerExec(
            `DISPLAY=${vm.display} xdotool type '${text}'`,
            vm.containerName
          );
          break;
        }
  
        case "wait": {
          console.log(`Action: wait`);
          await new Promise((resolve) => setTimeout(resolve, 2000));
          break;
        }
  
        case "screenshot": {
          // 无需操作，每轮循环会自动截图
          console.log(`Action: screenshot`);
          break;
        }
  
        // 其他操作处理
  
        default:
          console.log("未识别的操作:", action);
      }
    } catch (e) {
      console.error("操作执行错误", action, ":", e);
    }
  }

4. 捕获更新后的截图

操作执行后，捕获环境的新状态截图，具体实现方式因环境而异：

PlaywrightDocker

捕获并发送更新后的截图

async function getScreenshot(vm) {
  // 获取原始字节格式的截图
  const cmd = `export DISPLAY=${vm.display} && import -window root png:-`;
  const screenshotBuffer = await dockerExec(cmd, vm.containerName, false);
  return screenshotBuffer;
}

5. 循环执行

获得截图后，可将其作为 computer_call_output 发送给模型以获取下一步操作。只要响应中包含 computer_call 条目，就继续循环执行。

循环执行步骤

import OpenAI from "openai";
const openai = new OpenAI();

async function computerUseLoop(instance, response) {
  /**
   * 持续执行 computer action 直至无 computer_call 返回
   */
  while (true) {
    const computerCalls = response.output.filter(
      (item) => item.type === "computer_call"
    );
    if (computerCalls.length === 0) {
      console.log("未找到 computer_call。模型输出:");
      response.output.forEach((item) => {
        console.log(JSON.stringify(item, null, 2));
      });
      break; // 无 computer_call 时退出循环
    }

    // 每次响应最多包含一个 computer_call
    const computerCall = computerCalls[0];
    const lastCallId = computerCall.call_id;
    const action = computerCall.action;

    // 执行操作（步骤3定义的函数）
    handleModelAction(instance, action);
    await new Promise((resolve) => setTimeout(resolve, 1000)); // 等待操作生效

    // 捕获操作后的截图（步骤4定义的函数）
    const screenshotBytes = await getScreenshot(instance);
    const screenshotBase64 = Buffer.from(screenshotBytes).toString("base64");

    // 将截图作为 computer_call_output 发送
    response = await openai.responses.create({
      model: "computer-use-preview",
      previous_response_id: response.id,
      tools: [
        {
          type: "computer_use_preview",
          display_width: 1024,
          display_height: 768,
          environment: "browser",
        },
      ],
      input: [
        {
          call_id: lastCallId,
          type: "computer_call_output",
          output: {
            type: "input_image",
            image_url: `data:image/png;base64,${screenshotBase64}`,
          },
        },
      ],
      truncation: "auto",
    });
  }

  return response;
}

对话历史管理

可使用 previous_response_id 参数将当前请求与之前响应关联。若不想自行管理对话历史，推荐使用此方法。

若不使用该参数，需确保在后续请求的输入数组中包含之前响应的所有输出条目（包括存在的推理条目）。

确认安全检查

我们在 API 中内置了安全检查机制以防止提示注入和模型错误，包括：

• 恶意指令检测：分析截图内容是否包含可能改变模型行为的对抗性内容 • 无关域名检测：根据对话历史评估当前 URL（若提供）的相关性 • 敏感域名检测：检测当前 URL（若提供）是否涉及敏感域名

当触发上述任一检查时，模型会在返回 computer_call 时通过 pending_safety_checks 参数返回安全警告：

待处理安全检查

"output": [
    {
        "type": "reasoning",
        "id": "rs_67cb...",
        "summary": [
            {
                "type": "summary_text",
                "text": "探索'文件'菜单选项"
            }
        ]
    },
    {
        "type": "computer_call",
        "id": "cu_67cb...",
        "call_id": "call_nEJ...",
        "action": {
            "type": "click",
            "button": "left",
            "x": 135,
            "y": 193
        },
        "pending_safety_checks": [
            {
                "id": "cu_sc_67cb...",
                "code": "malicious_instructions",
                "message": "检测到可能导致应用程序执行恶意或未授权操作的指令。如需继续，请确认此警告。"
            }
        ],
        "status": "completed"
    }
]

需在下个请求中将安全检查作为 acknowledged_safety_checks 传回方可继续。当收到 pending_safety_checks 时，应将操作移交给终端用户确认模型行为：

• malicious_instructions 和 irrelevant_domain：需用户复核模型行为并确认符合预期 • sensitive_domain：需确保用户实时监控模型在敏感网站的操作（可参考 Operator 的"监视模式"实现）

确认安全检查

import OpenAI from "openai";
const openai = new OpenAI();

const response = await openai.responses.create({
    model: "computer-use-preview",
    previous_response_id: "<previous_response_id>",
    tools: [{
        type: "computer_use_preview",
        display_width: 1024,
        display_height: 768,
        environment: "browser"
    }],
    input: [
        {
            "type": "computer_call_output",
            "call_id": "<call_id>",
            "acknowledged_safety_checks": [
                {
                    "id": "<safety_check_id>",
                    "code": "malicious_instructions",
                    "message": "检测到可能导致应用程序执行恶意或未授权操作的指令。如需继续，请确认此警告。"
                }
            ],
            "output": {
                "type": "computer_screenshot",
                "image_url": "<image_url>"
            }
        }
    ],
    truncation: "auto",
});

完整代码

完整实现应包含以下要素：

1. 环境初始化
2. 携带 computer 工具的首次模型请求
3. 执行模型建议操作的循环机制
4. 安全检查确认机制及用户操作确认流程

端到端集成示例请参考我们的 CUA 示例应用仓库。

CUA 示例应用

不同环境下集成 computer use 工具的示例

限制

建议将 computer-use-preview 模型用于基于浏览器的任务。该模型在非浏览器环境中可能更容易出现意外错误，例如目前在 OSWorld 上的任务完成率仅为 38.1%，表明其操作系统自动化能力尚不完善。更多模型细节和安全工作请参阅更新的系统报告。

其他需注意的限制：

• computer-use-preview 模型具有约束性的速率限制和功能支持（详见模型详情页） • 该工具不支持零数据保留（数据保留政策）

风险与安全

相比标准 API 功能或聊天界面，Computer use 在互联网交互中存在独特风险。建议遵循以下最佳实践：

高风险任务保持人工介入

避免涉及重大影响或高精度要求的任务。模型可能产生难以逆转的错误操作。虽然模型会对部分高风险操作请求用户确认，但该机制并非完全可靠。对于具有现实影响的