主导航

推荐

开始使用

核心概念

Agents SDK

工具

运行与扩展

评估

实时与音频

模型优化

专用模型

上线

遗留 API

资源

API 控制台

OpenAI CLI

直接从终端使用 OpenAI API。

通过 openai 命令行工具直接在终端与 OpenAI API 进行交互。

安装

使用 Homebrew 安装 CLI

brew install openai/tools/openai

或者使用 Go 1.25 或更高版本进行安装

go install 'github.com/openai/openai-cli/cmd/openai@latest'

Python SDK 的旧版本也安装了遗留的 openai 命令。如果您已经安装了该包，并且您看到的命令与本指南不符，可能是因为您的 shell 仍在解析旧的二进制文件。新安装的 CLI 不受此影响。

身份验证

CLI 会从 OPENAI_API_KEY 读取您的 API 密钥

命令

export OPENAI_API_KEY="sk-..."

如果您还没有 API 密钥，请在 仪表板中创建一个。

对于管理 API 端点，请改用 OPENAI_ADMIN_KEY。SDK 层会根据调用的端点自动选择管理密钥或默认 API 密钥。

要指向不同的 API 主机，请设置 OPENAI_BASE_URL。

使用案例

在工作自然属于终端环境时，请使用 CLI

  • 生成本地工件，例如图像或语音。
  • 将结构化数据提取为 JSONL，以便进行后续的 shell 处理步骤。
  • 在云端使用 Responses 处理文件、计算机使用和当前 Web 上下文。
  • 使用管理 API 创建项目和 API 密钥。

直接用于一次性的终端请求，或者在代理需要对文件和生成的工件进行可重复的批量工作时，从脚本中调用。

Codex 的 CLI 与子代理对比

对于您希望检查并重新运行的可重复 API 工作（如批量提取、文件转换、工件生成或审慎的模型选择），请使用 CLI。当工作需要判断（例如探索代码、比较假设、调试或审查更改）时，请使用子代理。

全局标志

这些选项适用于所有命令

标志不如说
--format以 auto、json、jsonl、pretty、raw、yaml 或 explore 格式打印响应。
--transform在打印之前，使用 GJSON 路径提取或重塑响应数据。
--debug将请求和响应详情打印到 stderr。授权信息会被脱敏；在共享日志前请审查请求头。

本指南侧重于 CLI 模式。有关任何 API 系列的最新参数和响应格式，请使用实时的 API 参考文档。

当您需要将 CLI 指向其他兼容的端点（例如支持不同模型集或仅支持部分 API 功能的部署）时，也可以更改基础 URL。

响应

使用 Responses 进行文本生成、结构化提取、网页搜索、文件理解以及 Codex 编写的可重复批处理脚本。

发送您的第一个请求

命令

1
2
3
openai responses create \
--model gpt-5.5 \
--input "Say hello in one sentence."

输出

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
{
  "id": "resp_...",
  "object": "response",
  "status": "completed",
  "model": "gpt-5.5-...",
  "output": [
    {
      "type": "message",
      "role": "assistant",
      "content": [
        {
          "type": "output_text",
          "text": "Hello!"
        }
      ]
    }
  ],
  "usage": {
    "input_tokens": 12,
    "output_tokens": 6,
    "total_tokens": 18
  },
  "...": "additional response fields omitted"
}

CLI 默认打印完整的 API 响应对象。本页示例保留了 id、status、model、output 和 usage 等具有代表性的字段，并省略了其余部分。

Responses 的输出可能包含非消息项（例如推理项），这些项位于助手消息之前。当您需要助手文本时，请按类型选择消息项，而不是假设它始终是 output[0]。

--transform 'output.#(type=="message").content.0.text'

将本地文件添加到提示词中

对于简单的本地文件，通过命令替换在行内构建提示词

1
2
3
4
5
6
7
8
9
openai responses create \
--model gpt-5.5 \
--input "Summarize this note in one sentence.

