在 Codex Desktop 中安装和使用 TypeSafe 与 Jev

如果你已经拿到 TypeSafe API Key，在 Codex Desktop 里看到 /skills 中出现 typesafe-ai，接下来最容易踩坑的地方其实很明确。Skill 安装成功，并不等于 Codex 已经开始调用 Jev。

本文只整理这次实际讨论中涉及的安装、配置和使用方式，重点解决三个问题。typesafe-ai 到底装了什么，API Key 放在哪里，以及 Codex 使用过程中什么时候会真正调用 Jev。

Codex Desktop 能不能直接运行 `npx skills add`

如果你使用的是普通 ChatGPT Desktop，聊天窗口本身不能直接执行终端命令。npx skills add 需要在系统终端或者能够执行命令的开发环境中运行。

Codex Desktop 则可以配合项目终端使用这类命令。进入项目目录后执行。

npx skills add typesafe-ai/skills --skill typesafe-ai

安装完成后，可以使用下面的命令检查 Skills。

npx skills list

如果在 Codex Desktop 中执行 /skills 后已经能够看到 typesafe-ai，说明当前这一步已经完成。

全局安装可以使用。

npx skills add typesafe-ai/skills --skill typesafe-ai -g

项目级安装和全局安装的区别在于 Skill 的作用范围。当前项目需要使用时，可以采用项目级安装。希望多个项目都能使用时，可以考虑全局安装。

`/skills` 里出现 `typesafe-ai` 之后发生了什么

看到 typesafe-ai 只能说明 Codex 已经识别这个 Skill。

它不会因为安装完成就自动弹出 API Key 输入框，也不会因为你在 Codex 里输入普通问题，就自动把问题发送给 Jev。

typesafe-ai 更接近开发辅助工具。它可以帮助 Codex 按 TypeSafe 的方式设计 workflow、生成 SDK 调用代码，以及根据 Skill 中的说明使用 TypeSafe 和 Jev。

因此，这两个状态需要分开判断。

状态	含义
`/skills` 能看到 `typesafe-ai`	Codex 已经识别 Skill
已经获得 TypeSafe API Key	已经具备调用 TypeSafe API 所需的认证信息
设置 `TYPESAFE_API_KEY`	Codex 运行的程序可以读取 API Key
实际运行 SDK 调用	才能验证 Jev 是否真正被调用

这个区别非常重要。只检查 /skills，无法证明 API 调用已经成功。

TypeSafe API Key 应该怎么配置

如果你已经获得 TypeSafe API Key，下一步需要让运行 TypeSafe SDK 的环境能够读取 TYPESAFE_API_KEY。

macOS

在终端执行。

export TYPESAFE_API_KEY="你的API_KEY"

可以检查环境变量是否已经存在。

echo $TYPESAFE_API_KEY

如果希望以后打开终端时自动存在，可以写入 zsh 配置。

echo 'export TYPESAFE_API_KEY="你的API_KEY"' >> ~/.zshrc
source ~/.zshrc

配置完成后重新启动 Codex Desktop。

Windows

PowerShell 中可以执行。

$env:TYPESAFE_API_KEY="你的API_KEY"

检查。

echo $env:TYPESAFE_API_KEY

如果希望永久保存，可以设置用户级环境变量。

[Environment]::SetEnvironmentVariable(
  "TYPESAFE_API_KEY",
  "你的API_KEY",
  "User"
)

完成后重新启动 Codex Desktop，让新的环境变量进入 Codex 的运行环境。

API Key 不要直接发到聊天中，也不要提交到 Git 仓库。

为什么安装 Skill 时没有让我填写 API Key

这是正常的。

执行下面的命令。

npx skills add typesafe-ai/skills --skill typesafe-ai

完成的是 Skill 安装。

API Key 属于运行 TypeSafe API 时使用的认证配置。两件事发生在不同阶段，所以安装 Skill 时没有输入框并不代表安装失败。

可以把整个过程理解成下面这条路径。

Codex Desktop
    ↓
typesafe-ai Skill
    ↓
生成或使用 TypeSafe SDK 代码
    ↓
TYPESAFE_API_KEY
    ↓
TypeSafe API
    ↓
Jev

只有真正执行到 API 调用，最后几步才会发生。

Codex 使用 `typesafe-ai` 时会自动调用 Jev 吗

不会因为 Skill 存在就自动调用 Jev。

例如你在 Codex 中提出一个判断需求，Codex 可以使用 typesafe-ai Skill 帮你生成 TypeSafe/Jev 的实现代码。

如果只是让它生成代码，流程停留在代码生成阶段。

例如可以让 Codex 处理这样的任务。

$typesafe-ai

请使用 TypeSafe 的 Jev API 创建一个最简单的 TypeScript 示例。

要求：
1. 使用 @typesafe-ai/sdk
2. 从环境变量 TYPESAFE_API_KEY 读取 API Key
3. 使用 Jev
4. 发起一个简单的 typed judgment
5. 实际运行这个示例，确认 API Key 和 API 调用正常
6. 如果调用失败，请告诉我具体的 HTTP 错误，不要猜测

这里最关键的一句是“实际运行这个示例”。

如果只要求“生成代码”，Codex 可以完成代码生成，却没有验证 Jev API 是否真的被调用。

如果要求实际运行，才可以进一步验证。

Codex
  ↓
TypeSafe SDK
  ↓
TYPESAFE_API_KEY
  ↓
TypeSafe API
  ↓
Jev

怎么确认 Jev 真的被调用了

最直接的方法是让 Codex 完成一个最小可运行示例，而不是只让它解释用法。

