在 Codex 中使用 Jev：注册、配置 API Key 与首次调用完整教程

Jev 是 TypeSafe AI 推出的 System One 模型，主要用途不是生成长文本，而是根据给定状态完成分类、评分和是非判断，并返回可直接供程序使用的结构化结果。对于使用 Codex 开发项目的用户，官方提供了 Agent Skill，可以让 Codex 快速理解 Jev 的问题类型、接口结构和最佳实践。

下面从账号注册开始，完整介绍如何在 Codex 中配置并测试 Jev。官网界面可能随版本更新而略有变化，但核心流程保持一致。

一、Jev 是什么，适合解决哪些问题

Jev 是 TypeSafe AI 的旗舰模型。与普通大语言模型侧重生成自然语言不同，Jev 面向程序化决策：输入一段状态和若干问题，返回固定类型的答案与概率。

官方目前提供三类问题：

• Choice：从多个候选项中选择一个结果，并返回概率分布与置信度。
• Score：按照预先定义的等级标准评分。
• Noul：回答一个是非问题，返回“是”的概率，取值范围为 0 到 1。

这些问题可在一次请求中并行执行，适合工单分流、风险判断、内容分类、优先级评估和智能路由等场景。

二、申请并注册 TypeSafe AI 账号

1. 打开 Jev 控制台

访问 TypeSafe AI 控制台：https://console.typesafe.ai/home。未登录时，页面会显示账号登录或注册入口。

2. 选择注册方式

控制台目前支持以下方式：

• 使用 Google 账号继续；
• 输入邮箱继续；
• 选择通过邮箱验证码登录。

首次使用时，按页面提示完成邮箱验证并接受服务条款与隐私政策。若账号处于候补或受限开放阶段，则需要等待平台开通访问权限。注册成功后即可进入控制台首页。

三、把 Jev Agent Skill 接入 Codex

1. 复制 Agent Prompt

进入控制台首页后，在页面右侧找到 Copy Agent Prompt，点击后复制官方准备的提示词。该提示词的作用是指导 Codex 安装并使用 TypeSafe Agent Skill。

如果页面按钮位置发生变化，也可以打开官方 Agent Skill 文档：https://docs.typesafe.ai/agent-skill。官方为 Codex 等智能编程环境提供的安装命令是：

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

执行时根据交互提示选择 Codex。默认会安装到当前项目；如需全局安装，可根据官方说明添加 -g。同一个项目只选择一种安装方式，避免出现重复 Skill。

2. 在 Codex 中发送提示词

打开 Codex 并进入要使用 Jev 的项目，将刚才复制的 Agent Prompt 直接发送给 Codex。Codex 会按照提示读取或安装 TypeSafe Skill，并获得 Jev 的三种问题类型、常见架构模式及 API 使用规范。

安装完成后，可以补充一句：

请在这个项目中使用 TypeSafe Skill，并先说明 Jev 适合解决哪些问题。

如果 Codex 没有加载 Skill，应先确认 Skill 是否安装到了当前项目或全局目录，然后重启 Codex 会话再试。

四、创建并安全保存 Jev API Key

1. 创建 API Key

在控制台左侧进入 API keys，也可以直接访问：https://console.typesafe.ai/keys。点击创建按钮，按提示生成一个新的 Key。

API Key 通常只在创建时完整显示一次，因此应立即复制并妥善保存。不要把密钥发送到聊天群、截图公开，也不要提交到 Git 仓库。

2. 将 Key 保存为本地文件

为了按 Codex 文件上下文的方式配置，可以新建一个仅存于本机的文本文件，例如：

TYPESAFE_API_KEY=你的实际密钥

建议将文件命名为 .env.local 或 jev-key.txt，并把它加入 .gitignore。在 macOS 或 Linux 中，还可以限制文件权限：

chmod 600 jev-key.txt

更推荐的长期方式是把 Key 写入安全的环境变量或密钥管理服务，而不是长期保留普通明文文件。

3. 把密钥文件交给 Codex

在 Codex 中选择刚创建的文件，并明确说明：

这是 Jev 的 API 密钥文件。只在本地测试中读取，不要输出密钥，不要提交到 Git，也不要写入日志。

