AI工具

发布日期: 2026-06-23

文章字数: 4.3k

阅读时长: 16 分

AI入门第一课：装App和填API Key封面图

AI入门第一课：装App和填API Key

我以前也觉得，AI 课程有什么好教的？不会就问 AI，问两轮不就行了。

后来发现不是这样。

真正挡住普通同事的，往往不是 Prompt Engineering，也不是 Agent 架构，而是第一步：

API Key 填哪？
Base URL 是什么？
Mac 为什么打不开这个 App？
官网写的命令为什么我一粘贴就报错？
Chat Completions、Responses、Images 这些接口有什么区别？

这就很有意思了。老板说要推广 AI，听起来像战略升级；落到工位上，第一批问题通常是“这个 key 复制到哪里”。

所以 AI 培训确实是蓝海。但最好别一上来讲宏大叙事，先把门槛最低、卡人最多的两件事讲透：Mac 怎么装非 App Store 应用，API Key 怎么配。

为什么这两个问题值得单独写

因为它们不是技术细节，而是入口摩擦。

很多人不是不想用 AI，是卡在“我还没真正用起来”。如果一个同事第一天下载不了客户端，第二天 API 401，第三天不知道模型名填什么，他就会自然得出一个结论：AI 很麻烦，还是算了。

企业内训尤其明显。你给大家讲“AI 会重塑工作流”，大家点头；你让大家自己装 Codex、Claude Code、Cherry Studio、Cursor 插件，现场就开始分层：

flowchart TD
    A[老板说全员用 AI] --> B[同事开始安装工具]
    B --> C{第一步是否顺利}
    C -->|顺利| D[开始尝试真实任务]
    C -->|失败| E[回微信问懂的人]
    E --> F[培训变成售后群]

这篇文章不讲“AI 时代如何自我革命”。先讲两个更值钱的问题：

Mac 怎么安装 App Store 没有的 AI 工具；
API Key、Base URL、模型名、接口格式到底怎么填。

第一件事：Mac 下载 App Store 没有的应用

Mac 不是只能从 App Store 安装应用。开发者工具、AI 客户端、开源工具，大量都来自官网、GitHub Release、npm、Homebrew 或独立下载页。

常见安装包有几种：

.dmg：打开后把 App 拖进 Applications；
.pkg：双击安装，类似传统安装向导；
.zip：解压后得到 .app，再拖进 Applications；
命令行工具：用 npm、brew、curl、pipx 等安装。

新手最容易被 macOS 的安全提示吓住：

“无法打开，因为 Apple 无法检查其是否包含恶意软件。”
“无法打开，因为它来自身份不明的开发者。”

这个提示不是说 App 一定有毒，而是说：Apple 没有完成开发者签名、公证或来源校验。你可以打开，但要自己对来源负责。

Apple 官方也提醒过：绕过安全设置打开未知开发者 App，是 Mac 感染恶意软件的常见方式之一。我的建议很简单：

能从官网、GitHub 官方仓库、Homebrew 官方源下载，就别从网盘合集下载；
能右键单独允许某个 App，就别长期关闭 Gatekeeper；
不知道来源靠不靠谱，就先别装。

安全打开方式一：右键打开

对 .dmg、.pkg 或 .app，优先试这个：

在 Finder 里找到文件；
按住 Control 或右键点击；
选择“打开”；
在弹窗里再次确认“打开”。

这比双击更容易触发“我知道风险，仍然打开”的选项。

安全打开方式二：系统设置里允许

如果右键打开仍然失败：

macOS Ventura / Sonoma / Sequoia：打开“系统设置” → “隐私与安全性”，在页面底部找到被拦截的 App，点击“仍要打开”；
macOS Monterey 及更早版本：打开“系统偏好设置” → “安全性与隐私” → “通用”，点击“仍要打开”。

打开一次后，macOS 会把这个 App 记为例外，后面就能正常双击打开。

不推荐：长期关闭 Gatekeeper

网上经常有人给这条命令：

sudo spctl --master-disable

它会把“任何来源”选项打开。不是不能用，但不适合作为默认教学。尤其是公司电脑、主力电脑、装了钱包或重要账号的电脑，不建议长期这么开。

如果你临时开过，记得恢复：

sudo spctl --master-enable

培训时我更建议这么讲：先教右键打开，再教隐私与安全性里单独放行，最后才提全局关闭，而且要明确说“不建议长期使用”。

以 Codex App 为例：官网安装才是默认路径

你提醒得对：如果讲“官网安装 App”，Codex 的典型例子应该是 Codex App，而不是 Codex CLI。

OpenAI 官方的 Codex App 页面写得很清楚：Codex App 是一个桌面端工作台，用来并行处理 Codex 线程，内置 worktree、自动化和 Git 能力。它目前提供 macOS 和 Windows 版本，下载入口包括：