可以在 Codex Desktop 中直接发送。

$typesafe-ai

请创建一个最小的 TypeScript Jev 示例。

要求：
1. 使用 @typesafe-ai/sdk
2. API Key 从 TYPESAFE_API_KEY 环境变量读取
3. 使用 Jev
4. 创建一个简单的判断任务
5. 实际执行程序
6. 如果 API 调用失败，输出实际错误信息
7. 如果成功，告诉我实际返回了什么

这个测试可以把几个问题一次区分开。

如果 Skill 不存在，Codex 无法正常加载 typesafe-ai。

如果环境变量不存在，程序无法正常读取 API Key。

如果 API Key 或 API 请求存在问题，实际运行时会出现对应的 API 错误。

如果程序成功完成调用，才能确认从 Codex 到 TypeSafe API 的实际调用链已经跑通。

`typesafe-ai` 和 Jev Skill 要怎么区分

这次配置过程中最容易把两个概念混在一起。

typesafe-ai 适合用于 TypeSafe 集成开发。它可以让 Codex 按照 TypeSafe 的方式编写代码和设计判断流程。

Jev 则是实际执行判断的部分。

因此，如果你的目标是让 Codex 帮你写一个应用，并在应用代码中使用 TypeSafe/Jev，typesafe-ai Skill 就是当前安装的对象。

如果你的目标是让 Codex 在工作过程中直接执行 Jev 判断，那么还需要使用能够直接执行 Jev 的工具或 Skill。仅仅看到 $typesafe-ai 并不能证明每次任务都会自动请求 Jev。

可以用下面的方式理解。

你的需求	当前 `typesafe-ai` Skill
查 TypeSafe 使用方式	可以
帮 Codex 编写 TypeSafe 集成	可以
生成 Jev 调用代码	可以
安装后自动执行每一次 Jev 判断	不会
API Key 自动弹窗配置	不会
实际调用 Jev API	需要执行相应代码或调用工具

在 Codex Desktop 中建议采用的测试顺序

如果你现在已经满足三个条件，也就是已经安装 Codex Desktop、/skills 能看到 typesafe-ai、已经拿到 TypeSafe API Key，那么不要继续重复安装 Skill。

按照下面的顺序测试即可。

第一步检查 Skill

在 Codex 中执行。

/skills

确认存在。

typesafe-ai

第二步配置 API Key

macOS。

export TYPESAFE_API_KEY="你的API_KEY"

Windows PowerShell。

$env:TYPESAFE_API_KEY="你的API_KEY"

第三步重新启动 Codex Desktop

如果采用了永久环境变量配置，重启 Codex Desktop，确保新的环境变量进入 Codex 的运行环境。

第四步要求 Codex 实际运行

$typesafe-ai

创建一个最小的 TypeScript Jev 调用示例，并实际运行它。

使用 TYPESAFE_API_KEY 作为认证信息。
不要只生成代码，请实际执行并告诉我调用结果。

第五步根据结果定位问题

如果成功，说明 Skill、环境变量和 API 调用基本已经连通。

如果失败，把 Codex 输出的完整错误信息留下来再判断。尤其不要只看“调用失败”几个字，需要看具体的错误内容。

操作清单

☾ [ ] 安装 Codex Desktop
☾ [ ] 在项目中安装 typesafe-ai
☾ [ ] 用 /skills 确认能看到 typesafe-ai
☾ [ ] 准备 TypeSafe API Key
☾ [ ] 配置 TYPESAFE_API_KEY
☾ [ ] 重启 Codex Desktop
☾ [ ] 用 $typesafe-ai 要求生成 Jev 示例
☾ [ ] 要求 Codex 实际运行，而不是只生成代码
☾ [ ] 根据实际运行结果确认 Jev API 是否成功调用

FAQ

1. `/skills` 能看到 `typesafe-ai`，是不是已经配置成功？

只能确认 Skill 已经被 Codex 识别。API Key 和 Jev API 是否可用，还需要实际运行调用进行验证。

2. 安装 `typesafe-ai` 时为什么没有输入 API Key？

因为 Skill 安装和 API 认证配置是两个步骤。API Key 需要在运行 TypeSafe API 时提供。

3. `$typesafe-ai` 会自动调用 Jev 吗？

不会仅因为 Skill 被安装就自动调用。需要执行 TypeSafe SDK 或相应的 Jev 调用。

4. `TYPESAFE_API_KEY` 应该放在哪里？

可以作为环境变量配置。macOS 和 Windows 的设置方式不同，配置后需要确保 Codex 能够继承这个环境变量。

5. 只让 Codex 生成 TypeScript 代码，能证明 Jev 调用成功吗？

不能。生成代码只能证明 Codex 生成了相应实现。需要实际运行代码才能验证 API 调用。

6. API Key 应该直接写进 TypeScript 文件吗？

当前这套配置使用 TYPESAFE_API_KEY 环境变量读取 Key，因此没有必要把真实 Key 写进源代码。

7. 我已经有 `typesafe-ai`，还需要 Jev 吗？

取决于用途。如果目的是开发 TypeSafe/Jev 集成，当前 Skill 可以用于生成相关代码。如果希望 Codex 在任务执行过程中直接运行 Jev 判断，则需要相应的直接执行方式。

8. 怎么判断整个流程已经跑通？

最可靠的方法是让 Codex 使用 typesafe-ai 创建一个最小 Jev 示例，并要求它实际运行。只有程序完成实际 API 调用，才能验证从 Codex 到 TypeSafe API 再到 Jev 的调用链。

Codex Desktop集成TypeSafe指南：三步安装Jev技能，别再卡在API Key配置