OpenAI 命令行工具（OpenAI CLI）是面向 OpenAI REST API 的官方命令行工具。可通过 Homebrew 安装，命令为 brew install openai/tools/openai；也可用 Go 本地测试或安装，需要 Go 1.26 或更高版本，执行 go install github.com/openai/openai-cli/cmd/openai@latest。运行后二进制文件放入 Go bin 目录，默认路径为 $HOME/go/bin（若设置 GOPATH 则为 $GOPATH/bin），可用 go env GOPATH 查看基础目录。若安装后找不到命令，需把 Go bin 目录加入 PATH。首次符合条件的交互式 openai 运行会为今后的 Bash、zsh 和 fish 会话静默保存图片选择器 Tab 快捷键，PowerShell 保留普通 Tab 补全并在 openai images generate 后按 Enter 打开选择器。
正文
OpenAI CLI
OpenAI REST API 的官方命令行工具。
安装
通过 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：
添加到 shell 配置文件（.zshrc、.bashrc 等）
export PATH="$PATH:$(go env GOPATH)/bin"
首次符合条件的交互式 openai 运行会静默保存 image picker 的 Tab 快捷键，供未来的 Bash、zsh 和 fish 会话使用。打开新终端即可使用。快捷键的设置和移除要求及退出方式见 shortcut setup and removal。PowerShell 保留正常的 Tab 补全；在 openai images generate 后按 Enter 打开 picker。
更新提示
裸命令 openai 在 stdin、stdout 和 stderr 都是终端时会检查更新的稳定版。它会在帮助信息下方添加纯文本提示，最多每七天一次。显式帮助、命令、补全、CI 以及重定向流会完全跳过检查。
当 CLI 能验证其安装方式时，提示会包含更新命令。已验证的 Homebrew 安装使用 brew upgrade --cask openai/tools/openai。Go 命令需要已验证的二进制、可用的 go 命令以及显式匹配的 GOBIN。自定义 GOOS 或 GOARCH 设置会选择安装指南。升级到 Go 主版本 2 或更高也会选择安装指南。未知安装方式会收到安装指南链接。CLI 从不自动安装更新。
检查使用公共 GitHub release 元数据，无需 API 凭据，每天最多一次。检查遵循 HTTPS_PROXY 和 NO_PROXY（包括小写形式）。更新发现最多等待 200 毫秒。失败的检查保持静默。包管理器的可用性可能滞后于新的 GitHub release。设置 OPENAI_CLI_NO_UPDATE_CHECK=1 可禁用检查和提示。
本地运行
克隆本项目 git 仓库后，可使用 scripts/run 脚本在本地运行工具：
./scripts/run args...
用法
CLI 采用基于资源的命令结构：
openai
标准 API 端点需要 API key：
export OPENAIAPIKEY="sk-..." openai responses create \ --input "Say this is a test" \ --model gpt-5.5
管理员端点需要管理员 API key：
export OPENAIADMINKEY="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 key 或网络连接：
openai help setup # 安全输入 API key openai images generate --help # 示例和所有图像选项 openai help images generate # 同样的完整图像帮助 openai --help # 命令组和全局选项
任何命令加上 --help（或 -h）可查看完整帮助页。openai help COMMAND 显示相同页面。命令页会列出全局选项。完整描述请用 openai --help。--help 可放在有效命令选项之后。旧的 help --all 拼写会打印迁移指南和完整页面。命令行为、默认值和输出格式保持不变。Tab 补全遵循相同的组顺序，并支持帮助主题和文件输入路径。升级后需重新加载 shell 补全以启用新的文件路径行为。旧版已加载的补全脚本在刷新前保持原有行为。
启用 command insertion 可从示例、设置指导和恢复命令填充命令行。Ctrl+X 然后 Tab 会搜索建议但不执行。Double Tab 是 Bash、zsh 和 fish 的可选绑定。
成功的 JSON 响应默认打印可读文本，包括在管道中。在解析 API 数据的脚本中使用 --format json 或 --format jsonl。提取、二进制输出以及可读呈现的范围见 reading command results。
上传本地文件时需显式指定 purpose，检查其元数据，然后下载内容：
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 及其现有标志仍然可用。字面文件名、输出格式和脚本示例见 working with files。
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 模型和 prompt。命令与默认值见 image generation and saving。
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 报告的流错误事件。对于这些事件，提取路径包含错误 envelope，例如 --transform-error error.code。显式 --format 值 json、jsonl、raw 和 yaml 也适用于错误，除非被 --format-error 覆盖；显式的 --format-error auto 或 text 会恢复摘要。--transform-error 独立于成功输出提取错误数据。畸形或空错误体会收到安全诊断；仅当 SDK 保留 HTTP 状态时才包含该状态。摘要会省略被拒绝的值和请求 URL；显式 API 错误详情可能包含服务器提供的敏感数据。
环境变量
| 环境变量 | 是否必需 | 默认值 | |---|---|---| | OPENAIAPIKEY | 否 | null | | OPENAIADMINKEY | 否 | null | | OPENAIORGID | 否 | null | | OPENAIPROJECTID | 否 | null | | OPENAIWEBHOOKSECRET | 否 | null | | OPENAICUSTOMHEADERS | 否 | null | | OPENAIMTLSCLIENTCERTFILE | 否 | null | | OPENAIMTLSCLIENTKEYFILE | 否 | null | | OPENAIUNTRUSTEDSTDIN | 否 | 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 后端地址。除 localhost 或字面 loopback 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 错误格式（选项同--format）；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 transport 管理的头（如 Host 和 Content-Length）保持 transport 自身行为。提供的头值在帮助信息中隐藏，在调试日志中被脱敏。
对于携带凭据的请求头，让密钥管理器或可信启动器直接在 CLI 环境中设置 OPENAI_CUSTOM_HEADERS。这样可避免凭据出现在命令参数中，也防止把明文密钥输入 shell 历史。该变量每行接受一个 Name: Value 条目。例如（非敏感值）：
export OPENAICUSTOMHEADERS='X-Trace-ID: example-123 X-Client-Label: local,manual' openai models list
--header 和端点特定的头参数会覆盖匹配的环境变量条目。环境变量中的头值在调试日志中也会被脱敏。标准 API 和管理员认证请分别使用 OPENAI_API_KEY 和 OPENAI_ADMIN_KEY。
双向 TLS
双向 TLS 目前处于 beta 阶段。要启用并为组织或项目激活 CA 证书，请按照 OpenAI Mutual TLS Beta Program 的说明操作。
要使用双向 TLS 客户端证书对 API 密钥请求进行认证，请以独立的 PEM 文件提供客户端证书和私钥。如果组织启用了证书链支持，证书文件必须先是叶证书，随后是任何中间证书；否则，使用由已激活 CA 证书直接签名的客户端证书。
export OPENAIMTLSCLIENTCERTFILE=/run/secrets/openai/client-chain.pem export OPENAIMTLSCLIENTKEYFILE=/run/secrets/openai/client.key export OPENAIBASEURL=https://mtls.api.openai.com/v1 openai files list
两个 mTLS 文件必须同时配置。私钥应保存在权限受限的文件中；不要将私钥内容直接放在命令参数或环境变量中。CLI 不会自动选择 mTLS 端点，因此必须显式配置 OPENAI_BASE_URL 或 --base-url。仍支持 HTTP 和 SOCKS 代理，但会拒绝 HTTPS 代理，以防止在代理自身的 TLS 握手期间出示客户端证书。
将文件作为参数传递
对于 JSON 输入值，@myfile.ext 会读取本地文件内容：
openai
二进制上传标志使用普通路径。例如，使用 files upload --file "upload space.txt" --purpose user_data。这里的 --file "@upload space.txt" 指的是实际以 @ 开头的文件，不会展开另一个文件引用。详见 working with files。
文件也可以放在 JSON 或 YAML 块中传递：
openai
等价写法：
openai 从不受信任的来源管道传入 JSON 或 YAML 时，启用 untrusted-stdin 模式： untrusted-producer | OPENAIUNTRUSTEDSTDIN=1 openai 在此模式下，通过 stdin 提供的值被视为字面数据：请求体、头和查询参数中的 如果需要传递以 openai 对于 JSON 端点，CLI 会做文件类型嗅探，判断文件内容应作为字符串字面量（纯文本文件）还是 base64 编码字符串（二进制文件）发送。如果需要显式以纯文本或 base64 发送文件，可使用 openai 可以使用 链接到仓库中的特定版本（版本可以是分支、git tag 或 commit hash）： ./scripts/link github.com/org/repo@version 链接到本地 SDK 副本： ./scripts/link ../path/to/openai-go 如果不带参数运行 link 脚本，默认使用 请通过 GitHub issues 提交 bug 报告和功能请求。Pull requests 仅限仓库协作者；不接受非协作者的 PR。贡献政策和开发指南见 CONTRIBUTING.md。安全漏洞请遵循 SECURITY.md。 版权所有 2026 OpenAI 本项目基于 Apache License 2.0 授权。@、@file:// 和 @data:// 不会读取本地文件。文件上传参数必须作为命令行标志显式提供。显式标志保留正常文件行为，并优先于通过 stdin 提供的值。当使用可信 heredoc 或其他有意引用本地文件的可信管道输入时，请不要设置 OPENAI_UNTRUSTED_STDIN。@ 开头的字符串字面量，可以转义 @ 以避免意外传入文件：显式编码
@file://myfile.txt（字符串编码）或 @data://myfile.dat（base64 编码）。注意绝对路径会以 @file:// 或 @data:// 开头，后接第三个 /（例如 @file:///tmp/file.txt）。链接不同的 Go SDK 版本
./scripts/link 脚本，让 CLI 在开发时链接不同版本的 OpenAI Go SDK。../openai-go。贡献
许可证
评论
讨论气氛偏怀疑和嘲讽：多数人抱怨 OpenAI 的新工具没有说清自己是什么、解决什么问题，文档满是术语、命名混乱，并顺带嘲讽其“氛围编码”和新的锁定策略；少数人则从强化学习战略角度解释其价值，或指出这类包装早已被社区自己实现。分歧主轴在于它到底是一个早该出现的 agent/工具调用能力，还是一个仓促拼凑、可轻易复制的 CLI 外壳。
认为官方没讲清产品是什么、解决什么问题、和 Codex 有何区别
- 发布说明满是术语，却没有一句话说明用途、价值和适用场景；连“什么时候该用它而不是 Codex、是否该被其他 agent 调用”都要用户自己猜。（较多人）
- 命名混乱加重困惑：Codex 曾被当作 “OpenAI CLI”，而 “chat 与 work” 之类区分也显得随意，整体像氛围编码。（较多人）
- 有人强调，哪怕只是 CLI 包装，也必须写清它解决什么问题和目标用户，否则名字本身解释不了一切。（较多人） > 说名字就能解释工具是站不住脚的，CLI 包装仍需要一行说明它解决什么问题和给谁用。（@guyuedumingx）
提醒不要深陷 OpenAI 工具链：弃用快、质量差、还封提 issue 的人
- 警告 OpenAI 常在两年内几乎弃用所有产品，有时连正式通知都没有；现在这些东西看起来都像没好好评审和测试的氛围编码，基础 bug 很多。（较多人）
- 在 GitHub 反馈问题时常被封号而不是修问题，进一步削弱信任。（较多人） > 小心在 OpenAI 工具上陷太深，他们常在两年内弃用几乎所有东西，有时连通知都没有。（@throw20261022）
认为任何有 API 的人都能轻松做出等价物，并不新鲜
- 发布这类 CLI/agent 包装没门槛，有 OpenAI REST API 的人大概早就自己氛围编码过类似东西了。（少数人） > 任何能调用 OpenAI REST API 的人，大概早就自己氛围编码过等价工具了。（@Traster）
认为这暴露了 OpenAI 的优先级错位和新的锁定
- 讽刺 OpenAI 能几天拼出这种工具，却没有整理 ChatGPT 对话的 API，用户被更深地锁进它的生态。（少数人） > 他们能几天内氛围编码出这种东西，却根本没有整理 ChatGPT 对话的 API，欢迎来到新的锁定。（@bobm_kite9）
认为这是让模型通过强化学习优先使用自有工具、最终转向托管 agent 服务的战略步骤
- 猜测玩法是用强化学习训练模型，让它用自己最熟悉、最高效的工具解决问题，直到默认调用托管 agent 服务；并惊讶这不是更早出现。（少数人） > 想象中的打法是用强化学习让模型用你自己的工具解决问题，直到它默认转向托管 agent 之类的服务。（@hahahacorn）
有价值的补充
- 有人把发布说明讽刺为“直接把宜家安装说明书第 20–40 页塞给你，还指望你兴奋”，吐槽文档只有术语、没有一句话说明价值。（@bluegatty）
- 开发者 kristopolous 因找不到“像 cURL、awk、sed 那样对 LLM 友好的 Unix 原生工具”而自建了 llcat：它无状态、显式、低级、可组合，不用配置文件，而用内置 jq 语法和行号索引文件，调用可存成 JSON 复用。（@kristopolous）
- llcat 把对话也当成 JSON 文件，且没有隐藏状态，因此能像普通 Unix 管道一样编排：可把调用保存后用 shell 循环套用到一批文件，也能靠显式传入 key 和 URL 在同一套脚本里切换不同模型供应商，输入输出和上下文都只是 JSON，从而获得可脚本化的确定性。（@kristopolous）