跳到正文
Hacker News· armcat·· 5 小时前AI 评分58

OpenAI 发布官方 CLI，覆盖 REST API 全部资源命令

OpenAI CLI

AI 导读

OpenAI 发布官方命令行工具 openai-cli，按资源结构组织命令，支持 responses、files、images、admin 等接口，需通过 OPENAI_API_KEY 或 OPENAI_ADMIN_KEY 认证。

正文 · AI 翻译

OpenAI REST API 的官方 CLI。

安装

使用 Homebrew 安装

brew install openai/tools/openai

使用 Go 安装

要在本地测试或安装该 CLI，你需要安装 Go 1.26 或更高版本。

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

运行 go install 后，二进制文件会被放到你的 Go bin 目录中：

  • 默认位置：$HOME/go/bin（如果设置了 GOPATH，则为 $GOPATH/bin）
  • 检查你的路径：运行 go env GOPATH 查看基础目录

如果安装后找不到命令，请将 Go bin 目录添加到你的 PATH：

# Add to your shell profile (.zshrc, .bashrc, etc.)
export PATH="$PATH:$(go env GOPATH)/bin"

首次符合条件的交互式 openai 运行会静默保存图像选择器 Tab 快捷键，供之后的 Bash、zsh 和 fish 会话使用。打开新终端即可使用它们。有关要求和退出方式，请参阅 快捷键设置与移除。PowerShell 保留正常的 Tab 补全；在 openai images generate 后按 Enter 打开选择器。

更新提示

当 stdin、stdout 和 stderr 都是终端时，裸 openai 会检查是否有更新的稳定版本。它会在帮助信息下方添加一条纯文本提示，最多每七天一次。显式帮助、命令、补全、CI 以及重定向的流会完全跳过检查。

当 CLI 能够验证其安装方式时，提示中会包含更新命令。已验证的 Homebrew 安装使用 brew upgrade --cask openai/tools/openai。Go 命令需要已验证的二进制文件、可用的 Go 命令以及显式匹配的 GOBIN。自定义的 GOOS 或 GOARCH 设置会选择安装指南。Go 升级到主版本 2 或更高版本也会选择安装指南。未知安装方式会收到安装指南链接。CLI 从不自动安装更新。

检查使用公开的 GitHub 发布元数据，无需 API 凭据，最多每天一次。检查会遵循 HTTPS_PROXY 和 NO_PROXY，包括它们的小写形式。更新发现最多等待 200 毫秒。检查失败时保持静默。包管理器的可用性可能滞后于新的 GitHub 发布。设置 OPENAI_CLI_NO_UPDATE_CHECK=1 可禁用检查和提示。

本地运行

克隆此项目的 git 仓库后，你可以使用 scripts/run 脚本在本地运行该工具：

./scripts/run args...

用法

该 CLI 遵循基于资源的命令结构：

openai <resource> [subresource...] <command> [flags...]

标准 API 端点需要 API 密钥：

export OPENAI_API_KEY="sk-..."

openai responses create \
  --input "Say this is a test" \
  --model gpt-5.5

管理端点需要 管理 API 密钥：

export OPENAI_ADMIN_KEY="sk-admin-..."

openai admin organization usage completions \
  --start-time 1735689600 \
  --end-time 1735776000 \
  --bucket-width 1d

使用 --help 浏览每个组，例如 openai admin --help 或 openai admin organization --help。现有的冒号命令（如 openai admin:organization:usage completions）继续可用。

运行 openai 可按任务浏览命令组，并查看每个组的描述。组帮助会将操作与嵌套命令组分开，并列出每个直接命令。帮助功能无需 API 密钥或网络连接即可使用：

openai help setup                  # Enter your API key safely
openai images generate --help      # Example and every image option
openai help images generate        # The same complete image help
openai --help                      # Command groups and global options

在任何命令后添加 --help（或 -h）可查看其完整帮助页面。openai help COMMAND 显示相同的页面。命令页面会列出全局选项。使用 openai --help 查看它们的完整描述。你可以将 --help 放在有效的命令选项之后。旧的 help --all 拼写会打印迁移指南和完整页面。命令行为、默认值和输出格式保持不变。Tab 补全遵循相同的组顺序，并支持帮助主题和文件输入路径。升级后，请重新加载 shell 补全以启用新的文件路径行为。已加载的旧补全脚本在刷新之前保持原有行为。

启用命令插入，即可从示例、设置指南和恢复命令中填充你的命令行。按 Ctrl+X，然后按 Tab 可搜索建议而不运行它们。双击 Tab 是 Bash、zsh 和 fish 的可选绑定。

默认情况下，成功的 JSON 响应会打印可读文本，在管道中也是如此。 在解析 API 数据的脚本中使用 --format json 或 --format jsonl。 有关提取、二进制输出以及可读呈现的适用范围，请参阅读取命令结果。

上传一个具有明确用途的本地文件，检查其元数据，然后下载其内容：

