openai/openai-cli 来源：https://github.com/openai/openai-cli

OpenAI CLI

OpenAI REST API (https://platform.openai.com/docs) 的官方命令行工具。

安装

使用 Homebrew 安装

brew install openai/tools/openai

使用 Go 安装

要在本地测试或安装 CLI，需要安装 Go (https://go.dev/doc/install) 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 中：

# 添加到您的 shell 配置文件（.zshrc、.bashrc 等）
export PATH="$PATH:$(go env GOPATH)/bin"

首次符合条件的交互式 openai 运行会静默保存图像选择器的 Tab 快捷键，供后续 Bash、zsh 和 fish 会话使用。打开新终端即可使用。关于前置要求和退出方式，请参阅 快捷键设置与移除。

PowerShell 保留正常的 Tab 补全；在 openai images generate 后按 Enter 即可打开选择器。

更新通知

裸 openai 命令会在 stdin、stdout 和 stderr 都是终端时检查是否有新的稳定版本。它会在帮助信息下方添加纯文本通知，最多每七天一次。显式帮助、命令、补全、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 [子资源...] [标志...]

标准 API 端点需要 API 密钥 (https://platform.openai.com/settings/organization/api-keys)：

export OPENAI_API_KEY="sk-..."
openai responses create \
  --input "Say this is a test" \
  --model gpt-5.5

管理端点需要管理员 API 密钥 (https://platform.openai.com/settings/organization/admin-keys)：

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               # 安全地输入您的 API 密钥
openai images generate --help   # 示例和每个图像选项
openai help images generate     # 相同的完整图像帮助
openai --help                   # 命令组和全局选项

在任何命令后添加 --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 独立于成功输出提取错误数据。格式错误或空的错误响应体会收到安全的诊断信息；HTTP 状态码仅在 SDK 保留时才包含。摘要省略被拒绝的值和请求 URL；显式 API 错误详情可能包含服务器提供的敏感数据。

环境变量

全局标志

• --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 语法 (https://github.com/tidwall/gjson/blob/master/SYNTAX.md) 转换数据输出
• --transform-error — 使用 GJSON 语法 (https://github.com/tidwall/gjson/blob/master/SYNTAX.md) 转换错误输出

请求头

在资源命令之前或之后使用 --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（mTLS）

双向 TLS 目前处于 Beta 阶段。要选择加入并为您的组织或项目激活 CA 证书，请按照 OpenAI Mutual TLS Beta Program (https://help.openai.com/en/articles/10876024-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 --arg @abe.jpg

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

openai --arg '{image: "@abe.jpg"}'
# 等价于：openai < --file ./upload.txt

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

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

openai --username '\@abe'

显式编码

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

openai --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

如果不带参数运行 link 脚本，默认链接到 ../openai-go。

贡献

请通过 GitHub issues (https://github.com/openai/openai-cli/issues) 分享 bug 报告和功能请求。拉取请求仅限于仓库协作者；我们不接受来自非协作者的拉取请求。请参阅 CONTRIBUT.md 了解贡献政策和开发指南。

对于安全漏洞，请参阅 SECURITY.md。

许可证

版权所有 2026 OpenAI

本项目基于 Apache License 2.0 授权。