---
格式版本: 2
标题: "Reference – Plugins | OpenAI Developers"
原文链接: "https://developers.openai.com/plugins/reference"
发布日期: "2026-09-02"
发布时间校准状态: "found"
发布时间需复核: "否"
发布时间来源: "rule:local:strict_original_body"
发布时间证据: "Published Time: Wed, 02 Sep 2026 01:58:19 GMT"
发布时间校准原因: "规则确认唯一严格发布时间，来源 local:strict_original_body"
发布时间校准置信度: "high"
发布时间候选数量: 4
发布时间严格候选数量: 1
发布时间原页读取状态: "source template page reused from URL open"
发布时间未找到原因: ""
发布时间校准时间: "2026-09-02T10:25:31+08:00"
发布时间仲裁状态: "skipped"
发布时间仲裁尝试次数: 0
发布时间仲裁耗时毫秒: 0
发现时间: "2026-09-02T10:18:13+08:00"
入库时间: "2026-09-02T02:25:31.536Z"
来源平台: "固定入口"
搜索渠道: "fixed_url"
搜索词: "https://developers.openai.com/blog"
匹配关键词:
  - "deployment"
  - "performance"
  - "latency"
  - "throughput"
  - "AI"
相关厂家:
  - "OpenAI"
  - "Meta"
  - "Microsoft"
  - "AWS"
  - "Google"
  - "Oracle"
相关专家:
  []
内容类型: "网页"
抓取工具: "Jina Reader"
清洗工具: "Jina Reader Markdown + Defuddle/Readability 正文提取"
原始附件:
  []
AI优质: "否"
AI打分: 23
AI分档: "非优质"
AI质检状态: "不通过"
AI打分理由: "正文为OpenAI官方开发者文档中的Plugin UI reference，仅描述ChatGPT插件UI扩展、MCP Apps桥接、window.openai API和文件上传等开发接口，与超节点、AI Rack、机架级基础设施完全无关，属于强否决项（主题不相关）。来源虽为官方，权威性较高，但无任何超节点相关事实、技术细节或商业部署信号，完整性虽高但不能改变业务准入结论。"
AI质检模型: "zj-deepseek-v4-flash"
AI质检时间: "2026-09-02T12:14:12+08:00"
AI主题相关性: 0
AI来源权威性: 12
AI新颖性: 3
AI技术细节: 0
AI商业部署信号: 0
AI完整性: 8
AI评分提示词版本: "v17-精简生产版"
AI评分提示词SHA256: "48fb9777f386026761b4873eaff30807694fb11e9b352d7c69bf2dfde750cc7d"
AI评分知识库版本: "knowledge_base_v1-20260819+runtime.66"
AI评分知识库SHA256: "392aeec055aaeafa7a3d419bc23a4eb8c9dd2456cb3dcb199200ba4394eda140"
AI评分知识库检索词: "[\"OpenAI\",\"https://developers.openai.com/blog\",\"RAS\",\"NPU\",\"Google\",\"Meta\",\"Microsoft\",\"UI\",\"URL\",\"GMT\",\"API\",\"GPT-5.6\"]"
AI评分知识库命中: "[{\"id\":\"july-correct-0033\",\"title\":\"Microsoft, Alphabet, Meta Pivot from Buy to Build in AI\",\"sourceType\":\"labeled_article\",\"time\":\"2026-07\",\"matchedTerms\":[\"OpenAI\",\"RAS\",\"Google\",\"Meta\",\"Microsoft\",\"UI\",\"URL\",\"API\",\"GPT-5.6\"],\"rank\":-19.35374838648524},{\"id\":\"runtime-51cfe3db04ed0bd3efb5e0e3\",\"title\":\"The full stack behind abundant intelligence\",\"sourceType\":\"ai_excellent_article\",\"time\":\"2026-08-25\",\"matchedTerms\":[\"OpenAI\",\"RAS\",\"Microsoft\",\"UI\",\"URL\",\"API\",\"GPT-5.6\"],\"rank\":-14.657085376136065},{\"id\":\"july-correct-0018\",\"title\":\"AMD, Cerebras partner on joint Helios rack-scale AI inference platform\",\"sourceType\":\"labeled_article\",\"time\":\"2026-07\",\"matchedTerms\":[\"OpenAI\",\"RAS\",\"Meta\",\"Microsoft\",\"URL\",\"GPT-5.6\"],\"rank\":-13.306060693915867},{\"id\":\"july-correct-0015\",\"title\":\"AMD to join the optical interconnect party with 2027 Instinct GPUs\",\"sourceType\":\"labeled_article\",\"time\":\"2026-07\",\"matchedTerms\":[\"OpenAI\",\"Meta\",\"Microsoft\",\"URL\",\"GPT-5.6\"],\"rank\":-13.22542634630433},{\"id\":\"july-correct-0001\",\"title\":\"全球首颗2nm GPU来了！苏姿丰甩出“最强AI机架”，CPU性能干翻英伟达 - 智东西\",\"sourceType\":\"labeled_article\",\"time\":\"2026-07\",\"matchedTerms\":[\"OpenAI\",\"RAS\",\"NPU\",\"Meta\",\"GPT-5.6\"],\"rank\":-13.008845017892035}]"
采集批次: "2026年9月2日10点15分47秒"
采集批次ID: "20260902-101546-814"
去重键: "https://developers.openai.com/plugins/reference"
---

Title: Reference – Plugins | OpenAI Developers

URL Source: https://developers.openai.com/plugins/reference

Published Time: Wed, 02 Sep 2026 01:58:19 GMT