<note>
$(cat ./note.md)
</note>" \
--format yaml \
--transform 'output.#(type=="message").content.0.text'

输出

The note says the launch checklist is ready except for final support ownership.

传递请求体

使用标志处理短标量输入。对于多行提示词、工具、文件或嵌套请求体，请使用 YAML 继承文档（heredoc）。继承文档可以包含您本可以使用标志传递的所有请求字段。

小心处理看起来像 YAML 的字符串值，尤其是包含 : 或 {} 的提示词。在标志中，生成的解析器可能会将这些值解释为结构化 YAML 而非纯文本。如果提示词看起来像配置，请将其放在 YAML 体中的 input: | 下方。

命令

1
2
3
4
5
6
7
8
9
10
11
12
13
openai responses create \
  --format yaml \
  --transform 'output.#(type=="message").content.0.text' <<'YAML'
model: gpt-5.5
instructions: Return exactly one sentence.
max_output_tokens: 120
input: |
  Summarize this release note in one sentence.

  <release_note>
  Fixed the image generation example and added CLI installation guidance.
  </release_note>
YAML

输出

The release note updates the CLI docs with corrected image generation and installation guidance.

当提示词本身需要 shell 组装时，请构建一个 YAML 体并将其通过管道传给命令

1
2
3
4
5
6
7
8
9
10
{
printf 'input: |\n'
printf '  Summarize this note in one sentence.\n\n'
printf '  <note>\n'
sed 's/^/  /' ./note.md
printf '  </note>\n'
} | openai responses create \
--model gpt-5.5 \
--format yaml \
--transform 'output.#(type=="message").content.0.text'

将结构化数据写入 JSON

当下游脚本需要稳定的 JSON 时，使用结构化输出。将可重用的模式保存到磁盘

保存为 schema.json

1
2
3
4
5
6
7
8
9
10
11
12
13
14
{
  "type": "json_schema",
  "name": "fact",
  "strict": true,
  "schema": {
    "type": "object",
    "additionalProperties": false,
    "properties": {
      "person": { "type": "string" },
      "topic": { "type": "string" }
    },
    "required": ["person", "topic"]
  }
}

命令

1
2
3
4
5
6
7
openai responses create \
--model gpt-5.5 \
--instructions "Extract the person and topic from the input." \
--input "Ada Lovelace wrote notes about the Analytical Engine." \
--text.format "$(cat ./schema.json)" \
--format yaml \
--transform 'output.#(type=="message").content.0.text'

输出

{ "person": "Ada Lovelace", "topic": "notes about the Analytical Engine" }

将结构化记录写入 JSONL

当一个输入可能产生多个记录时，要求模型提供一个数组并将其展平为 JSONL，以便后续的 shell 步骤可以逐行处理记录

保存为 records-schema.json

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
{
  "type": "json_schema",
  "name": "items",
  "strict": true,
  "schema": {
    "type": "object",
    "additionalProperties": false,
    "properties": {
      "items": {
        "type": "array",
        "items": {
          "type": "object",
          "additionalProperties": false,
          "properties": {
            "title": { "type": "string" },
            "summary": { "type": "string" },
            "evidence": { "type": "string" }
          },
          "required": ["title", "summary", "evidence"]
        }
      }
    },
    "required": ["items"]
  }
}

命令

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
: > records.jsonl