macOS Apple Silicon；
macOS Intel；
Windows；
Linux 目前是“Get notified”，不是正式下载。

官网安装路径应该这样讲：

打开 OpenAI Developers 的 Codex App 页面：
https://developers.openai.com/codex/app
根据电脑选择 macOS Apple Silicon、macOS Intel 或 Windows；
下载后按系统提示安装；
打开 Codex，用 ChatGPT 账号或 OpenAI API Key 登录；
选择项目文件夹；
确认选择 Local，让 Codex 在本机项目上工作；
发第一条消息，比如“Tell me about this project”。

这里的新手价值是：让同事知道“App 安装”优先看官网，不要去搜索引擎随便点下载站。尤其是 AI 工具会接触代码仓库、API Key、浏览器登录态，更不能从来路不明的网盘包、破解版、搬运站安装。

Codex App 也不是一个普通聊天窗口。它更像“本地项目控制台”：可以并行开多个任务线程，可以用 Git worktree 隔离改动，可以看 diff、stage、commit、push，也可以配合 in-app browser、Chrome extension、automations、skills、plugins 等能力。

所以培训时我会把它讲成两层：

想装桌面客户端：走 Codex App 官网下载：https://developers.openai.com/codex/app
想配置命令行和 OpenAI 兼容 API：再讲 Codex CLI、Base URL、API Key。

命令行工具另讲：Codex CLI 不是桌面 App

Codex CLI 仍然值得讲，但它不应该冒充“官网安装 App”的例子。它适合解释另一类问题：有些 AI 工具装完不会出现在 Launchpad，因为它本来就是命令行工具。

安装前先要有 Node.js。装好后，用 npm 安装 Codex CLI：

# Windows
npm install -g @openai/codex@latest

# macOS / Linux，遇到权限问题再加 sudo
sudo npm install -g @openai/codex@latest

验证是否安装成功：

codex --version

能输出版本号，说明命令已经装好了。如果提示 command not found，通常是 npm 全局目录没有加入 PATH，或者终端没重启。

这类问题看起来很基础，但现场培训时非常常见。因为很多人以为“安装软件”一定会出现一个图标，结果命令行工具装完后什么都看不见，于是以为失败了。

第二件事：API Key 到底是什么

API Key 可以理解为“给工具用的密码”。

你在网页里登录 ChatGPT，是账号密码或扫码登录；你让 Codex、Claude Code、Cherry Studio、Cursor、自己的脚本去调用模型，就需要一个 API Key。工具会把这个 key 放在请求头里，服务端据此判断：

你是谁；
你能不能用这个模型；
这次调用该记到谁账上；
有没有超额度、过期、IP 限制、速率限制。

所以 API Key 的第一原则是：不要发群里，不要写进公开 GitHub，不要截图给不该看的人。

常见请求头长这样：

Authorization: Bearer YOUR_API_KEY

Bearer 后面那串就是 key。很多人第一次配置失败，是因为多复制了空格、少复制了一段、把引号也复制进去了，或者用错了分组的 key。

Base URL 是什么

Base URL 是“请求发到哪里”。

如果你用 OpenAI 官方 API，常见基础地址是：

https://api.openai.com/v1

如果你使用中转或统一接入平台，比如 Tosky AI，图片接口文档里给的是：

https://api.ai.tosky.top/v1

而 Codex CLI 的配置示例里，base_url 写的是：

base_url = "https://api.ai.tosky.top"

这里最容易混：有些工具要你填到 /v1，有些工具自己会拼 /v1，所以只让你填根地址。判断方法很简单：看对应工具文档怎么写，不要自己脑补。

可以这么记：

curl 直接请求接口，通常要写完整路径，比如 /v1/chat/completions、/v1/responses、/v1/images/generations；
工具配置里的 Base URL，可能是根地址，也可能是带 /v1 的地址，按工具文档填；
报 404 时，优先检查 URL 拼错；报 401 时，优先检查 key 和分组。

OpenAI 兼容是什么意思

“OpenAI 兼容”不是说它一定是 OpenAI 官方。它通常表示：这个服务模仿 OpenAI 的接口格式，让原本支持 OpenAI 的工具可以少改配置就接入。

比如很多工具默认认识这些环境变量：

export OPENAI_API_KEY="你的密钥"
export OPENAI_BASE_URL="https://api.ai.tosky.top"

然后工具会按 OpenAI 风格发请求：

文本聊天：/v1/chat/completions；
新一代响应接口：/v1/responses；
图片生成：/v1/images/generations；
图片编辑：/v1/images/edits；
模型列表：/v1/models。

兼容的好处是生态能复用。坏处是每个工具对 Base URL、模型名、接口类型的细节不完全一样，所以配置时要对齐三件事：