这一步既让 Codex 知道文件用途，也明确了保密边界。官方 Python 与 JavaScript SDK 默认会读取 TYPESAFE_API_KEY 环境变量，因此 Codex 可以先从文件安全加载变量，再执行测试。

五、在 Codex 中测试 Jev API

完成密钥配置后，向 Codex 发送：

测试一下调用 Jev API 是否成功。请使用 TypeSafe Skill，读取本地密钥但不要显示它；执行一个最小 Noul 测试，并返回 HTTP 状态、模型名称和结构化答案。

官方 HTTP 接口为：

POST https://api.typesafe.ai/v1/systemone

请求需要使用 Bearer Token 鉴权，并发送 JSON。一个最小测试可以判断一段文本是否表达紧迫性：

curl -X POST https://api.typesafe.ai/v1/systemone \
  -H "Authorization: Bearer $TYPESAFE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "state": "这个支付问题已经持续三天，请尽快处理。",
    "model": "jev-latest",
    "questions": {
      "is_urgent": {
        "type": "noul",
        "instructions": "这段信息是否表达了紧迫性？"
      }
    }
  }'

调用成功后，响应会包含实际使用的模型、answers 结构化答案以及 token 用量。Noul 结果中的 noul 是 0 到 1 之间的概率，不应把它简单理解为普通聊天模型生成的一句“是”或“否”。

常见失败原因

• 401 或 403：密钥无效、未正确加载，或账号权限尚未开通；
• 找不到环境变量：确认变量名必须为 TYPESAFE_API_KEY；
• 请求格式错误：检查 state、model 和 questions 是否齐全；
• Codex 没有使用 Skill：在提示词中明确要求“使用 TypeSafe Skill”；
• 密钥泄露到输出：立即在控制台撤销旧 Key，并生成新 Key。

六、API 成功后如何让 Codex 返回 Jev 结果

验证成功后，可以让 Codex根据项目需求设计真实问题。例如：

使用 TypeSafe Skill 调用 Jev。把下面的客户反馈作为 state，同时判断：
1. 用 Choice 判断应分配给 billing、technical 还是 sales；
2. 用 Score 按“普通、较急、紧急、严重”评估优先级；
3. 用 Noul 判断是否需要立即转人工。
请返回 Jev 的原始结构化结果，并解释代码应如何根据概率与置信度进行分支处理。

编写提示词的关键原则

1. 一次只判断一个明确问题：复杂目标应拆成多个原子问题。
2. 把规则写清楚：Choice 的每个候选项应提供清晰边界。
3. 不要只看最终标签：需要自动执行重要操作时，应结合概率和置信度设置阈值。
4. 一次请求合并多个问题：多个问题可共享同一个 state，减少重复请求。
5. 生产环境固定模型版本：验证阶段可使用 jev-latest，对稳定性要求较高时应评估固定版本。

七、完整操作清单

从零开始在 Codex 中使用 Jev，可以按以下顺序执行：

1. 登录 console.typesafe.ai，使用 Google 或邮箱完成注册；
2. 在首页点击 Copy Agent Prompt；
3. 将提示词发送给 Codex，安装并加载 TypeSafe Agent Skill；
4. 在控制台左侧进入 API keys，创建新的 Key；
5. 把 Key 保存到本地私密文件，并加入 .gitignore；
6. 在 Codex 中选择该文件，声明它是 Jev 密钥且禁止输出；
7. 发送“测试一下调用 Jev API 是否成功”；
8. 确认响应包含模型名称、结构化答案和用量信息；
9. 使用 Choice、Score、Noul 组合编写实际业务判断；
10. 测试结束后检查密钥是否进入代码、日志或 Git 历史。

总结

Codex 与 Jev 的组合重点不在于让 Jev 替代普通聊天模型，而是让 Codex 使用一个稳定、结构化的判断接口。正确流程是：先通过官方 Agent Prompt 安装 TypeSafe Skill，再创建并安全配置 API Key，最后用最小 Noul 请求验证连接。测试成功后，再逐步加入 Choice 与 Score，并在代码中根据概率和置信度实现可靠的自动化分支。