openai files upload "upload space.txt" --purpose user_data
openai files get file-example
openai files download file-example --output "downloaded copy.txt"
openai files download file-example > copy.txt

将 file-example 替换为返回的文件 ID。上传接受纯路径，无需添加 @。 create、retrieve、content 及其现有标志仍然可用。 有关字面文件名、输出格式和脚本示例，请参阅使用文件。

openai images generate --prompt "A tiny orange robot" 将图像保存到 ~/Downloads/gpt-images/ 并打印其路径，在管道中也是如此。CLI 在未指定模型或使用旧版响应格式保存时使用 gpt-image-2.5-sunburst。使用 --model 指定另一个确切的 ID，使用 --name 指定文件名， 或使用 --output-dir 指定现有目录。现有文件会被保留。 --format json 返回 API 数据，不保存也不应用 CLI 预设。 images edit 还会在保留源文件的同时保存新结果。 images create-variation 已停用，不再可用。要创建 变体，请使用 images edit 配合 GPT Image 模型和提示词。有关命令 和默认值，请参阅图像生成与保存。

openai images preview "path/to/image.png" 无需 API 请求即可重新显示已保存的图像。使用 openai images inline on 或 off 来记住未来 保存的图像是否自动显示。每条命令的 --inline auto、on 或 off 会覆盖该设置。on 还允许在本地 Apple Terminal 中使用图像字体。

默认情况下，错误会将可操作的摘要打印到 stderr。使用 --format-error json 获取原始 API 错误详情，包括未知字段和 SDK 报告的流 错误事件。对于这些事件，提取路径包括 error 信封， 例如 --transform-error error.code。显式的 --format 值 json、jsonl、raw 和 yaml 也适用于错误，除非被 --format-error 覆盖；显式的 --format-error auto 或 text 会恢复摘要。 --transform-error 独立于成功输出提取错误数据。 格式错误或为空的错误体会收到安全诊断信息；仅当 SDK 保留 HTTP 状态时才会包含该状态。摘要会省略被拒绝的值和请求 URL； 显式的 API 错误详情可能包含服务器提供的敏感数据。

环境变量

环境变量 必需 默认值
OPENAI_API_KEY 否 null
OPENAI_ADMIN_KEY 否 null
OPENAI_ORG_ID 否 null
OPENAI_PROJECT_ID 否 null
OPENAI_WEBHOOK_SECRET 否 null
OPENAI_CUSTOM_HEADERS 否 null
OPENAI_MTLS_CLIENT_CERT_FILE 否 null
OPENAI_MTLS_CLIENT_KEY_FILE 否 null
OPENAI_UNTRUSTED_STDIN 否 false

全局标志

  • --api-key（也可通过 OPENAI_API_KEY 环境变量设置）
  • --admin-api-key（也可通过 OPENAI_ADMIN_KEY 环境变量设置）
  • --organization（也可通过 OPENAI_ORG_ID 环境变量设置）
  • --project（也可通过 OPENAI_PROJECT_ID 环境变量设置）
  • --webhook-secret（也可通过 OPENAI_WEBHOOK_SECRET 环境变量设置）
  • --mtls-client-cert-file（也可通过 OPENAI_MTLS_CLIENT_CERT_FILE 环境变量设置）
  • --mtls-client-key-file（也可通过 OPENAI_MTLS_CLIENT_KEY_FILE 环境变量设置）
  • --help - 显示命令行用法
  • --debug - 启用调试日志记录。这包括 HTTP 请求/响应详情和正文；如果调试日志可能包含敏感负载，请勿分享。
  • --version、-v - 显示 CLI 版本
  • --base-url - 使用自定义 API 后端 URL。除 localhost 或字面回环 IP 地址（如 127.0.0.1 和 ::1）外，需要 HTTPS。 这也适用于 OPENAI_BASE_URL；远程 HTTP 后端必须启用 HTTPS。
  • --header、-H - 添加字面请求头，格式为 Name: Value；多个请求头可重复使用
  • --format - 更改输出格式（auto、text、explore、json、jsonl、pretty、raw、yaml）；除非提取数据，否则 auto 选择可读文本
  • --format-error - 更改 stderr 错误格式（auto、text、explore、json、jsonl、pretty、raw、yaml）；除非提取错误数据，否则 auto 选择可读摘要
  • --transform - 使用 GJSON 语法转换数据输出
  • --transform-error - 使用 GJSON 语法转换错误输出

请求头

在资源命令之前或之后使用 --header 或 -H：

openai --header 'X-Trace-ID: example-123' models list \
  -H 'X-Client-Label: local,manual'

值是字面量：逗号和冒号会被保留，@ 前缀不会读取文件。值两端的空格和制表符会被去除。-H 'X-Example:' 发送空值。如果名称重复，无论大小写，最后一个值生效，并覆盖默认标头和端点特定标头。由 HTTP 传输层管理的标头（例如 Host 和 Content-Length）保留传输层的行为。提供的标头值在帮助信息中隐藏，并在调试日志中脱敏。