for file in notes/*.md; do
  extracted="$(
    openai responses create \
      --model gpt-5.5 \
      --text.format "$(cat ./records-schema.json)" \
      --raw-output \
      --transform 'output.#(type=="message").content.0.text' <<YAML
input: |
  <note path="$file">
$(sed 's/^/  /' "$file")
  </note>
YAML
  )"

  jq -r --arg source "$file" \
    '.items[]? + {source: $source} | @json' \
    <<<"$extracted" >> records.jsonl
done

这样既能保持模型响应的结构化，又能为后续的 shell 步骤生成每行一个 JSON 对象的数据。

网络搜索

Responses 可以从同一个 YAML 请求体中调用托管工具

命令

1
2
3
4
5
6
7
8
9
10
openai responses create \
--model gpt-5.5 \
--format yaml \
--transform 'output.#(type=="message").content.0.text' <<'YAML'
tools:
- type: web_search
input: |
Research the latest material news for AAPL.
Return three concise bullets and cite sources in the text.
YAML

输出

- Apple announced ...
- Analysts highlighted ...
- The company said ...

文件输入

对于上传的文件（如 PDF），请先创建文件，捕获其 ID，然后将其作为 input_file.file_id 传递

命令

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
FILE_ID=$(
  openai files create \
    --file ./brief.pdf \
    --purpose user_data \
    --format yaml \
    --transform id
)

openai responses create \
  --model gpt-5.5 \
  --format yaml \
  --transform 'output.#(type=="message").content.0.text' <<YAML
input:
  - role: user
    content:
      - type: input_text
        text: Summarize this brief and list three risks.
      - type: input_file
        file_id: ${FILE_ID}
YAML

输出

- The brief proposes ...
- Risks: migration timing, unclear rollback criteria, and unresolved support ownership.

最近生成的构建版本会将本地文件标志作为具有文件名和内容类型元数据的多部分文件部件发送。如果本地上传命令因 UploadFile 类型错误而失败，请更新 CLI 后重试。

图像

生成图像

生成图像，提取 base64 负载，并将其解码为常规资源文件

命令

1
2
3
4
5
6
openai images generate \
  --model gpt-image-2 \
  --prompt "A simple product-style render of a translucent green cube on a neutral background." \
  --format yaml \
  --transform 'data.0.b64_json' | base64 --decode > hero.png
printf 'wrote hero.png\n'

输出

wrote hero.png

当前限制：图像命令尚未原生支持 --output，因此图像生成仍需要自行提取 b64_json 并进行解码。

对于 gpt-image-2，请省略 --input-fidelity；图像输入始终以高保真度处理。不要对 gpt-image-2 使用 --background transparent。该模型还支持比早期 GPT Image 模型更广泛的 --size 值，只要所请求的分辨率满足图像 API 的尺寸约束即可。

编辑图像

图像编辑在编辑请求成功后，使用相同的 base64 提取模式

命令

1
2
3
4
5
6
7
openai images edit \
  --model gpt-image-2 \
  --image ./hero.png \
  --prompt "Turn the cube bright green." \
  --format yaml \
  --transform 'data.0.b64_json' | base64 --decode > hero-edited.png
printf 'wrote hero-edited.png\n'

输出

wrote hero-edited.png

如果本地图像编辑上传因 UploadFile 类型错误而失败，请更新 CLI 后重试。

语音 (Speech)

使用语音 API 在本地创建 MP3

命令

1
2
3
4
5
openai audio:speech create \
  --model gpt-4o-mini-tts \
  --voice marin \
  --input "The OpenAI CLI can call the API from ordinary shell scripts." \
  --output speech.mp3

输出

Wrote output to: speech.mp3

使用您机器上可用的任何本地音频工具播放它。在 macOS 上

afplay speech.mp3

使用 --instructions 来塑造表达方式，使用 --input 来指定要朗读的文字。指令在控制语速、能量、情感温暖度、正式程度、强调重点或受众方面效果很好。

1
2
3
4
5
6
openai audio:speech create \
  --model gpt-4o-mini-tts \
  --voice marin \
  --instructions "Whisper very quickly, like a hurried stage cue, while staying clear and intelligible." \
  --input "The launch checklist is ready. Please send final feedback by Friday at noon." \
  --output reminder.mp3

语音转文字

为 shell 管道打印纯转录文本

命令

1
2
3
4
5
openai audio:transcriptions create \
  --model gpt-4o-transcribe \
  --file ./speech.mp3 \
  --transform text \
  --raw-output

输出

The OpenAI CLI can call the API from ordinary shell scripts.

使用符合您所需工件的响应格式

需要命令形态
纯转录文本--model gpt-4o-transcribe --transform text --raw-output
字幕文件--model whisper-1 --response-format srt 或 --response-format vtt
分段或单词时间戳--model whisper-1 --response-format verbose_json
带有说话人标记的日记标注（Diarization）--model gpt-4o-transcribe-diarize --response-format diarized_json

对于单词级计时，请请求详细转录格式

命令

1
2
3
4
5
6
openai audio:transcriptions create \
  --model whisper-1 \
  --file ./speech.mp3 \
  --response-format verbose_json \
  --timestamp-granularity word \
  --format json

输出

1
2
3
4
5
6
7
8
9
10
11
{
  "task": "transcribe",
  "language": "english",
  "duration": 6,
  "text": "The OpenAI CLI can call the API from ordinary shell scripts.",
  "words": [
    { "word": "The", "start": 0, "end": 0.42 },
    { "word": "OpenAI", "start": 0.42, "end": 1.22 }
  ],
  "...": "additional response fields omitted"
}

对于带有说话人标签的输出，请使用日记标注模型并请求 diarized_json

命令

1
2
3
4
5
openai audio:transcriptions create \
  --model gpt-4o-transcribe-diarize \
  --file ./speech.mp3 \
  --response-format diarized_json \
  --format json

输出

1
2
3
4
5
6
7
8
9
10
11
12
13
14
{
  "text": "The OpenAI CLI can call the API from ordinary shell scripts.",
  "segments": [
    {
      "type": "transcript.text.segment",
      "id": "seg_0",
      "start": 0.05,
      "end": 5.25,
      "text": " The OpenAI CLI can call the API from ordinary shell scripts.",
      "speaker": "A"
    }
  ],
  "...": "additional response fields omitted"
}

whisper-1 支持 json, text, srt, verbose_json 和 vtt。diarized_json 是携带 segments[].speaker 的格式；如果使用相同的日记标注模型但仅请求纯 json，响应中包含转录文本但不含说话人标签。

管理员 API

使用管理 API 进行组织管理、凭证配置、合规性检查和使用监控流程。设置 OPENAI_ADMIN_KEY，然后调用生成的 admin:organization:* 命令。

要配置新的机器凭证，请 创建一个项目，在该项目中 创建一个服务账号，并使用返回的 API 密钥。

创建一个项目、服务账号和 API 密钥

在项目中创建服务账号会返回一个非脱敏的 API 密钥，供该服务账号使用。

命令

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
# Create the project that will own this app or agent and save the response.
openai admin:organization:projects create \
  --name "automation project" \
  --format json > project.json
PROJECT_ID="$(jq -r '.id' project.json)"

# Create a service account inside the project and save the full response.
openai admin:organization:projects:service-accounts create \
  --project-id "$PROJECT_ID" \
  --name "automation bot" \
  --format json > service-account.json

# Extract the returned API key into an env file for the workload to use.
jq -r '.api_key.value | "OPENAI_API_KEY=\(.)"' \
  service-account.json > .env

输出

1
2
3
4
5
6
7
8
9
10
{
  "object": "organization.project.service_account",
  "id": "svc_acct_...",
  "name": "automation bot",
  "role": "member",
  "api_key": {
    "id": "key_...",
    "value": "sk-..."
  }
}

此操作将项目响应写入 project.json，将其 ID 解析到下一个命令中，将服务账号响应写入 service-account.json，并将返回的凭证写入 .env 文件作为 OPENAI_API_KEY=...。请将两个 JSON 文件视为机密，并在存储库中使用此模式之前，将 project.json、service-account.json 和 .env 添加到 .gitignore 中。

有关其余功能，请参阅 管理 API 指南 和当前的 管理 API 参考文档。请务必小心，不要让未经审核的人员访问管理密钥。

© . This website operates independently and is not affiliated with or endorsed by OpenAI, Inc. All brand names, logos, and trademarks are the property of their respective owners.