flowchart LR
    A[API Key] --> D[一次成功调用]
    B[Base URL] --> D
    C[Model Name] --> D
    E[接口类型
chat / responses / images] --> D

只要其中一个填错，就会失败。

Codex CLI 怎么填 API Key

以 Tosky AI 的 Codex 文档为例，先在控制台创建 API Key，分组选择 OpenAI / Codex。然后配置 Codex。

推荐用配置文件，而不是把 key 长期散落在各种命令里。

先创建配置目录：

# macOS / Linux
mkdir -p ~/.codex

# Windows PowerShell
mkdir "$env:USERPROFILE\.codex"

创建 ~/.codex/config.toml：

model_provider = "OpenAI"
model = "gpt-5.5"
review_model = "gpt-5.5"
model_reasoning_effort = "xhigh"
disable_response_storage = true
network_access = "enabled"
model_context_window = 1000000
model_auto_compact_token_limit = 900000

[model_providers.OpenAI]
name = "OpenAI"
base_url = "https://api.ai.tosky.top"
wire_api = "responses"
requires_openai_auth = true

再创建 ~/.codex/auth.json：

{
  "OPENAI_API_KEY": "YOUR_API_KEY"
}

然后进入任意项目目录，运行：

codex

如果要临时切模型，可以用：

codex --model gpt-5.5

这里有几个关键点：

model 是模型名，不是产品名；
base_url 是服务地址，不是 key；
wire_api = "responses" 表示 Codex 用 Responses API 的协议；
auth.json 里只放密钥，别把真实 key 发给别人看。

常见接口：Chat Completions、Responses、Images

很多新手看到接口名就晕，其实可以按用途分。

Chat Completions：传统聊天接口

老生态最常见，很多 SDK、机器人、后台服务都支持。典型请求：

curl https://api.ai.tosky.top/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "gpt-5.5",
    "messages": [
      {"role": "user", "content": "用一句话解释 API Key 是什么"}
    ]
  }'

它的核心字段是 messages，里面按角色组织对话。

Responses：新一代响应接口

Codex 这类新工具更常用 Responses API。它比传统 chat 接口更适合工具调用、多模态、复杂输出。典型请求可以这样理解：

curl https://api.ai.tosky.top/v1/responses \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "gpt-5.5",
    "input": "写一个 Python 函数，判断字符串是否为回文"
  }'

如果你只是用 Codex CLI，不需要手写这个请求；但你要知道 wire_api = "responses" 不是随便写的，它决定工具按哪种协议和后端说话。

Models：先查能用哪些模型

不确定模型名时，先查模型列表：

curl https://api.ai.tosky.top/v1/models \
  -H "Authorization: Bearer YOUR_API_KEY"

拿到返回后，看里面的 id。工具里的 model 字段通常就填这个 id。

很多 404 或“model not found”，其实不是服务挂了，而是模型名填错、key 分组不支持这个模型，或者你把展示名当成了模型 ID。

Images：文生图和以图改图

Tosky AI 的 GPT-Image 文档给的是 OpenAI 兼容图片接口。文生图：

curl 'https://api.ai.tosky.top/v1/images/generations' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -d '{
    "model": "gpt-image-2",
    "prompt": "一张中文科技博客封面，主题是 API Key 配置入门",
    "n": 1,
    "size": "1254x1254"
  }'

返回里的 data[0].b64_json 是 base64 编码的 PNG。保存成图片可以这样做：

curl 'https://api.ai.tosky.top/v1/images/generations' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -d '{
    "model": "gpt-image-2",
    "prompt": "一只穿宇航服的猫漂浮在太空中",
    "n": 1,
    "size": "1254x1254"
  }' \
| python3 -c 'import sys,json,base64; data=json.load(sys.stdin); open("output.png","wb").write(base64.b64decode(data["data"][0]["b64_json"]))'

以图改图：

curl 'https://api.ai.tosky.top/v1/images/edits' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -F 'model=gpt-image-2' \
  -F 'prompt=把背景改成日落海滩，保留主体人物' \
  -F 'image=@/path/to/your/image.png' \
  -F 'size=1254x1254'

这里要注意一个现实问题：有些文档还写着旧尺寸，比如 1024x1024、1792x1024、2048x2048。但当前维护通知显示，default 分组的 gpt-image-2 已固定到 1.5K 档，quality 参数无效。

目前可以按比例理解为：

1:1：1254x1254
2:3：1024x1536
3:2：1536x1024
3:4：1086x1448
4:3：1448x1086
4:5：1122x1402
5:4：1402x1122
16:9：1672x941
9:16：941x1672
21:9：1915x821
9:21：821x1915

如果你非常介意 1.5K 限制，就不要在 default 分组里硬传 4K。应该换支持对应能力的分组或官方原价通道。

出错时先看状态码

新手排障不要一上来重装。先看错误码。

401：身份不对

常见原因：