Markdown Content:
For the complete documentation index, see [llms.txt](https://developers.openai.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to the page URL. 

[![Image 1: OpenAI Developers](https://developers.openai.com/OpenAI_Developers.svg)ChatGPT](https://developers.openai.com/)

[Home](https://developers.openai.com/)

[API](https://developers.openai.com/api/docs)

[Codex](https://learn.chatgpt.com/docs)

[Docs Guides, concepts, and product docs for Codex](https://learn.chatgpt.com/docs)[Use cases Example workflows and tasks teams can take on with ChatGPT or Codex](https://learn.chatgpt.com/use-cases)

[Docs](https://developers.openai.com/codex)

[Use cases](https://developers.openai.com/codex/use-cases)

[Training](https://developers.openai.com/training)

[Resources](https://developers.openai.com/codex/resources)

[ChatGPT](https://developers.openai.com/chatgpt)

[Plugins Extend ChatGPT and Codex](https://developers.openai.com/plugins)[Workspace Agents Trigger published ChatGPT workspace agents](https://developers.openai.com/workspace-agents)[Commerce Build commerce flows in ChatGPT](https://developers.openai.com/commerce)[Ads Publish and measure ads in ChatGPT](https://developers.openai.com/ads)

[Resources](https://developers.openai.com/learn)

[Showcase Demo apps to get inspired](https://developers.openai.com/showcase)[Blog Learnings and experiences from developers](https://developers.openai.com/blog)[Cookbook Notebook examples for building with OpenAI models](https://developers.openai.com/cookbook)[Learn Docs, videos, and demo apps for building with OpenAI](https://developers.openai.com/learn)[Community Programs, meetups, and support for builders](https://developers.openai.com/community)

Start searching

[API Dashboard](https://platform.openai.com/login)

[Try ChatGPT](https://chatgpt.com/)

## Search the ChatGPT docs

Search docs 

### Suggested

responses create reasoning_effort realtime prompt caching

 Primary navigation 

 API  Codex  ChatGPT  Docs  Use cases  Training  Resources  Resources 

Search docs 

### Suggested

responses create reasoning_effort realtime prompt caching

 Overview  Models  Agents  Tools  Voice & Audio  Production  API reference 

Docs Overview

*   [Home](https://developers.openai.com/api/docs)

### Get started

*   [Quickstart](https://developers.openai.com/api/docs/quickstart)
*   [Using GPT-5.6](https://developers.openai.com/api/docs/guides/latest-model)
*   [Key concepts](https://developers.openai.com/api/docs/concepts)

### Core concepts

*   [Responses API](https://developers.openai.com/api/docs/guides/migrate-to-responses)
*   [Conversation state](https://developers.openai.com/api/docs/guides/conversation-state)
*   [Background mode](https://developers.openai.com/api/docs/guides/background)
*   [Streaming](https://developers.openai.com/api/docs/guides/streaming-responses)
*   [WebSocket mode](https://developers.openai.com/api/docs/guides/websocket-mode)
*   [Multi-agent](https://developers.openai.com/api/docs/guides/responses-multi-agent)
*   [Webhooks](https://developers.openai.com/api/docs/guides/webhooks)
*   [File inputs](https://developers.openai.com/api/docs/guides/file-inputs)
*   [Compaction](https://developers.openai.com/api/docs/guides/compaction)
*   [Counting tokens](https://developers.openai.com/api/docs/guides/token-counting)

### SDKs and CLI

*   [OpenAI SDK](https://developers.openai.com/api/docs/libraries)
*   [OpenAI CLI](https://developers.openai.com/api/docs/libraries/openai-cli)

### Resources

*   [Changelog](https://developers.openai.com/api/docs/changelog)
*   [Deprecations](https://developers.openai.com/api/docs/deprecations)
*   [Supported countries](https://developers.openai.com/api/docs/supported-countries)
*   [OpenAI Crawlers](https://developers.openai.com/api/docs/bots)
*   [Terms and policies](https://openai.com/policies)

### Legacy APIs

*   
Agent Builder
    *   [Overview](https://developers.openai.com/api/docs/guides/agent-builder)
    *   [Migration guide](https://developers.openai.com/api/docs/guides/agent-builder/migrate-from-agent-builder)
    *   [Node reference](https://developers.openai.com/api/docs/guides/node-reference)
    *   [Safety in building agents](https://developers.openai.com/api/docs/guides/agent-builder-safety)

*   
Evals
    *   [Getting started](https://developers.openai.com/api/docs/guides/evaluation-getting-started)
    *   [Working with evals](https://developers.openai.com/api/docs/guides/evals)
    *   [Prompt optimizer](https://developers.openai.com/api/docs/guides/prompt-optimizer)
    *   [External models](https://developers.openai.com/api/docs/guides/external-models)
    *   [Best practices](https://developers.openai.com/api/docs/guides/evaluation-best-practices)
    *   [Graders](https://developers.openai.com/api/docs/guides/graders)

*   
Fine-tuning
    *   [Optimization cycle](https://developers.openai.com/api/docs/guides/model-optimization)
    *   [Supervised fine-tuning](https://developers.openai.com/api/docs/guides/supervised-fine-tuning)
    *   [Vision fine-tuning](https://developers.openai.com/api/docs/guides/vision-fine-tuning)
    *   [Direct preference optimization](https://developers.openai.com/api/docs/guides/direct-preference-optimization)
    *   [Reinforcement fine-tuning](https://developers.openai.com/api/docs/guides/reinforcement-fine-tuning)
    *   [RFT use cases](https://developers.openai.com/api/docs/guides/rft-use-cases)
    *   [Best practices](https://developers.openai.com/api/docs/guides/fine-tuning-best-practices)

*   
Assistants API
    *   [Migration guide](https://developers.openai.com/api/docs/assistants/migration)

*   [Model catalog](https://developers.openai.com/api/docs/models)

### Choose a model

*   [Pricing](https://developers.openai.com/api/docs/pricing)
*   [Model selection](https://developers.openai.com/api/docs/guides/model-selection)

### Text and code

*   [Text generation](https://developers.openai.com/api/docs/guides/text)
*   [Code generation](https://developers.openai.com/api/docs/guides/code-generation)
*   [Structured output](https://developers.openai.com/api/docs/guides/structured-outputs)

### Prompting

*   [Overview](https://developers.openai.com/api/docs/guides/prompting)
*   [Prompt engineering](https://developers.openai.com/api/docs/guides/prompt-engineering)
*   [Citation formatting](https://developers.openai.com/api/docs/guides/citation-formatting)
*   [Migration guide](https://developers.openai.com/api/docs/guides/prompting/migrate-from-prompt-object)
*   [Prompt generation](https://developers.openai.com/api/docs/guides/prompt-generation)
*   [Frontend prompting](https://developers.openai.com/api/docs/guides/frontend-prompt)

### Reasoning

*   [Reasoning models](https://developers.openai.com/api/docs/guides/reasoning)
*   [Reasoning best practices](https://developers.openai.com/api/docs/guides/reasoning-best-practices)

### Images and video

*   
[Images and vision](https://developers.openai.com/api/docs/guides/images-vision)
    *   [Image input cost calculator](https://developers.openai.com/api/docs/guides/image-cost-calculator)

*   [Image generation](https://developers.openai.com/api/docs/guides/image-generation)
*   [Video generation](https://developers.openai.com/api/docs/guides/video-generation)

### Realtime and audio

*   [Audio and speech](https://developers.openai.com/api/docs/guides/audio)
*   [Overview](https://developers.openai.com/api/docs/guides/realtime)
*   [Voice agents](https://developers.openai.com/api/docs/guides/voice-agents)

### Specialized models

*   [Deep research](https://developers.openai.com/api/docs/guides/deep-research)
*   [Embeddings](https://developers.openai.com/api/docs/guides/embeddings)
*   [Moderation](https://developers.openai.com/api/docs/guides/moderation)

*   [Overview](https://developers.openai.com/api/docs/guides/agents)

### Agents SDK

*   [Quickstart](https://developers.openai.com/api/docs/guides/agents/quickstart)
*   [Agent definitions](https://developers.openai.com/api/docs/guides/agents/define-agents)
*   [Models and providers](https://developers.openai.com/api/docs/guides/agents/models)
*   [Running agents](https://developers.openai.com/api/docs/guides/agents/running-agents)
*   [Sandbox agents](https://developers.openai.com/api/docs/guides/agents/sandboxes)
*   [Orchestration](https://developers.openai.com/api/docs/guides/agents/orchestration)
*   [Guardrails](https://developers.openai.com/api/docs/guides/agents/guardrails-approvals)
*   [Results and state](https://developers.openai.com/api/docs/guides/agents/results)
*   [Integrations and observability](https://developers.openai.com/api/docs/guides/agents/integrations-observability)
*   [Evaluate agent workflows](https://developers.openai.com/api/docs/guides/agent-evals)

### ChatKit

*   [Overview](https://developers.openai.com/api/docs/guides/chatkit)
*   [Customize](https://developers.openai.com/api/docs/guides/chatkit-themes)
*   [Widgets](https://developers.openai.com/api/docs/guides/chatkit-widgets)
*   [Actions](https://developers.openai.com/api/docs/guides/chatkit-actions)
*   [Advanced integrations](https://developers.openai.com/api/docs/guides/custom-chatkit)

*   [Overview](https://developers.openai.com/api/docs/guides/tools)
*   [Function calling](https://developers.openai.com/api/docs/guides/function-calling)

### Search and retrieval

*   [Web search](https://developers.openai.com/api/docs/guides/tools-web-search)
*   [File search](https://developers.openai.com/api/docs/guides/tools-file-search)
*   [Retrieval](https://developers.openai.com/api/docs/guides/retrieval)

### Connect tools and data

*   [MCP and Connectors](https://developers.openai.com/api/docs/guides/tools-connectors-mcp)
*   [Secure MCP Tunnel](https://developers.openai.com/api/docs/guides/secure-mcp-tunnels)

### Build tool workflows

*   [Skills](https://developers.openai.com/api/docs/guides/tools-skills)
*   [Tool search](https://developers.openai.com/api/docs/guides/tools-tool-search)
*   [Programmatic tool calling](https://developers.openai.com/api/docs/guides/tools-programmatic-tool-calling)

### Computer and code

*   [Shell](https://developers.openai.com/api/docs/guides/tools-shell)
*   [Computer use](https://developers.openai.com/api/docs/guides/tools-computer-use)
*   [Apply Patch](https://developers.openai.com/api/docs/guides/tools-apply-patch)
*   [Local shell](https://developers.openai.com/api/docs/guides/tools-local-shell)
*   [Code interpreter](https://developers.openai.com/api/docs/guides/tools-code-interpreter)

### Media

*   [Image generation](https://developers.openai.com/api/docs/guides/tools-image-generation)

*   [Overview](https://developers.openai.com/api/docs/guides/realtime)

### Get started

*   [Voice agents](https://developers.openai.com/api/docs/guides/voice-agents)
*   [Live translation](https://developers.openai.com/api/docs/guides/realtime-translation)
*   [Realtime prompting guide](https://developers.openai.com/api/docs/guides/realtime-models-prompting)

### Audio

*   [Audio and speech](https://developers.openai.com/api/docs/guides/audio)
*   [Transcription](https://developers.openai.com/api/docs/guides/transcription)
*   [File transcription](https://developers.openai.com/api/docs/guides/speech-to-text)
*   [Realtime transcription](https://developers.openai.com/api/docs/guides/realtime-transcription)
*   [Speech generation](https://developers.openai.com/api/docs/guides/text-to-speech)

### Connection methods

*   [WebRTC](https://developers.openai.com/api/docs/guides/realtime-webrtc)
*   [WebSocket](https://developers.openai.com/api/docs/guides/realtime-websocket)
*   [SIP](https://developers.openai.com/api/docs/guides/realtime-sip)

### Sessions and operations

*   [Managing conversations](https://developers.openai.com/api/docs/guides/realtime-conversations)
*   [Voice activity detection](https://developers.openai.com/api/docs/guides/realtime-vad)
*   [Realtime with tools](https://developers.openai.com/api/docs/guides/realtime-mcp)
*   [Webhooks and server-side controls](https://developers.openai.com/api/docs/guides/realtime-server-controls)
*   [Managing costs](https://developers.openai.com/api/docs/guides/realtime-costs)

### Go live

*   [Production best practices](https://developers.openai.com/api/docs/guides/production-best-practices)
*   [Deployment checklist](https://developers.openai.com/api/docs/guides/deployment-checklist)

### Performance and quality

*   [Latency optimization](https://developers.openai.com/api/docs/guides/latency-optimization)
*   [Predicted Outputs](https://developers.openai.com/api/docs/guides/predicted-outputs)
*   [Fast mode](https://developers.openai.com/api/docs/guides/fast-mode)
*   [Accuracy optimization](https://developers.openai.com/api/docs/guides/optimizing-llm-accuracy)

### Cost and throughput

*   [Cost optimization](https://developers.openai.com/api/docs/guides/cost-optimization)
*   [Prompt caching](https://developers.openai.com/api/docs/guides/prompt-caching)
*   [Batch](https://developers.openai.com/api/docs/guides/batch)
*   [Flex processing](https://developers.openai.com/api/docs/guides/flex-processing)

### Safety and governance

*   [Safety best practices](https://developers.openai.com/api/docs/guides/safety-best-practices)
*   [Red teaming](https://developers.openai.com/api/docs/guides/red-teaming)
*   
[Safety checks](https://developers.openai.com/api/docs/guides/safety-checks)
    *   [Cybersecurity checks](https://developers.openai.com/api/docs/guides/safety-checks/cybersecurity)
    *   [Under 18 API Guidance](https://developers.openai.com/api/docs/guides/safety-checks/under-18-api-guidance)

*   [CSAM guidance](https://developers.openai.com/api/docs/guides/csam-guidance)
*   [Content provenance](https://developers.openai.com/api/docs/guides/content-provenance)
*   [Your data](https://developers.openai.com/api/docs/guides/your-data)
*   [Permissions](https://developers.openai.com/api/docs/guides/rbac)

### Infrastructure and access

*   
[Terraform provider](https://developers.openai.com/api/docs/guides/terraform)
    *   [Overview](https://developers.openai.com/api/docs/guides/terraform)
    *   [Projects and access](https://developers.openai.com/api/docs/guides/terraform/projects-and-access)
    *   [Service accounts](https://developers.openai.com/api/docs/guides/terraform/service-accounts)
    *   [Rate limits and spend](https://developers.openai.com/api/docs/guides/terraform/rate-limits-and-spend)
    *   [Model, tool, and data controls](https://developers.openai.com/api/docs/guides/terraform/project-controls)
    *   [Import and reconciliation](https://developers.openai.com/api/docs/guides/terraform/import-and-reconcile)

*   [Private Link](https://developers.openai.com/api/docs/guides/private-link)
*   [IP allowlist](https://developers.openai.com/api/docs/guides/ip-allowlist)
*   [Mutual TLS](https://developers.openai.com/api/docs/guides/mutual-tls)
*   
[Workload identity federation](https://developers.openai.com/api/docs/guides/workload-identity-federation)
    *   [Codex setup](https://developers.openai.com/codex/enterprise/workload-identity)
    *   [Federation rules](https://developers.openai.com/api/docs/guides/workload-identity-federation/federation-rules)
    *   [Admin API](https://developers.openai.com/api/docs/guides/workload-identity-federation/admin-api)
    *   [X.509 certificates](https://developers.openai.com/api/docs/guides/workload-identity-federation/x509)
    *   [Kubernetes](https://developers.openai.com/api/docs/guides/workload-identity-federation/kubernetes)
    *   [AWS](https://developers.openai.com/api/docs/guides/workload-identity-federation/aws)
    *   [Microsoft Azure](https://developers.openai.com/api/docs/guides/workload-identity-federation/microsoft-azure)
    *   [Google Cloud](https://developers.openai.com/api/docs/guides/workload-identity-federation/google-cloud)
    *   [Oracle Cloud Infrastructure](https://developers.openai.com/api/docs/guides/workload-identity-federation/oracle-cloud)
    *   [GitHub Actions](https://developers.openai.com/api/docs/guides/workload-identity-federation/github-actions)
    *   [SPIFFE](https://developers.openai.com/api/docs/guides/workload-identity-federation/spiffe)

*   [IP egress ranges](https://developers.openai.com/api/docs/guides/ip-addresses)
*   [Amazon Bedrock](https://developers.openai.com/api/docs/guides/amazon-bedrock)

### Operations

*   [Rate limits](https://developers.openai.com/api/docs/guides/rate-limits)
*   [Spend limits](https://developers.openai.com/api/docs/guides/spend-limits)
*   [Admin APIs](https://developers.openai.com/api/docs/guides/admin-apis)
*   [Error codes](https://developers.openai.com/api/docs/guides/error-codes)

[Docs](https://learn.chatgpt.com/docs)[Use cases](https://learn.chatgpt.com/use-cases)

Docs Docs

 Plugins  Workspace Agents  Commerce  Ads 

Docs Plugins

*   [Home](https://developers.openai.com/plugins)
*   [Quickstart](https://developers.openai.com/plugins/quickstart)

### Core concepts

*   [Plugin architecture](https://developers.openai.com/plugins/concepts/plugins)
*   [Skills](https://developers.openai.com/plugins/concepts/skills)
*   [MCP server](https://developers.openai.com/plugins/concepts/mcp-server)

### Plan

*   [Brainstorm use cases](https://developers.openai.com/plugins/plan/use-case)
*   [Define tools](https://developers.openai.com/plugins/plan/tools)

### Build

*   [Build an MCP server](https://developers.openai.com/plugins/build/mcp-server)
*   [Add UI to your MCP server (optional)](https://developers.openai.com/plugins/build/chatgpt-ui)
*   [Authenticate users](https://developers.openai.com/plugins/build/auth)
*   [Build skills](https://developers.openai.com/plugins/build/skills)
*   [Package your plugin](https://developers.openai.com/plugins/build/plugins)
*   [Examples](https://developers.openai.com/plugins/build/examples)

### Test and publish

*   [Connect and test your plugin](https://developers.openai.com/plugins/deploy/connect-chatgpt)
*   [Submit and publish](https://developers.openai.com/plugins/deploy/submission)
*   [Submission error reference](https://developers.openai.com/plugins/deploy/submission-errors)

### Conversion specs

*   [Restaurant reservation spec](https://developers.openai.com/plugins/guides/restaurant-reservation-conversion-spec)
*   [Get Quote spec](https://developers.openai.com/plugins/guides/local-services-request-quote-conversion-spec)
*   [Product checkout spec](https://developers.openai.com/plugins/guides/product-checkout-conversion-spec)

### Guides

*   [UI guidelines](https://developers.openai.com/plugins/concepts/ui-guidelines)
*   [Optimize Metadata](https://developers.openai.com/plugins/guides/optimize-metadata)
*   [Submit a Claude Code plugin](https://developers.openai.com/plugins/guides/submit-claude-plugin)
*   [Security & Privacy](https://developers.openai.com/plugins/guides/security-privacy)
*   [Troubleshooting](https://developers.openai.com/plugins/deploy/troubleshooting)

### Resources

*   [Changelog](https://developers.openai.com/plugins/changelog)
*   [Plugin guidelines](https://developers.openai.com/plugins/app-guidelines)
*   [MCP server review requirements](https://developers.openai.com/plugins/deploy/app-review)
*   [Plugin UI reference](https://developers.openai.com/plugins/reference)
*   [Checkout API reference](https://developers.openai.com/plugins/build/monetization)

*   [Home](https://developers.openai.com/workspace-agents)

### Get started

*   [Trigger workspace agent runs](https://developers.openai.com/workspace-agents/trigger-runs)
*   [Authenticate with Workspace Agent access tokens](https://developers.openai.com/workspace-agents/authentication)

*   [Home](https://developers.openai.com/commerce)

### Guides

*   [Get started](https://developers.openai.com/commerce/guides/get-started)
*   [Best practices](https://developers.openai.com/commerce/guides/best-practices)

### File Upload

*   [Overview](https://developers.openai.com/commerce/specs/file-upload/overview)
*   [Products](https://developers.openai.com/commerce/specs/file-upload/products)

### API

*   [Overview](https://developers.openai.com/commerce/specs/api/overview)
*   [Feeds](https://developers.openai.com/commerce/specs/api/feeds)
*   [Products](https://developers.openai.com/commerce/specs/api/products)
*   [Promotions](https://developers.openai.com/commerce/specs/api/promotions)

*   [Ads Overview](https://developers.openai.com/ads)

### Measurement

*   [Measurement Pixel](https://developers.openai.com/ads/measurement-pixel)
*   [Multiple Pixels (Advanced)](https://developers.openai.com/ads/multiple-pixels)
*   [Image Tag](https://developers.openai.com/ads/image-tag)
*   [Conversions API](https://developers.openai.com/ads/conversions-api)
*   [Supported Events](https://developers.openai.com/ads/supported-events)

### Advertiser API

*   [Overview](https://developers.openai.com/ads/api-overview)
*   [API Partner Setup](https://developers.openai.com/ads/api-partner-setup)
*   [Quickstart](https://developers.openai.com/ads/api-quickstart)
*   [Bulk API](https://developers.openai.com/ads/bulk-api)
*   [Product Feeds](https://developers.openai.com/ads/product-feeds)
*   [Delta Feeds API](https://developers.openai.com/ads/delta-feeds)
*   [Campaign Targeting](https://developers.openai.com/ads/campaign-targeting)
*   [Conversion-Optimized Campaigns](https://developers.openai.com/ads/conversion-optimized-campaigns)
*   [Custom Audiences](https://developers.openai.com/ads/custom-audiences)

### API Reference

*   [Authentication](https://developers.openai.com/ads/api-reference/authentication)
*   [Ad Account](https://developers.openai.com/ads/api-reference/ad-account)
*   [Campaigns](https://developers.openai.com/ads/api-reference/campaigns)
*   [Ad Groups](https://developers.openai.com/ads/api-reference/ad-groups)
*   [Ads](https://developers.openai.com/ads/api-reference/ads)
*   [Insights](https://developers.openai.com/ads/api-reference/insights)
*   [Files](https://developers.openai.com/ads/api-reference/files)
*   [Conversion Setup](https://developers.openai.com/ads/api-reference/conversion-setup)

 Overview  Features  Configuration  Developers  Security  Administration  Use Cases  Resources 

Docs Overview

*   [Home](https://developers.openai.com/codex)

### Get started

*   [Quickstart](https://developers.openai.com/codex/quickstart)
*   [Use ChatGPT](https://developers.openai.com/codex/use-chatgpt)
*   [Get started with Work](https://developers.openai.com/codex/get-started-with-work)
*   [Import from another agent](https://developers.openai.com/codex/import)

### Foundations

*   [Prompting](https://developers.openai.com/codex/prompting)
*   [Personalize ChatGPT](https://developers.openai.com/codex/personalize)
*   [Skills & Plugins](https://developers.openai.com/codex/skills-and-plugins)
*   [Permissions](https://developers.openai.com/codex/permission-modes)

### Explore

*   [What's new](https://developers.openai.com/codex/whats-new)
*   [Models](https://developers.openai.com/codex/models)
*   [Pricing](https://developers.openai.com/codex/pricing)
*   [Glossary](https://developers.openai.com/codex/glossary)

### Available on

*   [ChatGPT desktop app](https://developers.openai.com/codex/app)
*   [Remote](https://developers.openai.com/codex/remote)
*   [ChatGPT on the web](https://developers.openai.com/codex/web)
*   [Codex CLI](https://developers.openai.com/codex/cli)
*   [Codex IDE extension](https://developers.openai.com/codex/ide)
*   [Codex cloud](https://developers.openai.com/codex/cloud)

### Releases

*   [Changelog](https://developers.openai.com/codex/changelog)
*   [Feature Maturity](https://developers.openai.com/codex/feature-maturity)
*   [Open Source](https://developers.openai.com/codex/open-source)

*   [Overview](https://developers.openai.com/codex/features)

### Workflows

*   [Projects and chats](https://developers.openai.com/codex/projects)
*   [Sites](https://developers.openai.com/codex/sites)
*   [Visualizations](https://developers.openai.com/codex/visualizations)
*   [Scheduled tasks](https://developers.openai.com/codex/automations)
*   [Long-running work](https://developers.openai.com/codex/long-running-work)
*   [Notifications](https://developers.openai.com/codex/notifications)
*   [Pets](https://developers.openai.com/codex/pets)
*   [Codex Micro](https://developers.openai.com/codex/features/codex-micro)

### Capabilities

*   [Browser](https://developers.openai.com/codex/browser)
*   [Computer use](https://developers.openai.com/codex/computer-use)
*   [Voice](https://developers.openai.com/codex/features/voice)
*   [Plugins](https://developers.openai.com/codex/plugins)
*   [Web search](https://developers.openai.com/codex/web-search)
*   [Image generation](https://developers.openai.com/codex/image-generation)
*   [Image inputs](https://developers.openai.com/codex/image-inputs)
*   [Appshots](https://developers.openai.com/codex/appshots)
*   [Browser extension](https://developers.openai.com/codex/chrome-extension)
*   [Work with files](https://developers.openai.com/codex/artifacts-viewer)

### Reference

*   [Commands](https://developers.openai.com/codex/reference/commands)
*   [Slash commands](https://developers.openai.com/codex/reference/slash-commands)
*   [Settings](https://developers.openai.com/codex/reference/settings)
*   [Troubleshooting](https://developers.openai.com/codex/reference/troubleshooting)

*   [Overview](https://developers.openai.com/codex/configuration)

### Customization

*   [Overview](https://developers.openai.com/codex/customization/overview)
*   [Memories](https://developers.openai.com/codex/customization/memories)
*   [Computer History](https://developers.openai.com/codex/customization/computer-history)

### Config file

*   [Config Basics](https://developers.openai.com/codex/config-file/config-basic)
*   [Advanced Config](https://developers.openai.com/codex/config-file/config-advanced)
*   [Config Reference](https://developers.openai.com/codex/config-file/config-reference)
*   [Environment Variables](https://developers.openai.com/codex/config-file/environment-variables)
*   [Sample Config](https://developers.openai.com/codex/config-file/config-sample)

### Agent configuration

*   [AGENTS.md](https://developers.openai.com/codex/agent-configuration/agents-md)
*   [Subagents](https://developers.openai.com/codex/agent-configuration/subagents)
*   [Speed](https://developers.openai.com/codex/agent-configuration/speed)
*   [Rules](https://developers.openai.com/codex/agent-configuration/rules)

### Extend ChatGPT and Codex

*   [Record & Replay](https://developers.openai.com/codex/extend/record-and-replay)
*   [MCP](https://developers.openai.com/codex/extend/mcp)

### Linux

*   [Desktop app](https://developers.openai.com/codex/linux/linux-app)

### Windows

*   [Desktop app](https://developers.openai.com/codex/windows/windows-app)
*   [Windows sandbox](https://developers.openai.com/codex/windows/windows-sandbox)
*   [WSL](https://developers.openai.com/codex/windows/wsl)

*   [Overview](https://developers.openai.com/codex/developers)

### Development workflows

*   [Code review](https://developers.openai.com/codex/code-review)
*   [Integrated terminal](https://developers.openai.com/codex/integrated-terminal)

### Extend and automate

*   [Build skills](https://developers.openai.com/codex/build-skills)
*   [Build plugins](https://developers.openai.com/codex/build-plugins)
*   [Site tools (WebMCP)](https://developers.openai.com/codex/webmcp)
*   [Hooks](https://developers.openai.com/codex/hooks)

### Environments

*   [Modes](https://developers.openai.com/codex/environments/modes)
*   [Local environments](https://developers.openai.com/codex/environments/local-environment)
*   [Cloud environment](https://developers.openai.com/codex/environments/cloud-environment)
*   [Git worktrees](https://developers.openai.com/codex/environments/git-worktrees)

### Build with Codex

*   [Codex SDK](https://developers.openai.com/codex/codex-sdk)
*   [App Server](https://developers.openai.com/codex/app-server)
*   [MCP Server](https://developers.openai.com/codex/mcp-server)
*   [GitHub Action](https://developers.openai.com/codex/github-action)
*   [Non-interactive mode](https://developers.openai.com/codex/non-interactive-mode)

### Third-party integrations

*   [GitHub](https://developers.openai.com/codex/third-party/github)
*   [GitLab (Beta)](https://developers.openai.com/codex/third-party/gitlab)
*   [Slack](https://developers.openai.com/codex/third-party/slack)
*   [Linear](https://developers.openai.com/codex/third-party/linear)

### Reference

*   [CLI customization](https://developers.openai.com/codex/cli-customization)
*   [Developer commands](https://developers.openai.com/codex/developer-commands)
*   [Developer settings](https://developers.openai.com/codex/developer-settings)

*   [Overview](https://developers.openai.com/codex/security-administration)

### Permissions

*   [Profiles](https://developers.openai.com/codex/permissions)
*   [Sandboxing](https://developers.openai.com/codex/sandboxing)
*   [Auto-review](https://developers.openai.com/codex/sandboxing/auto-review)
*   [Agent approvals & security](https://developers.openai.com/codex/agent-approvals-security)
*   [Internet access](https://developers.openai.com/codex/cloud/internet-access)

### Codex Security

*   [Overview](https://developers.openai.com/codex/security)
*   
Codex Security plugin
    *   [Quickstart](https://developers.openai.com/codex/security/plugin)
    *   [Run a security scan](https://developers.openai.com/codex/security/plugin/scans)
    *   [Run a deep scan](https://developers.openai.com/codex/security/plugin/deep-scans)
    *   [Review code changes](https://developers.openai.com/codex/security/plugin/code-changes)
    *   [Use the Security workbench](https://developers.openai.com/codex/security/plugin/workbench)
    *   [Triage a backlog](https://developers.openai.com/codex/security/plugin/triage-backlog)
    *   [Fix findings](https://developers.openai.com/codex/security/plugin/fix-findings)
    *   [Propose security hardening](https://developers.openai.com/codex/security/plugin/security-hardening)
    *   [Write vulnerability reports](https://developers.openai.com/codex/security/plugin/vulnerability-reports)
    *   [Export and track findings](https://developers.openai.com/codex/security/plugin/export-findings)
    *   [Changelog](https://developers.openai.com/codex/security/plugin/changelog)

*   
Codex Security CLI
    *   [Quickstart](https://developers.openai.com/codex/security/cli)
    *   [Run bulk scans](https://developers.openai.com/codex/security/cli/bulk-scans)
    *   [Run scans in CI](https://developers.openai.com/codex/security/cli/ci)
    *   [GitLab CI/CD](https://developers.openai.com/codex/security/cli/ci/gitlab)
    *   [Reference](https://developers.openai.com/codex/security/cli/reference)
    *   [FAQ](https://developers.openai.com/codex/security/cli/faq)

*   [TypeScript SDK](https://developers.openai.com/codex/security/sdk)
*   
Codex Security cloud
    *   [Setup](https://developers.openai.com/codex/security/setup)
    *   [Security Review](https://developers.openai.com/codex/security/security-review)
    *   [Improving the threat model](https://developers.openai.com/codex/security/threat-model)
    *   [FAQ](https://developers.openai.com/codex/security/faq)

### Cyber safety

*   [Models & Trusted Access](https://developers.openai.com/codex/cyber-safety)
*   [Recommended configuration](https://developers.openai.com/codex/cyber-safety/recommended-configuration)

*   [Overview](https://developers.openai.com/codex/administration)

### Getting started

*   [Admin rollout guide](https://developers.openai.com/codex/enterprise/admin-setup)

### ChatGPT Work

*   [ChatGPT Work Overview](https://developers.openai.com/codex/enterprise/chatgpt-work-overview)
*   [ChatGPT Work cloud security](https://developers.openai.com/codex/enterprise/chatgpt-work-cloud-security)
*   [ChatGPT Work local security](https://developers.openai.com/codex/enterprise/chatgpt-work-local-security)
*   [ChatGPT Work admin FAQ](https://developers.openai.com/codex/enterprise/work-admin-faq)
*   [ChatGPT Work: usage and cost](https://developers.openai.com/codex/enterprise/chatgpt-work-usage-and-cost)

### Identity and authentication

*   [Authentication overview](https://developers.openai.com/codex/auth)
*   [Workload identity](https://developers.openai.com/codex/enterprise/workload-identity)
*   [Personal Access Tokens](https://developers.openai.com/codex/enterprise/access-tokens)
*   [Service accounts](https://developers.openai.com/codex/enterprise/service-accounts)

### Workspace access, policy, and models

*   [Groups and provisioning](https://developers.openai.com/codex/enterprise/groups-and-provisioning)
*   [User lifecycle management](https://developers.openai.com/codex/enterprise/user-lifecycle)
*   [Roles and workspace permissions](https://developers.openai.com/codex/enterprise/roles-and-workspace-permissions)
*   [GPTs and Sharing](https://developers.openai.com/codex/enterprise/gpts-and-sharing)
*   [Managed configuration](https://developers.openai.com/codex/enterprise/managed-configuration)
*   [Prisma AIRS](https://developers.openai.com/codex/enterprise/prisma-airs)
*   [HIPAA configuration](https://developers.openai.com/codex/hipaa-configuration)
*   [Workspace model availability](https://developers.openai.com/codex/enterprise/workspace-model-availability)

### Plugin and connector controls

*   [Plugin controls](https://developers.openai.com/codex/enterprise/apps-and-connectors)
*   [Plugin management](https://developers.openai.com/codex/enterprise/plugin-management)
*   [Skill controls](https://developers.openai.com/codex/enterprise/skills)

### Usage, governance, and compliance

*   [Governance](https://developers.openai.com/codex/enterprise/governance)
*   [Admin plugin](https://developers.openai.com/codex/enterprise/admin-plugin)
*   [Workspace analytics](https://developers.openai.com/codex/enterprise/workspace-analytics)
*   [Analytics API](https://developers.openai.com/codex/enterprise/analytics-api)
*   [Compliance API and audit events](https://developers.openai.com/codex/enterprise/compliance-api)

### Deployment and model providers

*   [Manage app updates](https://developers.openai.com/codex/enterprise/manage-app-updates)
*   [Windows app deployment](https://developers.openai.com/codex/enterprise/windows-deployment)
*   [Remote connections](https://developers.openai.com/codex/remote-connections)
*   [Amazon Bedrock](https://developers.openai.com/codex/amazon-bedrock)

*   [Explore use cases](https://developers.openai.com/codex/use-cases)
*   [Collections](https://developers.openai.com/codex/use-cases/collections)

*   [Home](https://developers.openai.com/codex/resources)
*   [Videos](https://developers.openai.com/codex/videos)
*   [Showcase](https://developers.openai.com/showcase)
*   [OpenAI Academy](https://openai.com/academy/)
*   [Online trainings](https://academy.openai.com/home/events)

### Community

*   [Codex Ambassadors](https://developers.openai.com/community/codex-ambassadors)
*   [Codex for Students](https://developers.openai.com/community/students)
*   [Codex for Open Source](https://developers.openai.com/community/codex-for-oss)
*   [Meetups](https://developers.openai.com/community/meetups)

### Blog

*   [Company blog](https://openai.com/news/)
*   [Developer blog](https://developers.openai.com/blog)

*   [Explore use cases](https://developers.openai.com/codex/use-cases)
*   [Collections](https://developers.openai.com/codex/use-cases/collections)

*   [Home](https://developers.openai.com/codex/resources)
*   [Videos](https://developers.openai.com/codex/videos)
*   [Showcase](https://developers.openai.com/showcase)
*   [OpenAI Academy](https://openai.com/academy/)
*   [Online trainings](https://academy.openai.com/home/events)

### Community

*   [Codex Ambassadors](https://developers.openai.com/community/codex-ambassadors)
*   [Codex for Students](https://developers.openai.com/community/students)
*   [Codex for Open Source](https://developers.openai.com/community/codex-for-oss)
*   [Meetups](https://developers.openai.com/community/meetups)

### Blog

*   [Company blog](https://openai.com/news/)
*   [Developer blog](https://developers.openai.com/blog)

[Showcase](https://developers.openai.com/showcase) Blog  Cookbook  Learn  Community 

Docs Select...

*   [All posts](https://developers.openai.com/blog)

### Recent

*   [Meet Rosalind Workbench: Empowering every scientist to be their own research team](https://developers.openai.com/blog/rosalind-workbench)
*   [Automating repetitive work at OpenAI with Codex](https://developers.openai.com/blog/automating-repetitive-work-at-openai-with-codex)
*   [Meet the winners of OpenAI Build Week](https://developers.openai.com/blog/build-week-winners)
*   [Scaling cyber defenders with Daybreak](https://developers.openai.com/blog/scaling-cyber-defenders-with-daybreak)
*   [Codex as a platform: build on the open agent harness](https://developers.openai.com/blog/codex-as-a-platform)

### Topics

*   [General](https://developers.openai.com/blog/topic/general)
*   [API](https://developers.openai.com/blog/topic/api)
*   [Apps SDK](https://developers.openai.com/blog/topic/apps-sdk)
*   [Audio](https://developers.openai.com/blog/topic/audio)
*   [Codex](https://developers.openai.com/blog/topic/codex)
*   [Life sciences](https://developers.openai.com/blog/topic/life-sciences)

*   [Home](https://developers.openai.com/cookbook)

### Topics

*   [Agents](https://developers.openai.com/cookbook/topic/agents)
*   [Evals](https://developers.openai.com/cookbook/topic/evals)
*   [Multimodal](https://developers.openai.com/cookbook/topic/multimodal)
*   [Text](https://developers.openai.com/cookbook/topic/text)
*   [Guardrails](https://developers.openai.com/cookbook/topic/guardrails)
*   [Optimization](https://developers.openai.com/cookbook/topic/optimization)
*   [ChatGPT](https://developers.openai.com/cookbook/topic/chatgpt)
*   [Codex](https://developers.openai.com/cookbook/topic/codex)
*   [gpt-oss](https://developers.openai.com/cookbook/topic/gpt-oss)

### Contribute

*   [Cookbook on GitHub](https://github.com/openai/openai-cookbook)

*   [Home](https://developers.openai.com/learn)
*   [OpenAI Developers plugin](https://developers.openai.com/learn/developers-codex-plugin)
*   [Docs MCP](https://developers.openai.com/learn/docs-mcp)

### Categories

*   [Demo apps](https://developers.openai.com/learn/code)
*   [Videos](https://developers.openai.com/learn/videos)

### Topics

*   [Agents](https://developers.openai.com/learn/agents)
*   [Audio & Voice](https://developers.openai.com/learn/audio)
*   [Computer Use](https://developers.openai.com/learn/cua)
*   [Codex](https://developers.openai.com/learn/codex)
*   [Evals](https://developers.openai.com/learn/evals)
*   [gpt-oss](https://developers.openai.com/learn/gpt-oss)
*   [Fine-tuning](https://developers.openai.com/learn/fine-tuning)
*   [Image generation](https://developers.openai.com/learn/imagegen)
*   [Scaling](https://developers.openai.com/learn/scaling)
*   [Tools](https://developers.openai.com/learn/tools)
*   [Video generation](https://developers.openai.com/learn/videogen)

*   [Community](https://developers.openai.com/community)

### Programs

*   [Codex Ambassadors](https://developers.openai.com/community/codex-ambassadors)
*   [Codex for Students](https://developers.openai.com/community/students)
*   [Codex for Open Source](https://developers.openai.com/community/codex-for-oss)
*   [OpenAI for Startups](https://openai.com/business/why-openai/startups/)

### Events

*   [Meetups](https://developers.openai.com/community/meetups)

### Spaces

*   [Developer Forum](https://community.openai.com/)
*   [Discord](https://discord.com/invite/openai)
*   [Reddit](https://www.reddit.com/r/OpenAI/)
*   [X](https://x.com/OpenAIDevs)

[API Dashboard](https://platform.openai.com/login)

[Try ChatGPT](https://chatgpt.com/)

*   [Home](https://developers.openai.com/plugins)
*   [Quickstart](https://developers.openai.com/plugins/quickstart)

### Core concepts

*   [Plugin architecture](https://developers.openai.com/plugins/concepts/plugins)
*   [Skills](https://developers.openai.com/plugins/concepts/skills)
*   [MCP server](https://developers.openai.com/plugins/concepts/mcp-server)

### Plan

*   [Brainstorm use cases](https://developers.openai.com/plugins/plan/use-case)
*   [Define tools](https://developers.openai.com/plugins/plan/tools)

### Build

*   [Build an MCP server](https://developers.openai.com/plugins/build/mcp-server)
*   [Add UI to your MCP server (optional)](https://developers.openai.com/plugins/build/chatgpt-ui)
*   [Authenticate users](https://developers.openai.com/plugins/build/auth)
*   [Build skills](https://developers.openai.com/plugins/build/skills)
*   [Package your plugin](https://developers.openai.com/plugins/build/plugins)
*   [Examples](https://developers.openai.com/plugins/build/examples)

### Test and publish

*   [Connect and test your plugin](https://developers.openai.com/plugins/deploy/connect-chatgpt)
*   [Submit and publish](https://developers.openai.com/plugins/deploy/submission)
*   [Submission error reference](https://developers.openai.com/plugins/deploy/submission-errors)

### Conversion specs

*   [Restaurant reservation spec](https://developers.openai.com/plugins/guides/restaurant-reservation-conversion-spec)
*   [Get Quote spec](https://developers.openai.com/plugins/guides/local-services-request-quote-conversion-spec)
*   [Product checkout spec](https://developers.openai.com/plugins/guides/product-checkout-conversion-spec)

### Guides

*   [UI guidelines](https://developers.openai.com/plugins/concepts/ui-guidelines)
*   [Optimize Metadata](https://developers.openai.com/plugins/guides/optimize-metadata)
*   [Submit a Claude Code plugin](https://developers.openai.com/plugins/guides/submit-claude-plugin)
*   [Security & Privacy](https://developers.openai.com/plugins/guides/security-privacy)
*   [Troubleshooting](https://developers.openai.com/plugins/deploy/troubleshooting)

### Resources

*   [Changelog](https://developers.openai.com/plugins/changelog)
*   [Plugin guidelines](https://developers.openai.com/plugins/app-guidelines)
*   [MCP server review requirements](https://developers.openai.com/plugins/deploy/app-review)
*   [Plugin UI reference](https://developers.openai.com/plugins/reference)
*   [Checkout API reference](https://developers.openai.com/plugins/build/monetization)

Copy Page

# Reference

Reference for ChatGPT-specific UI extensions and metadata.

Copy Page

**Start with the open standard.** Use the

[MCP Apps specification](https://modelcontextprotocol.io/docs/extensions/apps)
for shared UI fields and bridge methods. **OpenAI extensions are optional** and live in `window.openai` when you want ChatGPT-specific capabilities.

## `window.openai` component bridge

ChatGPT provides `window.openai` for compatibility aliases and optional ChatGPT extensions. New UI should use the MCP Apps bridge whenever the shared specification provides an equivalent, then use `window.openai` only for ChatGPT-specific capabilities.

See [build a ChatGPT UI](https://developers.openai.com/plugins/build/chatgpt-ui) for implementation walkthroughs.

If your tool requires confirmation, treat missing initial `toolInput` as expected. ChatGPT does not load approval-gated arguments into widget values before approval; instead, the host delivers them through `ui/notifications/tool-input` once the user approves the call.

### Capabilities

| Capability | What it does | Typical use |
| --- | --- | --- |
| State & data | `window.openai.toolInput` | Arguments supplied when the tool was invoked. For approval-gated tools, this may remain `null` until the host sends `ui/notifications/tool-input` after approval. |
| State & data | `window.openai.toolOutput` | Your `structuredContent`. Keep fields concise; the model reads them verbatim. |
| State & data | `window.openai.toolResponseMetadata` | Canonical widget-only tool result metadata. In ChatGPT this includes `status`, `call_tool_result`, and `mcp_tool_result`, preserving the full MCP result envelope, including hidden `_meta`. |
| State & data | `window.openai.widgetState` | Snapshot of UI state persisted between renders. |
| State & data | `window.openai.setWidgetState(state)` | Stores a new snapshot synchronously; call it after every meaningful UI interaction. |
| Widget runtime APIs | `window.openai.callTool(name, args)` | Invoke another MCP tool from the widget (mirrors model-initiated calls). |
| Widget runtime APIs | `window.openai.sendFollowUpMessage({ prompt, scrollToBottom })` | Ask ChatGPT to post a message authored by the component. `scrollToBottom` is optional, defaults to `true`, and can be set to `false` to prevent automatic scrolling. |
| Widget runtime APIs | `window.openai.uploadFile(file, { library?: boolean })` | Upload a user-selected file and receive a `fileId`. Pass `{ library: true }` to also save the upload in the user’s ChatGPT file library when that library is available. |
| Widget runtime APIs | `window.openai.selectFiles()` | Open ChatGPT’s file library picker and return plugin-authorized files as `{ fileId, fileName, mimeType }[]`. Feature-detect this helper because the file library may not be available to all users. |
| Widget runtime APIs | `window.openai.getFileDownloadUrl({ fileId })` | Retrieve a temporary download URL for a file uploaded by the widget, selected from the file library, passed via file params, or returned by tool file references. |
| Widget runtime APIs | `window.openai.requestDisplayMode(...)` | Request PiP/fullscreen modes. |
| Widget runtime APIs | `window.openai.requestModal({ params, template })` | Spawn a modal owned by ChatGPT. Omit `template` to use the current template, or pass a registered template URI to switch modal content. |
| Widget runtime APIs | `window.openai.requestClose()` | Ask ChatGPT to close the current widget. |
| Widget runtime APIs | `window.openai.notifyIntrinsicHeight(...)` | Report dynamic widget heights to avoid scroll clipping. |
| Widget runtime APIs | `window.openai.openExternal({ href, redirectUrl })` | Open a vetted external link in the user’s browser. For approved redirect targets, ChatGPT appends `?redirectUrl=...` by default; set `redirectUrl: false` to skip it. |
| Widget runtime APIs | `window.openai.setOpenInAppUrl({ href })` | Optionally override the external target shown in fullscreen. If unset, ChatGPT keeps the default behavior and opens the component’s current iframe path. |
| Context | `window.openai.theme`, `window.openai.displayMode`, `window.openai.maxHeight`, `window.openai.safeArea`, `window.openai.view`, `window.openai.userAgent`, `window.openai.locale` | Environment signals you can read or subscribe to through `useOpenAiGlobal` to adapt visuals and copy. |

### `useOpenAiGlobal` helper

Many ChatGPT UI projects wrap `window.openai` access in small helper functions so views remain testable. This example helper listens for host `openai:set_globals` events and lets React components subscribe to a single global value:

```
export function useOpenAiGlobal<K extends keyof WebplusGlobals>(
  key: K
): WebplusGlobals[K] {
  return useSyncExternalStore(
    (onChange) => {
      const handleSetGlobal = (event: SetGlobalsEvent) => {
        const value = event.detail.globals[key];
        if (value === undefined) {
          return;
        }

        onChange();
      };

      window.addEventListener(SET_GLOBALS_EVENT_TYPE, handleSetGlobal, {
        passive: true,
      });

      return () => {
        window.removeEventListener(SET_GLOBALS_EVENT_TYPE, handleSetGlobal);
      };
    },
    () => window.openai[key]
  );
}
```

### Close the UI

Call `window.openai.requestClose()` to ask ChatGPT to close the current UI.

### Request another presentation mode

Use `window.openai.requestDisplayMode` to request inline, picture-in-picture, or fullscreen presentation:

```
await window.openai?.requestDisplayMode({ mode: "fullscreen" });
// On mobile, picture-in-picture may be presented as fullscreen.
```

### Open a modal

Use `window.openai.requestModal` to open a host-controlled modal. Provide the URI of another UI template registered by the same MCP server, or omit `template` to open the current template:

```
await window.openai.requestModal({
  template: "ui://widget/checkout.html",
});
```

## File APIs

ChatGPT supports file upload/download helpers as optional `window.openai` extensions.

| API | Purpose | Notes |
| --- | --- | --- |
| `window.openai.uploadFile(file, { library?: boolean })` | Upload a user-selected file and receive a `fileId`. | Pass `{ library: true }` to also save the upload in the user’s ChatGPT file library when that library is available to the current user. |
| `window.openai.selectFiles()` | Open the file library picker for existing files. | Returns `[{ fileId, fileName, mimeType }]`. Feature-detect this helper because the file library may not be available to all users. |
| `window.openai.getFileDownloadUrl({ fileId })` | Request a temporary download URL for a file. | Works for files uploaded by the widget, selected from the file library, passed via file params, or returned by tool file references. |

The ChatGPT file library is optional and may not be available to every user. Files returned from `window.openai.selectFiles()` are already authorized for the current plugin when the helper is available. Use the returned `fileId` with `window.openai.getFileDownloadUrl({ fileId })` or in a tool input that uses file params.

Upload a user-selected file:

```
const { fileId } = await window.openai.uploadFile(file, {
  library: true,
});
```

Select files that the user already uploaded to ChatGPT:

```
if (window.openai?.selectFiles) {
  const files = await window.openai.selectFiles();
  // [{ fileId, fileName, mimeType }]
}
```

Feature-detect `window.openai.selectFiles` and fall back to `window.openai.uploadFile` when the file library is unavailable.

Request a temporary download URL:

`const { downloadUrl } = await window.openai.getFileDownloadUrl({ fileId });`
### Define file inputs

To let ChatGPT pass files to a tool, list each top-level file input in `_meta["openai/fileParams"]`. Each listed field must resolve to a file object or an array of file objects.

Every file object schema must declare all four supported properties:

| Property | Type | Declare in `properties` | Include in `required` |
| --- | --- | --- | --- |
| `download_url` | `string` | Yes | Yes |
| `file_id` | `string` | Yes | Yes |
| `mime_type` | `string` | Yes | No |
| `file_name` | `string` | Yes | No |

`mime_type` and `file_name` are optional values, but you must declare their properties in the schema. The **Scan Tools** step and plugin submission reject a file schema that omits any of the four properties, does not require `download_url` and `file_id`, marks either optional property as required, or requires a property other than `download_url` or `file_id`. You can declare extra optional properties.

This complete tool descriptor accepts one required file input:

```
{
  "name": "analyze_file",
  "title": "Analyze file",
  "description": "Analyzes a user-provided file without modifying it.",
  "inputSchema": {
    "type": "object",
    "$defs": {
      "OpenAIFile": {
        "type": "object",
        "properties": {
          "download_url": { "type": "string" },
          "file_id": { "type": "string" },
          "mime_type": { "type": "string" },
          "file_name": { "type": "string" }
        },
        "required": ["download_url", "file_id"],
        "additionalProperties": false
      }
    },
    "properties": {
      "file": { "$ref": "#/$defs/OpenAIFile" }
    },
    "required": ["file"]
  },
  "annotations": {
    "readOnlyHint": true,
    "openWorldHint": false,
    "destructiveHint": false
  },
  "_meta": {
    "openai/fileParams": ["file"]
  }
}
```

To accept more than one file, define the top-level field as an array and use the same file object schema in `items`. The tool can require the top-level file field independently of the properties required inside each file object.

At runtime, ChatGPT passes file values with snake case fields:

```
{
  "download_url": "https://...",
  "file_id": "file_...",
  "mime_type": "image/png",
  "file_name": "input.png"
}
```

ChatGPT always includes `download_url` and `file_id`; it may omit `mime_type` and `file_name`. Use `file_id` as the `fileId` value for `window.openai.getFileDownloadUrl({ fileId })` when a widget needs a fresh temporary download URL.

When persisting widget state, use the structured shape (`modelContent`, `privateContent`, `imageIds`) if you want the model to see image IDs during follow-up turns.

## Host-backed navigation

The sandbox runtime mirrors navigation history from the iframe into ChatGPT’s UI. Use standard routing APIs, such as React Router, and the host keeps its navigation controls in sync with your UI.

Router setup with React Router’s `BrowserRouter`:

```
export default function PizzaListRouter() {
  return (
    <BrowserRouter>
      <Routes>
        <Route path="/" element={<PizzaListPlugin />}>
          <Route path="place/:placeId" element={<PizzaListPlugin />} />
        </Route>
      </Routes>
    </BrowserRouter>
  );
}
```

Programmatic navigation:

```
const navigate = useNavigate();

function openDetails(placeId: string) {
  navigate(`place/${placeId}`, { replace: false });
}

function closeDetails() {
  navigate("..", { replace: true });
}
```

## Tool descriptor parameters

By default, a tool description should include the fields listed [here](https://modelcontextprotocol.io/specification/2025-06-18/server/tools#tool).

Declare `outputSchema` for any tool that returns `structuredContent`. The schema should describe the exact object your tool returns so clients can validate results and the model can reason about follow-up tool calls.

### `_meta` fields on tool descriptor

Use these `_meta` fields on the tool descriptor. Prefer the MCP Apps standard key `_meta.ui.resourceUri` for linking a tool to a UI template. ChatGPT supports OpenAI-specific metadata for compatibility and optional extensions.

| Key | Placement | Type | Limits | Purpose |
| --- | --- | --- | --- | --- |
| `_meta["securitySchemes"]` | Tool descriptor | array | None | Back-compat mirror for clients that only read `_meta`. |
| `_meta.ui.resourceUri` | Tool descriptor | string (URI) | None | Standard resource URI for the UI template. |
| `_meta.ui.visibility` | Tool descriptor | string[] | default `["model", "app"]` | Controls whether a tool is available to the model, the UI, or both. The `app` value is the MCP Apps protocol identifier for UI. |
| `_meta["openai/outputTemplate"]` | Tool descriptor | string (URI) | None | OpenAI-specific optional/compatibility alias for `_meta.ui.resourceUri` in ChatGPT. |
| `_meta["openai/widgetAccessible"]` | Tool descriptor | boolean | default `false` | OpenAI-specific compatibility field used by existing UI integrations; prefer `_meta.ui.visibility` + `tools/call`. |
| `_meta["openai/visibility"]` | Tool descriptor | string | `public` (default) or `private` | OpenAI-specific compatibility field used by existing UI integrations; prefer `_meta.ui.visibility`. |
| `_meta["openai/toolInvocation/invoking"]` | Tool descriptor | string | ≤ 64 chars | Short status text while the tool runs. |
| `_meta["openai/toolInvocation/invoked"]` | Tool descriptor | string | ≤ 64 chars | Short status text after the tool completes. |
| `_meta["openai/fileParams"]` | Tool descriptor | string[] | None | List of top-level input fields that represent files. Each field receives `{ download_url, file_id, mime_type?, file_name? }`. |

Example:

```
import { registerAppTool } from "@modelcontextprotocol/ext-apps/server";
import { z } from "zod";

registerAppTool(
  server,
  "search",
  {
    title: "Public Search",
    description: "Search public documents.",
    inputSchema: { q: z.string() },
    outputSchema: {
      results: z.array(
        z.object({
          id: z.string(),
          title: z.string(),
          url: z.string(),
        })
      ),
    },
    securitySchemes: [
      { type: "noauth" },
      { type: "oauth2", scopes: ["search.read"] },
    ],
    _meta: {
      securitySchemes: [
        { type: "noauth" },
        { type: "oauth2", scopes: ["search.read"] },
      ],
      ui: { resourceUri: "ui://widget/story.html" },
      // Optional compatibility alias (ChatGPT only):
      // "openai/outputTemplate": "ui://widget/story.html",
      "openai/toolInvocation/invoking": "Searching…",
      "openai/toolInvocation/invoked": "Results ready",
    },
  },
  async ({ q }) => {
    const results = await performSearch(q);

    return {
      structuredContent: { results },
      content: [{ type: "text", text: `Found ${results.length} results.` }],
    };
  }
);
```

### Annotations

To label a tool as “read-only,” use the following [`ToolAnnotations` fields](https://modelcontextprotocol.io/specification/2025-11-25/schema#toolannotations) on the tool descriptor:

| Key | Type | Required | Notes |
| --- | --- | --- | --- |
| `readOnlyHint` | boolean | Required | Signal that the tool only retrieves or computes information and doesn’t create, update, delete, or send data outside the conversation. |
| `destructiveHint` | boolean | Required | Declare that the tool may delete or overwrite user data so the host knows to elicit explicit approval first. |
| `openWorldHint` | boolean | Required | Declare that the tool publishes content or reaches outside the current user’s account, prompting the client to summarize the impact before asking for approval. |
| `idempotentHint` | boolean | Optional | Declare that calling the tool with the same arguments has no extra effect on its environment. |

These hints only influence how ChatGPT or Codex frames the tool call to the user; servers must still enforce their own authorization logic.

Example:

```
import { z } from "zod";

server.registerTool(
  "list_saved_recipes",
  {
    title: "List saved recipes",
    description: "Returns the user’s saved recipes without modifying them.",
    inputSchema: {},
    outputSchema: {
      recipes: z.array(
        z.object({
          id: z.string(),
          title: z.string(),
        })
      ),
    },
    annotations: { readOnlyHint: true },
  },
  async () => ({
    structuredContent: { recipes: await fetchSavedRecipes() },
  })
);
```

## Component resource `_meta` fields

Set these keys on the resource template that serves your component (`registerResource`). They help ChatGPT describe and frame the rendered iframe without leaking metadata to other clients.

| Key | Placement | Type | Purpose |
| --- | --- | --- | --- |
| `_meta.ui.prefersBorder` | Resource contents | boolean | Hint that the component should render inside a bordered card when supported. |
| `_meta.ui.csp` | Resource contents | object | Preferred metadata surface for standard widget CSP fields: `connectDomains`, `resourceDomains`, and optional `frameDomains`. |
| `_meta.ui.domain` | Resource contents | string (origin) | Dedicated origin for hosted components (required when submitting a plugin with UI; must be unique per plugin). Defaults to `https://web-sandbox.oaiusercontent.com`. |
| `_meta["openai/widgetDescription"]` | Resource contents | string | Human-readable summary surfaced to the model when the component loads, reducing redundant assistant narration. |
| `_meta["openai/widgetPrefersBorder"]` | Resource contents | boolean | OpenAI-specific compatibility alias for `_meta.ui.prefersBorder` in ChatGPT. |
| `_meta["openai/widgetCSP"]` | Resource contents | object | Legacy ChatGPT compatibility key for widget CSP metadata. Standard CSP fields are superseded by `_meta.ui.csp`, but `redirect_domains` is still required for trusted `openExternal` destinations. |
| `_meta["openai/widgetDomain"]` | Resource contents | string (origin) | OpenAI-specific compatibility alias for `_meta.ui.domain` in ChatGPT. |

ChatGPT supports the legacy `_meta["openai/widgetCSP"]` compatibility key with the following snake_case field names:

*   `connect_domains`: `string[]`
*   `resource_domains`: `string[]`
*   `frame_domains?`: `string[]`
*   `redirect_domains?`: `string[]`. ChatGPT extension for `window.openai.openExternal` redirect targets.

The standard `_meta.ui.csp` object is generally preferred for new UI and supports:

*   `connectDomains`: `string[]`. Domains the widget may contact via fetch/XHR.
*   `resourceDomains`: `string[]`. Domains for static assets (images, fonts, scripts, styles).
*   `frameDomains?`: `string[]`. Optional list of origins allowed for iframe embeds. By default, widgets can’t render subframes; adding `frameDomains` opts in to iframe usage and triggers stricter plugin review.

However, `_meta.ui.csp` does not support `redirect_domains` for `window.openai.openExternal(...)` links. To allowlist redirect targets, you must still set `_meta["openai/widgetCSP"].redirect_domains`.

## Tool results

Tool results can contain the following [fields](https://modelcontextprotocol.io/specification/2025-06-18/server/tools#tool-result). Notably:

| Key | Type | Required | Notes |
| --- | --- | --- | --- |
| `structuredContent` | object | Optional | Surfaced to the model and the component. Must match the declared `outputSchema`, when provided. |
| `content` | string or `Content[]` | Optional | Surfaced to the model and the component. |
| `_meta` | object | Optional | Delivered only to the component. Hidden from the model. |

Only `structuredContent` and `content` appear in the conversation transcript. The host forwards `_meta` to the component so you can hydrate UI without exposing the data to the model.

Host-provided tool result metadata:

| Key | Placement | Type | Purpose |
| --- | --- | --- | --- |
| `_meta["openai/widgetSessionId"]` | Tool result `_meta` (from host) | string | Stable ID for the currently mounted widget instance; use it to correlate logs and tool calls until the widget unmounts. |

Example:

```
import { registerAppTool } from "@modelcontextprotocol/ext-apps/server";
import { z } from "zod";

registerAppTool(
  server,
  "get_zoo_animals",
  {
    title: "get_zoo_animals",
    inputSchema: { count: z.number().int().min(1).max(20).optional() },
    outputSchema: {
      animals: z.array(
        z.object({
          id: z.string(),
          name: z.string(),
          species: z.string(),
        })
      ),
    },
    _meta: { ui: { resourceUri: "ui://widget/widget.html" } },
  },
  async ({ count = 10 }) => {
    const animals = generateZooAnimals(count);

    return {
      structuredContent: { animals },
      content: [{ type: "text", text: `Here are ${animals.length} animals.` }],
      _meta: {
        allAnimalsById: Object.fromEntries(
          animals.map((animal) => [animal.id, animal])
        ),
      },
    };
  }
);
```

### Error tool result

To return an error on the tool result, use the following `_meta` key:

| Key | Purpose | Type | Notes |
| --- | --- | --- | --- |
| `_meta["mcp/www_authenticate"]` | Error result | string or string[] | RFC 7235 `WWW-Authenticate` challenges to trigger OAuth. |

## `_meta` fields the client provides

| Key | When provided | Type | Purpose |
| --- | --- | --- | --- |
| `_meta["openai/locale"]` | Initialize + tool calls | string (BCP 47) | Requested locale (older clients may send `_meta["webplus/i18n"]`). |
| `_meta["openai/userAgent"]` | Tool calls | string | Optional, best-effort user agent hint for analytics or formatting. |
| `_meta["openai/userLocation"]` | Tool calls | object | Coarse location hint (`city`, `region`, `country`, `timezone`, `longitude`, `latitude`). |
| `_meta["openai/subject"]` | Tool calls | string | Anonymized user id sent to MCP servers for the purposes of rate limiting and identification |
| `_meta["openai/session"]` | Tool calls | string | Anonymized conversation id for correlating tool calls within the same ChatGPT session. |
| `_meta["openai/organization"]` | Tool calls | string | Anonymized organization id associated with the current ChatGPT organization, when available. |

Operation-phase `_meta["openai/userAgent"]` and `_meta["openai/userLocation"]` are hints only; servers should never rely on them for authorization decisions and must tolerate their absence. Treat `_meta["openai/userAgent"]` as optional, best-effort metadata rather than a stable way to detect which host surface is calling your server.

Example:

```
import { z } from "zod";

server.registerTool(
  "recommend_cafe",
  {
    title: "Recommend a cafe",
    inputSchema: {},
    outputSchema: {
      cafes: z.array(
        z.object({
          name: z.string(),
          address: z.string(),
        })
      ),
    },
  },
  async (_args, { _meta }) => {
    const locale = _meta?.["openai/locale"] ?? "en";
    const location = _meta?.["openai/userLocation"]?.city;
    const cafes = await findNearbyCafes(location);

    return {
      content: [{ type: "text", text: formatIntro(locale, location) }],
      structuredContent: { cafes },
    };
  }
);
```

Ask AI

## Docs agent

Loading docs agent...