对于携带凭据的标头，请让密钥管理器或受信任的启动器直接在 CLI 的环境中设置 OPENAI_CUSTOM_HEADERS。这样可使凭据不出现在命令参数中，并避免将字面密钥输入 shell 历史记录。该变量每行接受一个 Name: Value 条目。例如，使用非敏感值：

export OPENAI_CUSTOM_HEADERS='X-Trace-ID: example-123
X-Client-Label: local,manual'
openai models list

--header 和端点特定标头标志会覆盖匹配的环境条目。环境标头值也会在调试日志中脱敏。使用 OPENAI_API_KEY 和 OPENAI_ADMIN_KEY 进行标准 API 和管理员身份验证。

双向 TLS

双向 TLS 目前处于测试阶段。要选择加入并为您的组织或项目激活 CA 证书，请遵循 OpenAI Mutual TLS Beta Program 的说明。

要使用双向 TLS 客户端证书对 API 密钥请求进行身份验证，请将客户端证书和私钥作为单独的 PEM 文件提供。如果您的组织启用了证书链支持，证书文件必须首先包含叶证书，然后是任何中间证书。否则，请使用由已激活的 CA 证书直接签名的客户端证书。

export OPENAI_MTLS_CLIENT_CERT_FILE=/run/secrets/openai/client-chain.pem
export OPENAI_MTLS_CLIENT_KEY_FILE=/run/secrets/openai/client.key
export OPENAI_BASE_URL=https://mtls.api.openai.com/v1

openai files list

两个 mTLS 文件必须一起配置。将私钥保存在权限受限的文件中；不要将私钥内容直接放在命令参数或环境变量中。CLI 不会自动选择 mTLS 端点，因此请显式配置 OPENAI_BASE_URL 或 --base-url。HTTP 和 SOCKS 代理仍然受支持，但 HTTPS 代理会被拒绝，以防止在代理自身的 TLS 握手期间出示客户端证书。

将文件作为参数传递

对于 JSON 输入值，@myfile.ext 读取本地文件内容：

二进制上传标志使用普通路径。例如，使用 files upload --file "upload space.txt" --purpose user_data。此处，--file "@upload space.txt" 指定一个以 @ 开头的实际文件；它不会展开另一个文件引用。请参阅使用文件。

openai <command> --arg @abe.jpg

文件也可以在 JSON 或 YAML 块中传递：

openai <command> --arg '{image: "@abe.jpg"}'
# Equivalent:
openai <command> <<YAML
arg:
  image: "@abe.jpg"
YAML

当从不受信任的来源管道传输 JSON 或 YAML 时，启用不受信任的 stdin 模式：

untrusted-producer | OPENAI_UNTRUSTED_STDIN=1 openai <command> --file ./upload.txt

在此模式下，通过 stdin 提供的值被视为字面数据：请求体、标头和查询参数中的 @、@file:// 和 @data:// 引用不会读取本地文件。文件上传参数必须显式作为命令行标志提供。显式标志保留其正常的文件行为，并优先于通过 stdin 提供的值。当使用受信任的 heredoc 或其他有意引用本地文件的受信任管道输入时，请将 OPENAI_UNTRUSTED_STDIN 保持未设置。

如果需要传递以 @ 符号开头的字符串字面量，可以转义 @ 符号以避免意外传递文件。

openai <command> --username '\@abe'

显式编码

对于 JSON 端点，CLI 工具会进行文件类型嗅探，以确定文件内容应作为字符串字面量（对于纯文本文件）还是作为 base64 编码的字符串字面量（对于二进制文件）发送。如果您需要显式地将文件作为纯文本或 base64 编码数据发送，可以使用 @file://myfile.txt（用于字符串编码）或 @data://myfile.dat（用于 base64 编码）。请注意，绝对路径将以 @file:// 或 @data:// 开头，后跟第三个 /（例如，@file:///tmp/file.txt）。

openai <command> --arg @data://file.txt

链接不同的 Go SDK 版本

你可以使用 ./scripts/link 脚本，将 CLI 链接到不同版本的 OpenAI Go SDK，以便进行开发。

要从仓库链接到特定版本（版本可以是分支、git 标签或提交哈希）：

./scripts/link github.com/org/repo@version

要链接到 SDK 的本地副本：

./scripts/link ../path/to/openai-go

如果你运行链接脚本时不带任何参数，它将默认使用 ../openai-go。

贡献

请通过 GitHub issues 分享错误报告和功能请求。 拉取请求仅限仓库协作者提交；我们不接受非协作者的拉取请求。 有关贡献政策和开发指南，请参阅 CONTRIBUTING.md。 对于安全漏洞，请遵循 SECURITY.md。

许可证

版权所有 2026 OpenAI

本项目根据 Apache License 2.0 许可。

来源：Hacker News · github.com

OpenAI / ChatGPT部署工程产品更新#产品更新#部署/工程#OpenAI