API Key 复制错了；
key 过期或被删了；
key 分组不对，比如用 Codex 分组 key 调图片接口；
请求头少了 Bearer；
环境变量没生效，工具实际读到的是旧 key。

处理方法：重新复制 key，确认分组，重启终端，再跑一次最小 curl。

404：地址或路径不对

常见原因：

Base URL 多写或少写了 /v1；
把 https://api.ai.tosky.top 和 https://api.ai.tosky.top/v1 用反了；
接口路径写错，比如把 /images/generations 写成 /image/generation。

处理方法：回到工具对应文档，照抄地址，不要混用不同工具的写法。

model not found：模型名或权限不对

先用 /v1/models 查模型列表，再填返回里的模型 id。如果列表里没有，可能是当前 key 分组不支持。

command not found：工具没装好或 PATH 不对

如果 codex --version 找不到命令，检查：

npm bin -g

然后确认这个目录在 PATH 里。也可以关闭终端重新打开，再试一次。

企业内训怎么讲才有效

如果我要给公司同事做一场入门培训，我不会第一节课讲 Prompt 模板。我会这样安排：

sequenceDiagram
    participant T as 培训者
    participant U as 同事
    participant A as AI工具
    participant P as API平台

    T->>U: 先装客户端或 CLI
    U->>A: 运行版本检查
    T->>U: 创建 API Key
    U->>A: 填 Base URL / Key / Model
    A->>P: 发起最小请求
    P-->>A: 返回 hello world
    T->>U: 再讲真实业务场景

顺序不能反。没有跑通最小请求之前，讲再多 Agent 都是空的。

我建议每次内训都留半小时做“环境陪跑”：

所有人打开终端或客户端；
现场安装工具；
现场创建 key；
现场跑一个最小请求；
现场解决 401、PATH、Gatekeeper、Base URL 这些破事。

这半小时看起来很土，但它决定课后大家会不会真的继续用。

一张新手检查表

给同事排查时，可以按这个顺序问：

你装的是 App，还是命令行工具？
如果是 Mac App，来源是不是官网或可信仓库？有没有被 Gatekeeper 拦截？
如果是命令行工具，--version 能不能输出？
API Key 是哪个平台创建的？属于哪个分组？
Base URL 是工具要求的根地址，还是带 /v1 的地址？
模型名是从 /v1/models 里复制的吗？
当前工具用的是 chat.completions、responses，还是 images？
报错是 401、404、model not found，还是 command not found？
终端是否重启过？配置文件路径是不是写对了？
真实 key 有没有泄露到截图、群聊或 GitHub？

这张表比“多问 AI”更有用。因为很多时候，AI 也不知道你本机的 key 填在哪个文件、终端读到的是不是旧环境变量。

结语：AI 课不是教聪明人炫技

AI 培训真正值钱的部分，不是把几个英文概念讲得很高级。

更值钱的是把第一步铺平：让一个普通同事能安全装上工具，能把 API Key 填对，能知道 Base URL、模型名、接口类型分别是什么，能在报错时不慌。

只要第一步通了，后面很多东西他自己会问 AI、会试、会复制、会改。第一步没通，他只会回到微信群里问：“这个 key 到底填哪里？”

从这个角度看，AI 课程确实大有可为。不是因为大家不聪明，而是因为真正的落地，往往死在那些看起来不好意思问的小问题上。

参考资料

Onefly

https://onefly.top/posts/ai-api-key-mac-app-install-guide.html

本博客所有文章除特別声明外，均采用 CC BY 4.0 许可协议。转载请注明来源 Onefly !

Mac AI工具 API Codex

一位华盛顿大学NLP博士的OpenAI求职复盘：57场面试之后

2026-06-24 求职成长

AI求职面经 PhD

GEO：让 AI 主动推荐你

2026-06-23 AI工程

AI搜索 GEO SEO

AI入门第一课：装App和填API Key

AI入门第一课：装App和填API Key

为什么这两个问题值得单独写

第一件事：Mac 下载 App Store 没有的应用

安全打开方式一：右键打开

安全打开方式二：系统设置里允许

不推荐：长期关闭 Gatekeeper

以 Codex App 为例：官网安装才是默认路径

命令行工具另讲：Codex CLI 不是桌面 App

第二件事：API Key 到底是什么

Base URL 是什么

OpenAI 兼容是什么意思

Codex CLI 怎么填 API Key

常见接口：Chat Completions、Responses、Images

Chat Completions：传统聊天接口

Responses：新一代响应接口

Models：先查能用哪些模型

Images：文生图和以图改图

出错时先看状态码

401：身份不对

404：地址或路径不对

model not found：模型名或权限不对

command not found：工具没装好或 PATH 不对

企业内训怎么讲才有效

一张新手检查表

结语：AI 课不是教聪明人炫技

参考资料

你的赏识是我前进的动力