> ## Documentation Index
> Fetch the complete documentation index at: https://cndoc-langchain.site/llms.txt
> Use this file to discover all available pages before exploring further.

# OpenAI 集成

> 使用 LangChain JavaScript 与 OpenAI 工具集成。

`@langchain/openai` 包为 OpenAI 的内置工具提供了与 LangChain 兼容的封装。这些工具可以使用 `bindTools()` 或 [`createAgent`](https://reference.langchain.com/javascript/langchain/index/createAgent) 绑定到 `ChatOpenAI`。

### 网络搜索工具

网络搜索工具允许 OpenAI 模型在生成响应之前搜索网络以获取最新信息。网络搜索支持三种主要类型：

1. **非推理网络搜索**：快速查询，模型将查询直接传递给搜索工具
2. **使用推理模型的代理搜索**：模型主动管理搜索过程，分析结果并决定是否继续搜索
3. **深度研究**：使用 `o3-deep-research` 或 `gpt-5` 等具有高推理能力的模型进行扩展调查

```typescript theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
import { ChatOpenAI, tools } from "@langchain/openai";

const model = new ChatOpenAI({
  model: "gpt-5.4",
});

// 基本用法
const response = await model.invoke("今天有什么积极的新闻故事？", {
  tools: [tools.webSearch()],
});
```

**域名过滤** - 将搜索结果限制在特定域名（最多 100 个）：

```typescript theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
const response = await model.invoke("最新的 AI 研究新闻", {
  tools: [
    tools.webSearch({
      filters: {
        allowedDomains: ["arxiv.org", "nature.com", "science.org"],
      },
    }),
  ],
});
```

**用户位置** - 根据地理位置优化搜索结果：

```typescript theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
const response = await model.invoke("我附近最好的餐厅有哪些？", {
  tools: [
    tools.webSearch({
      userLocation: {
        type: "approximate",
        country: "US",
        city: "San Francisco",
        region: "California",
        timezone: "America/Los_Angeles",
      },
    }),
  ],
});
```

**仅缓存模式** - 禁用实时互联网访问：

```typescript theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
const response = await model.invoke("查找有关 OpenAI 的信息", {
  tools: [
    tools.webSearch({
      externalWebAccess: false,
    }),
  ],
});
```

更多信息，请参阅 [OpenAI 的网络搜索文档](https://platform.openai.com/docs/guides/tools-web-search)。

### MCP 工具（模型上下文协议）

MCP 工具允许 OpenAI 模型连接到远程 MCP 服务器和 OpenAI 维护的服务连接器，使模型能够访问外部工具和服务。

使用 MCP 工具有两种方式：

1. **远程 MCP 服务器**：通过 URL 连接到任何公共 MCP 服务器
2. **连接器**：使用 OpenAI 维护的流行服务（如 Google Workspace 或 Dropbox）的封装

**远程 MCP 服务器** - 连接到任何兼容 MCP 的服务器：

```typescript theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
import { ChatOpenAI, tools } from "@langchain/openai";

const model = new ChatOpenAI({ model: "gpt-5.4" });

const response = await model.invoke("掷 2d4+1", {
  tools: [
    tools.mcp({
      serverLabel: "dmcp",
      serverDescription: "用于掷骰子的 D&D MCP 服务器",
      serverUrl: "https://dmcp-server.deno.dev/sse",
      requireApproval: "never",
    }),
  ],
});
```

**服务连接器** - 使用 OpenAI 维护的流行服务连接器：

```typescript theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
const response = await model.invoke("我今天日历上有什么？", {
  tools: [
    tools.mcp({
      serverLabel: "google_calendar",
      connectorId: "connector_googlecalendar",
      authorization: "<oauth-access-token>",
      requireApproval: "never",
    }),
  ],
});
```

更多信息，请参阅 [OpenAI 的 MCP 文档](https://platform.openai.com/docs/guides/tools-remote-mcp)。

### 代码解释器工具

代码解释器工具允许模型在沙盒环境中编写和运行 Python 代码以解决复杂问题。

使用代码解释器用于：

* **数据分析**：处理具有不同数据和格式的文件
* **文件生成**：创建包含数据和图表图像的文件
* **迭代编码**：迭代编写和运行代码以解决问题
* **视觉智能**：裁剪、缩放、旋转和变换图像

```typescript theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
import { ChatOpenAI, tools } from "@langchain/openai";

const model = new ChatOpenAI({ model: "gpt-5.4" });

// 基本用法，使用自动容器（默认 1GB 内存）
const response = await model.invoke("解方程 3x + 11 = 14", {
  tools: [tools.codeInterpreter()],
});
```

**内存配置** - 从 1GB（默认）、4GB、16GB 或 64GB 中选择：

```typescript theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
const response = await model.invoke("分析这个大型数据集并创建可视化", {
  tools: [
    tools.codeInterpreter({
      container: { memoryLimit: "4g" },
    }),
  ],
});
```

**使用文件** - 使上传的文件可供代码使用：

```typescript theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
const response = await model.invoke("处理上传的 CSV 文件", {
  tools: [
    tools.codeInterpreter({
      container: {
        memoryLimit: "4g",
        fileIds: ["file-abc123", "file-def456"],
      },
    }),
  ],
});
```

**显式容器** - 使用预创建的容器 ID：

```typescript theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
const response = await model.invoke("继续处理数据", {
  tools: [
    tools.codeInterpreter({
      container: "cntr_abc123",
    }),
  ],
});
```

> **注意**：容器在 20 分钟不活动后会过期。虽然称为“代码解释器”，但模型将其称为“python 工具” - 对于显式提示，请在提示中要求“python 工具”。

更多信息，请参阅 [OpenAI 的代码解释器文档](https://platform.openai.com/docs/guides/tools-code-interpreter)。

### 文件搜索工具

文件搜索工具允许模型使用语义和关键词搜索搜索您的文件以查找相关信息。它支持从存储在向量存储中的先前上传文件的知识库中进行检索。

**先决条件**：使用文件搜索之前，您必须：

1. 使用 `purpose: "assistants"` 将文件上传到文件 API
2. 创建向量存储
3. 将文件添加到向量存储

```typescript theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
import { ChatOpenAI, tools } from "@langchain/openai";

const model = new ChatOpenAI({ model: "gpt-5.4" });

const response = await model.invoke("什么是 OpenAI 的深度研究？", {
  tools: [
    tools.fileSearch({
      vectorStoreIds: ["vs_abc123"],
      // maxNumResults: 5, // 限制结果以降低延迟
      // filters: { type: "eq", key: "category", value: "blog" }, // 元数据过滤
      // filters: { type: "and", filters: [                       // 复合过滤器 (AND/OR)
      //   { type: "eq", key: "category", value: "technical" },
      //   { type: "gte", key: "year", value: 2024 },
      // ]},
      // rankingOptions: { scoreThreshold: 0.8, ranker: "auto" }, // 自定义评分
    }),
  ],
});
```

过滤运算符：`eq`（等于）、`ne`（不等于）、`gt`（大于）、`gte`（大于或等于）、`lt`（小于）、`lte`（小于或等于）。

更多信息，请参阅 [OpenAI 的文件搜索文档](https://platform.openai.com/docs/guides/tools-file-search)。

### 图像生成工具

图像生成工具允许模型使用文本提示和可选的图像输入生成或编辑图像。它利用 GPT 图像模型，并自动优化文本输入以提高性能。

使用图像生成用于：

* **从文本创建图像**：根据详细的文本描述生成图像
* **编辑现有图像**：根据文本指令修改图像
* **多轮图像编辑**：在对话轮次中迭代优化图像
* **多种输出格式**：支持 PNG、JPEG 和 WebP 格式

```typescript theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
import { ChatOpenAI, tools } from "@langchain/openai";

const model = new ChatOpenAI({ model: "gpt-5.4" });

// 基本用法 - 生成图像
const response = await model.invoke(
  "生成一张灰色虎斑猫拥抱一只戴橙色围巾的水獭的图像",
  { tools: [tools.imageGeneration()] },
);

// 访问生成的图像（base64 编码）
const imageOutput = response.additional_kwargs.tool_outputs?.find(
  (output) => output.type === "image_generation_call",
);
if (imageOutput?.result) {
  const fs = await import("fs");
  fs.writeFileSync("output.png", Buffer.from(imageOutput.result, "base64"));
}
```

**自定义尺寸和质量** - 配置输出尺寸和质量：

```typescript theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
const response = await model.invoke("绘制山脉上方美丽的日落", {
  tools: [
    tools.imageGeneration({
      size: "1536x1024", // 横向格式（还有："1024x1024"、"1024x1536"、"auto"）
      quality: "high", // 质量级别（还有："low"、"medium"、"auto"）
    }),
  ],
});
```

**输出格式和压缩** - 选择格式和压缩级别：

```typescript theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
const response = await model.invoke("创建产品照片", {
  tools: [
    tools.imageGeneration({
      outputFormat: "jpeg", // 格式（还有："png"、"webp"）
      outputCompression: 90, // 压缩 0-100（适用于 JPEG/WebP）
    }),
  ],
});
```

**透明背景** - 生成具有透明度的图像：

```typescript theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
const response = await model.invoke("创建具有透明背景的徽标", {
  tools: [
    tools.imageGeneration({
      background: "transparent", // 背景类型（还有："opaque"、"auto"）
      outputFormat: "png",
    }),
  ],
});
```

**带部分图像的流式传输** - 在生成过程中获取视觉反馈：

```typescript theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
const response = await model.invoke("绘制详细的奇幻城堡", {
  tools: [
    tools.imageGeneration({
      partialImages: 2, // 部分图像数量（0-3）
    }),
  ],
});
```

**强制图像生成** - 确保模型使用图像生成工具：

```typescript theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
const response = await model.invoke("黎明时分宁静的湖泊", {
  tools: [tools.imageGeneration()],
  tool_choice: { type: "image_generation" },
});
```

**多轮编辑** - 在对话轮次中优化图像：

```typescript theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
// 第一轮：生成初始图像
const response1 = await model.invoke("绘制一辆红色汽车", {
  tools: [tools.imageGeneration()],
});

// 第二轮：编辑图像
const response2 = await model.invoke(
  [response1, new HumanMessage("现在将汽车颜色改为蓝色")],
  { tools: [tools.imageGeneration()] },
);
```

> **提示技巧**：使用“绘制”或“编辑”等术语以获得最佳效果。对于组合图像，请说“通过添加此元素编辑第一张图像”，而不是“组合”或“合并”。

支持的模型：`gpt-4o`、`gpt-4o-mini`、`gpt-5.4`、`gpt-5.4-mini`、`gpt-5.4-nano`、`o3`

更多信息，请参阅 [OpenAI 的图像生成文档](https://platform.openai.com/docs/guides/tools-image-generation)。

### 计算机使用工具

计算机使用工具允许模型通过模拟鼠标点击、键盘输入、滚动等来控制计算机界面。它使用 OpenAI 的计算机使用代理（CUA）模型来理解屏幕截图并建议操作。

> **测试版**：计算机使用处于测试版阶段。仅在沙盒环境中使用，不要用于高风险或需要身份验证的任务。对于重要决策，始终实施Human in the Loop。

**工作原理**：该工具在连续循环中运行：

1. 模型发送计算机操作（点击、输入、滚动等）
2. 您的代码在受控环境中执行这些操作
3. 您捕获结果的屏幕截图
4. 将屏幕截图发送回模型
5. 重复直到任务完成

```typescript theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
import { ChatOpenAI, tools } from "@langchain/openai";

const model = new ChatOpenAI({ model: "computer-use-preview" });

// 使用执行回调进行自动操作处理
const computer = tools.computerUse({
  displayWidth: 1024,
  displayHeight: 768,
  environment: "browser",
  execute: async (action) => {
    if (action.type === "screenshot") {
      return captureScreenshot();
    }
    if (action.type === "click") {
      await page.mouse.click(action.x, action.y, { button: action.button });
      return captureScreenshot();
    }
    if (action.type === "type") {
      await page.keyboard.type(action.text);
      return captureScreenshot();
    }
    if (action.type === "scroll") {
      await page.mouse.move(action.x, action.y);
      await page.evaluate(
        `window.scrollBy(${action.scroll_x}, ${action.scroll_y})`,
      );
      return captureScreenshot();
    }
    // 处理其他操作...
    return captureScreenshot();
  },
});

const llmWithComputer = model.bindTools([computer]);
const response = await llmWithComputer.invoke("查看 bing.com 上的最新新闻");
```

更多信息，请参阅 [OpenAI 的计算机使用文档](https://platform.openai.com/docs/guides/tools-computer-use)。

### 本地 Shell 工具

本地 Shell 工具允许模型在您提供的机器上本地运行 shell 命令。命令在您自己的运行时中执行——API 仅返回指令。

> **安全警告**：运行任意 shell 命令可能很危险。在将命令转发到系统 shell 之前，始终对执行进行沙盒处理或添加严格的允许/拒绝列表。
> **注意**：此工具旨在与 [Codex CLI](https://github.com/openai/codex) 和 `codex-mini-latest` 模型一起使用。

```typescript theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
import { ChatOpenAI, tools } from "@langchain/openai";
import { exec } from "child_process";
import { promisify } from "util";

const execAsync = promisify(exec);
const model = new ChatOpenAI({ model: "codex-mini-latest" });

// 使用执行回调进行自动命令处理
const shell = tools.localShell({
  execute: async (action) => {
    const { command, env, working_directory, timeout_ms } = action;
    const result = await execAsync(command.join(" "), {
      cwd: working_directory ?? process.cwd(),
      env: { ...process.env, ...env },
      timeout: timeout_ms ?? undefined,
    });
    return result.stdout + result.stderr;
  },
});

const llmWithShell = model.bindTools([shell]);
const response = await llmWithShell.invoke("列出当前目录中的文件");
```

**操作属性**：模型返回具有以下属性的操作：

* `command` - 要执行的 argv 令牌数组
* `env` - 要设置的环境变量
* `working_directory` - 运行命令的目录
* `timeout_ms` - 建议的超时时间（请自行强制执行限制）
* `user` - 可选的运行命令的用户

更多信息，请参阅 [OpenAI 的本地 Shell 文档](https://platform.openai.com/docs/guides/tools-local-shell)。

### Shell 工具

Shell 工具允许模型通过您的集成运行 shell 命令。与本地 Shell 不同，此工具支持同时执行多个命令，并且专为 `gpt-5.1` 设计。

> **安全警告**：运行任意 shell 命令可能很危险。在将命令转发到系统 shell 之前，始终对执行进行沙盒处理或添加严格的允许/拒绝列表。

**用例**：

* **自动化文件系统或进程诊断** – 例如，“查找 \~/Documents 下最大的 PDF”
* **扩展模型能力** – 使用内置的 UNIX 实用程序、Python 运行时和其他 CLI
* **运行多步骤构建和测试流程** – 链接 `pip install` 和 `pytest` 等命令
* **复杂的代理编码工作流** – 与 `apply_patch` 一起用于文件操作

```typescript theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
import { ChatOpenAI, tools } from "@langchain/openai";
import { exec } from "node:child_process/promises";

const model = new ChatOpenAI({ model: "gpt-5.1" });

// 使用执行回调进行自动命令处理
const shellTool = tools.shell({
  execute: async (action) => {
    const outputs = await Promise.all(
      action.commands.map(async (cmd) => {
        try {
          const { stdout, stderr } = await exec(cmd, {
            timeout: action.timeout_ms ?? undefined,
          });
          return {
            stdout,
            stderr,
            outcome: { type: "exit" as const, exit_code: 0 },
          };
        } catch (error) {
          const timedOut = error.killed && error.signal === "SIGTERM";
          return {
            stdout: error.stdout ?? "",
            stderr: error.stderr ?? String(error),
            outcome: timedOut
              ? { type: "timeout" as const }
              : { type: "exit" as const, exit_code: error.code ?? 1 },
          };
        }
      }),
    );
    return {
      output: outputs,
      maxOutputLength: action.max_output_length,
    };
  },
});

const llmWithShell = model.bindTools([shellTool]);
const response = await llmWithShell.invoke(
  "查找 ~/Documents 中最大的 PDF 文件",
);
```

**操作属性**：模型返回具有以下属性的操作：

* `commands` - 要执行的 shell 命令数组（可以并发运行）
* `timeout_ms` - 可选的超时时间（毫秒）（请自行强制执行限制）
* `max_output_length` - 可选的每个命令返回的最大字符数

**返回格式**：您的执行函数应返回 `ShellResult`：

```typescript theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
interface ShellResult {
  output: Array<{
    stdout: string;
    stderr: string;
    outcome: { type: "exit"; exit_code: number } | { type: "timeout" };
  }>;
  maxOutputLength?: number | null; // 如果提供，则从操作中传回
}
```

> **注意**：仅通过 Responses API 与 `gpt-5.1` 一起可用。模型提供的 `timeout_ms` 仅是一个提示——始终强制执行您自己的限制。

更多信息，请参阅 [OpenAI 的 Shell 文档](https://platform.openai.com/docs/guides/tools-shell)。

### 应用补丁工具

应用补丁工具允许模型提出结构化差异，您的集成可以应用这些差异。这使得迭代的多步骤代码编辑工作流成为可能，模型可以在您的代码库中创建、更新和删除文件。

**何时使用**：

* **多文件重构** – 重命名符号、提取辅助函数或重组模块
* **错误修复** – 让模型诊断问题并发出精确的补丁
* **测试和文档生成** – 创建新的测试文件、夹具和文档
* **迁移和机械编辑** – 应用重复的、结构化的更新

> **安全警告**：应用补丁可能会修改您代码库中的文件。始终验证路径、实施备份并考虑沙盒处理。
> **注意**：此工具旨在与 `gpt-5.1` 模型一起使用。

```typescript theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
import { ChatOpenAI, tools } from "@langchain/openai";
import { applyDiff } from "@openai/agents";
import * as fs from "fs/promises";

const model = new ChatOpenAI({ model: "gpt-5.1" });

// 使用执行回调进行自动补丁处理
const patchTool = tools.applyPatch({
  execute: async (operation) => {
    if (operation.type === "create_file") {
      const content = applyDiff("", operation.diff, "create");
      await fs.writeFile(operation.path, content);
      return `已创建 ${operation.path}`;
    }
    if (operation.type === "update_file") {
      const current = await fs.readFile(operation.path, "utf-8");
      const newContent = applyDiff(current, operation.diff);
      await fs.writeFile(operation.path, newContent);
      return `已更新 ${operation.path}`;
    }
    if (operation.type === "delete_file") {
      await fs.unlink(operation.path);
      return `已删除 ${operation.path}`;
    }
    return "未知操作类型";
  },
});

const llmWithPatch = model.bindTools([patchTool]);
const response = await llmWithPatch.invoke(
  "将 lib/fib.py 中的 fib() 函数重命名为 fibonacci()",
);
```

**操作类型**：模型返回具有以下属性的操作：

* `create_file` – 在 `path` 创建一个新文件，内容来自 `diff`
* `update_file` – 使用 V4A diff 格式在 `diff` 中修改 `path` 处的现有文件
* `delete_file` – 删除 `path` 处的文件

**最佳实践**：

* **路径验证**：防止目录遍历并将编辑限制在允许的目录中
* **备份**：考虑在应用补丁之前备份文件
* **错误处理**：返回描述性错误消息以便模型可以恢复
* **原子性**：决定是否需要“全有或全无”语义（如果任何补丁失败则回滚）

更多信息，请参阅 [OpenAI 的应用补丁文档](https://platform.openai.com/docs/guides/tools-apply-patch)。

***

<div className="source-links">
  <Callout icon="terminal-2">
    [将这些文档](/use-these-docs)通过 MCP 连接到 Claude、VSCode
    等，以获取实时答案。
  </Callout>

  <Callout icon="edit">
    [在 GitHub
    上编辑此页面](https://github.com/langchain-ai/docs/edit/main/src/oss/javascript/integrations/tools/openai.mdx)
    或 [提交问题](https://github.com/langchain-ai/docs/issues/new/choose)。
  </Callout>
</div>