该 @langchain/openai 包为 OpenAI 内置工具提供 LangChain 兼容的包装器。这些工具可以绑定到 ChatOpenAI 使用 bindTools() or createAgent.
网络搜索工具
网络搜索工具允许 OpenAI 模型在生成响应之前搜索网络以获取最新信息。网络搜索支持三种主要类型：
- **非推理型网络搜索**：快速查询，模型将查询直接传递给搜索工具
- **使用推理模型的代理搜索**：模型主动管理搜索过程，分析结果并决定是否继续搜索
- **深度研究**：使用如
o3-deep-researchorgpt-5等具有高推理努力程度的模型进行扩展调查
const model = new ChatOpenAI({
model: "gpt-5.5",
});
// Basic usage
const response = await model.invoke(
"What was a positive news story from today?",
{
tools: [tools.webSearch()],
}
);域名过滤 - 将搜索结果限制在特定域名（最多 100 个）：
const response = await model.invoke("Latest AI research news", {
tools: [
tools.webSearch({
filters: {
allowedDomains: ["arxiv.org", "nature.com", "science.org"],
},
}),
],
});用户位置 - 根据地理位置优化搜索结果：
const response = await model.invoke("What are the best restaurants near me?", {
tools: [
tools.webSearch({
userLocation: {
type: "approximate",
country: "US",
city: "San Francisco",
region: "California",
timezone: "America/Los_Angeles",
},
}),
],
});仅缓存模式 - 禁用实时互联网访问：
const response = await model.invoke("Find information about OpenAI", {
tools: [
tools.webSearch({
externalWebAccess: false,
}),
],
});更多信息，请参阅 OpenAI 的网络搜索文档.
MCP 工具（模型上下文协议）
MCP 工具允许 OpenAI 模型连接到远程 MCP 服务器和 OpenAI 维护的服务连接器，使模型能够访问外部工具和服务。
使用 MCP 工具的方法有两种：
- **远程 MCP 服务器**：通过 URL 连接到任何公共 MCP 服务器
- **连接器**：使用 OpenAI 维护的流行服务包装器（如 Google Workspace 或 Dropbox）
远程 MCP 服务器 - 连接到任何 MCP 兼容的服务器：
const model = new ChatOpenAI({ model: "gpt-5.5" });
const response = await model.invoke("Roll 2d4+1", {
tools: [
tools.mcp({
serverLabel: "dmcp",
serverDescription: "A D&D MCP server for dice rolling",
serverUrl: "https://dmcp-server.deno.dev/sse",
requireApproval: "never",
}),
],
});服务连接器 - 使用 OpenAI 维护的流行服务连接器：
const response = await model.invoke("What's on my calendar today?", {
tools: [
tools.mcp({
serverLabel: "google_calendar",
connectorId: "connector_googlecalendar",
authorization: "<oauth-access-token>",
requireApproval: "never",
}),
],
});更多信息，请参阅 OpenAI 的 MCP 文档.
代码解释器工具
代码解释器工具允许模型在沙盒环境中编写和运行 Python 代码来解决复杂问题。
使用代码解释器的场景：
- 数据分析：处理具有不同数据和格式的文件
- 文件生成：创建包含数据和图表图像的文件
- 迭代编码：通过迭代编写和运行代码来解决问题
- 视觉智能：裁剪、缩放、旋转和转换图像
const model = new ChatOpenAI({ model: "gpt-5.5" });
// Basic usage with auto container (default 1GB memory)
const response = await model.invoke("Solve the equation 3x + 11 = 14", {
tools: [tools.codeInterpreter()],
});内存配置 - 选择 1GB（默认）、4GB、16GB 或 64GB：
const response = await model.invoke(
"Analyze this large dataset and create visualizations",
{
tools: [
tools.codeInterpreter({
container: { memoryLimit: "4g" },
}),
],
}
);使用文件 - 使上传的文件可供代码使用：
const response = await model.invoke("Process the uploaded CSV file", {
tools: [
tools.codeInterpreter({
container: {
memoryLimit: "4g",
fileIds: ["file-abc123", "file-def456"],
},
}),
],
});显式容器 - 使用预先创建的容器 ID：
const response = await model.invoke("Continue working with the data", {
tools: [
tools.codeInterpreter({
container: "cntr_abc123",
}),
],
});> **注意**：容器在 20 分钟无活动后过期。虽然内部称为"代码解释器"，但模型将其称为"python 工具" - 如需明确提示，请在提示中使用"python 工具"。
更多信息，请参阅 OpenAI 代码解释器文档.
文件搜索工具
文件搜索工具允许模型使用语义搜索和关键字搜索来搜索文件中的相关信息。它支持从存储在向量存储中的先前上传文件知识库中进行检索。
前提条件：使用文件搜索前，您必须：
- 使用以下方式将文件上传到文件 API
purpose: "assistants" - 创建向量存储
- 将文件添加到向量存储
const model = new ChatOpenAI({ model: "gpt-5.5" });
const response = await model.invoke("What is deep research by OpenAI?", {
tools: [
tools.fileSearch({
vectorStoreIds: ["vs_abc123"],
// maxNumResults: 5, // Limit results for lower latency
// filters: { type: "eq", key: "category", value: "blog" }, // Metadata filtering
// filters: { type: "and", filters: [ // Compound filters (AND/OR)
// { type: "eq", key: "category", value: "technical" },
// { type: "gte", key: "year", value: 2024 },
// ]},
// rankingOptions: { scoreThreshold: 0.8, ranker: "auto" }, // Customize scoring
}),
],
});过滤运算符： eq （等于）， ne （不等于）， gt （大于）， gte （大于或等于）， lt （小于）， lte （小于或等于）。
更多信息，请参阅 OpenAI 文件搜索文档.
图像生成工具
图像生成工具允许模型使用文本提示和可选的图像输入来生成或编辑图像。它利用 GPT Image 模型并自动优化文本输入以提高性能。
图像生成的用途：
- 从文本创建图像：从详细文本描述生成图像
- 编辑现有图像：根据文本指令修改图像
- 多轮图像编辑：在对话轮次中迭代优化图像
- 多种输出格式：支持 PNG、JPEG 和 WebP 格式
const model = new ChatOpenAI({ model: "gpt-5.5" });
// Basic usage - generate an image
const response = await model.invoke(
"Generate an image of a gray tabby cat hugging an otter with an orange scarf",
{ tools: [tools.imageGeneration()] }
);
// Access the generated image (base64-encoded)
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"));
}自定义尺寸和质量 - 配置输出尺寸和质量：
const response = await model.invoke("Draw a beautiful sunset over mountains", {
tools: [
tools.imageGeneration({
size: "1536x1024", // Landscape format (also: "1024x1024", "1024x1536", "auto")
quality: "high", // Quality level (also: "low", "medium", "auto")
}),
],
});输出格式和压缩 - 选择格式和压缩级别：
const response = await model.invoke("Create a product photo", {
tools: [
tools.imageGeneration({
outputFormat: "jpeg", // Format (also: "png", "webp")
outputCompression: 90, // Compression 0-100 (for JPEG/WebP)
}),
],
});透明背景 - 生成带透明度的图像：
const response = await model.invoke(
"Create a logo with transparent background",
{
tools: [
tools.imageGeneration({
background: "transparent", // Background type (also: "opaque", "auto")
outputFormat: "png",
}),
],
}
);使用部分图像进行流式传输 - 在生成过程中获取视觉反馈：
const response = await model.invoke("Draw a detailed fantasy castle", {
tools: [
tools.imageGeneration({
partialImages: 2, // Number of partial images (0-3)
}),
],
});强制图像生成 - 确保模型使用图像生成工具：
const response = await model.invoke("A serene lake at dawn", {
tools: [tools.imageGeneration()],
tool_choice: { type: "image_generation" },
});多轮编辑 - 在对话轮次中优化图像：
// First turn: generate initial image
const response1 = await model.invoke("Draw a red car", {
tools: [tools.imageGeneration()],
});
// Second turn: edit the image
const response2 = await model.invoke(
[response1, new HumanMessage("Now change the car color to blue")],
{ tools: [tools.imageGeneration()] }
);> **提示技巧**：使用"绘制"或"编辑"等术语以获得最佳效果。对于组合图像，请说"通过添加此元素来编辑第一张图像"，而不是"组合"或"合并"。
支持的模型： gpt-4o, gpt-4o-mini, gpt-5.5, gpt-5.4-mini, gpt-5.4-nano, o3
更多信息，请参阅 OpenAI 图像生成文档.
计算机使用工具
计算机使用工具允许模型通过模拟鼠标点击、键盘输入、滚动等操作来控制计算机界面。它使用 OpenAI 的计算机使用代理（CUA）模型来理解屏幕截图并建议操作。
> **测试版**：计算机使用功能处于测试阶段。仅在沙盒环境中使用，切勿用于高风险或需要身份验证的任务。对于重要决策，请始终实施人工介入。
工作原理：该工具在连续循环中运行：
- 模型发送计算机操作（点击、输入、滚动等）
- 您的代码在受控环境中执行这些操作
- 您截取结果屏幕截图
- 将屏幕截图发送回模型
- 重复直到任务完成
const model = new ChatOpenAI({ model: "computer-use-preview" });
// With execute callback for automatic action handling
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();
}
// Handle other actions...
return captureScreenshot();
},
});
const llmWithComputer = model.bindTools([computer]);
const response = await llmWithComputer.invoke(
"Check the latest news on bing.com"
);更多信息，请参阅 OpenAI 计算机使用文档.
本地 shell 工具
本地 Shell 工具允许模型在您提供的计算机上本地运行 shell 命令。命令在您自己的运行时环境中执行——API 仅返回指令。
> **安全警告**: Running arbitrary shell commands can be dangerous. Always sandbox execution or add strict allow/deny-lists before forwarding commands to the system shell. > **注意**：此工具设计用于与 Codex CLI 和 codex-mini-latest model.
const execAsync = promisify(exec);
const model = new ChatOpenAI({ model: "codex-mini-latest" });
// With execute callback for automatic command handling
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(
"List files in the current directory"
);操作属性：模型返回具有以下属性的操作：
- -
command- 要执行的 argv 参数数组 - -
env- 要设置的环境变量 - -
working_directory- 运行命令的目录 - -
timeout_ms- 建议超时时间（强制执行您自己的限制） - -
user- 可选的用户身份运行命令
更多信息，请参阅 OpenAI 本地 Shell 文档.
Shell 工具
Shell 工具允许模型通过您的集成运行 shell 命令。与本地 Shell 不同，此工具支持并发执行多个命令，专为 gpt-5.1.
> **安全警告**: Running arbitrary shell commands can be dangerous. Always sandbox execution or add strict allow/deny-lists before forwarding commands to the system shell.
使用案例:
- 自动化文件系统或进程诊断 – e.g., "find the largest PDF under ~/Documents"
- 扩展模型能力 – 使用内置 UNIX 工具、Python 运行时和其他 CLI
- 运行多步骤构建和测试流程 – 链接命令如
pip install和pytest - 复杂的代理编码工作流 – 与
apply_patch配合使用进行文件操作
const model = new ChatOpenAI({ model: "gpt-5.1" });
// With execute callback for automatic command handling
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(
"Find the largest PDF file in ~/Documents"
);操作属性：模型返回具有以下属性的操作：
- -
commands- 要执行的 shell 命令数组（可并发运行） - -
timeout_ms- 可选的超时时间（毫秒）（强制执行您自己的限制） - -
max_output_length- 每个命令返回的最大字符数（可选）
返回格式：你的 execute 函数应返回一个 ShellResult:
interface ShellResult {
output: Array<{
stdout: string;
stderr: string;
outcome: { type: "exit"; exit_code: number } | { type: "timeout" };
}>;
maxOutputLength?: number | null; // Pass back from action if provided
}> **注意**：仅通过 Responses API 可用，使用 gpt-5.1。该 timeout_ms 来自模型的建议仅作提示——请始终自行强制执行限制。
更多信息，请参阅 OpenAI Shell 文档.
应用补丁工具
应用补丁工具允许模型提出结构化差异（diff），由您的集成来应用。这使得迭代式、多步骤的代码编辑工作流成为可能，模型可以在代码库中创建、更新和删除文件。
使用场景:
- 多文件重构 – 重命名符号、提取辅助函数或重新组织模块
- 缺陷修复 – 让模型既诊断问题又生成精确的补丁
- 测试和文档生成 – 创建新的测试文件、测试夹具和文档
- 迁移和机械编辑 – 应用重复的、结构化的更新
> **安全警告**：应用补丁可能会修改代码库中的文件。请务必验证路径、实施备份，并考虑使用沙箱环境。 > **注意**：此工具设计用于与 gpt-5.1 model.
const model = new ChatOpenAI({ model: "gpt-5.1" });
// With execute callback for automatic patch handling
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 `Created ${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 `Updated ${operation.path}`;
}
if (operation.type === "delete_file") {
await fs.unlink(operation.path);
return `Deleted ${operation.path}`;
}
return "Unknown operation type";
},
});
const llmWithPatch = model.bindTools([patchTool]);
const response = await llmWithPatch.invoke(
"Rename the fib() function to fibonacci() in lib/fib.py"
);操作类型：模型返回具有以下属性的操作：
- -
create_file– 在以下位置创建新文件path，内容来自diff - -
update_file– 修改位于以下位置的现有文件path，使用 V4A diff 格式在diff - -
delete_file– 删除位于以下位置的文件path
最佳实践:
- 路径验证：防止目录遍历，并将编辑限制在允许的目录范围内
- 备份：考虑在应用补丁前备份文件
- 错误处理：返回描述性错误消息，以便模型能够恢复
- 原子性：决定是否需要"全有或全无"语义（如果任何补丁失败则回滚）
更多信息，请参阅 OpenAI 应用补丁文档.