本地运行 Agents

用这个页面在你的电脑上运行提取出来的 Agents 项目。ReAct 循环、函数调用循环和最终界面都使用相同的 Vite 设置，只是在不同的地方显示结果。在开始你要完成的里程碑之前，更新 OpenAI 密钥查询和已弃用的模型 ID。

开始前的准备

安装受支持的 Node.js LTS 版本。推荐 Node 24，它内置了 npm；导出项目是一个 Vite 项目，所以 Node 和 npm 就足够了所有的工具需求。

你还需要一个有账单和模型访问权限已启用的 OpenAI API 密钥。模型访问权限在 OpenAI 仪表盘中按项目设置：你的密钥所属的项目必须允许访问下面配置的模型。密钥本身会在后面的步骤中放入 .env 文件。

Juno开始前的准备 安装 Node.js LTS 版本，npm 会一起装上。你还需要一个来自能够进行付费模型请求的账户的 OpenAI API 密钥。在开始前把两样东西都准备好，可以避免设置过程中的手忙脚乱。

Juno开始前的准备 导出项目是 Vite 项目，所以 Node LTS 加上 npm 就是完整的工具链。你的 OpenAI 密钥会在后面几步放进 .env，而模型访问权限指的是在 OpenAI 仪表盘中该密钥所在项目的允许模型列表。现在就检查一下这个列表，可以避免后面最让人困惑的错误。

Juno开始前的准备 Vite 可以在完全没有密钥的情况下启动这些项目，这使得密钥配置错误成为本页面最无声的失败。直到 agent 循环发起第一次模型请求并收到认证或配额错误时，才会有任何提示。在责怪代码之前，先确认账单和模型访问权限；我就是从浪费的一个上午得出这个经验的。

打开并安装项目

在包含 package.json 的提取文件夹中打开终端，然后安装依赖包：

$ cd path-to-your-downloaded-project
$ npm install

Juno打开并安装项目 打开包含 package.json 的提取文件夹并在那里运行 npm install。本页面上后面的每条命令都在同一个文件夹中执行。把一个终端停在那个文件夹里，可以避免我在初期经常经历的"我在哪儿"的困惑。

Juno打开并安装项目 三个里程碑都共享 npm 和 Vite 的设置，所以无论你提取的是哪一个，这个安装步骤都是一样的。在 package.json 旁边安装，然后在下一个章节进行两处代码改造。同一个文件夹，每条命令。

Juno打开并安装项目 这些导出文件没有包含锁文件，即 package-lock.json，所以 npm install 会在你的机器上重新解析 OpenAI SDK 和 Vite。版本漂移是可能的但很少成为问题所在。后面出了什么问题，在开始重新整理包之前，先怀疑源代码改造。

更新密钥和模型

在 index.js 中，把：

apiKey: process.env.OPENAI_API_KEY,

改为：

apiKey: import.meta.env.VITE_OPENAI_API_KEY,

Vite 通过 import.meta.env 读取环境变量；同样的改造也出现在本地运行 Embeddings 和向量数据库中，那篇文档改造了一个类似的课程导出。

课程快照使用已弃用的模型 ID，比如 gpt-3.5-turbo、gpt-3.5-turbo-1106 和 gpt-4-1106-preview。对这些课程示例，把提取的 index.js 中的模型值替换为 gpt-4o-mini：

model: "gpt-4o-mini",

在 package.json 旁边创建 .env：

VITE_OPENAI_API_KEY=your-openai-api-key

在同一个文件夹中创建 .gitignore：

.env
node_modules/

.gitignore 会让你的密钥不会被提交到任何从这个文件夹创建的仓库；忽略文件和良好习惯解释了为什么这很重要。

这个学习设置会暴露密钥

OpenAI SDK 有意在浏览器中运行，Vite 会把密钥放进前端 bundle。只使用临时的、权限受限的密钥。不要部署或分享这个版本。生产 agent 需要一个后端。

Juno更新密钥和模型 在 index.js 中替换旧的密钥查询和模型名称，把你的临时密钥放在 .env 中，并把那个文件从 Git 中排除。这个学习版本有意向浏览器暴露密钥，所以用一个可以随意丢弃的密钥。把它当作酒店房卡而不是你家的钥匙。

Juno更新密钥和模型 Vite 只暴露以 VITE_ 开头的变量，所以源代码中的名称和 .env 中的名称必须完全匹配。仔细检查整个下载内容中是否有已弃用的模型 ID，因为不同的里程碑包含不同的快照。漏掉一个 ID，一个里程碑可能工作正常而另一个就会失败。

Juno更新密钥和模型 生产环境的解决方案在架构层面：在后端创建 OpenAI 客户端，让浏览器调用那个后端，这样密钥永远不会离开服务器。这里的 Vite 替换是学习模式的快捷方式，不是要用于生产的模式。在发布后才改造后端比一开始就构建好要糟糕得多；两种方式我都经历过。

运行项目

$ npm start

打开 Vite 打印的确切 Local URL。对于仅有控制台的里程碑，打开浏览器的开发工具并选择控制台。ReAct 和函数循环会在那里打印它们的进度和响应。在 UI 里程碑中，发送一条消息并在页面上查找响应。按 Ctrl+C 停止 Vite。

Juno运行项目 运行 npm start 并打开 Vite 打印的确切本地 URL。对于早期的里程碑，操作发生在浏览器的控制台中，所以看起来空白的页面可能正在努力工作。完成后按 Ctrl+C 停止。

Juno运行项目 Vite 会选择端口并打印确切的地址，所以使用它打印的地址而不是记忆中的 URL。在仅有控制台的里程碑中，空白页面是预期的表面；在认为这是启动失败之前先检查开发者控制台中的循环输出。只有 UI 里程碑会在页面本身上给出响应。

Juno运行项目 Vite 启动只证明了编辑的项目可以编译，仅此而已；还没有联系 OpenAI。在调用设置完成前，要进行一次真实的交互，要么在 DevTools 中看到循环输出，要么通过最终界面发送一条消息。"编译成功就是能工作"的结论我多年前就放弃了。

故障排除

process is not defined： 在 index.js 中搜索剩余的 process.env.OPENAI_API_KEY 并把它替换为上面的 Vite 形式。

已弃用的模型不可用： 确认每个 model 字段都使用了对你的 OpenAI 项目可用的当前模型。下载的里程碑可能包含不同的已弃用 ID。

页面看起来是空的： 早期的里程碑在开发者控制台中报告进度而不是在页面上。如果你想要一个可见的聊天界面，使用最后的 UI 课程。

认证或配额错误： 检查 .env 是否在 package.json 旁边，重启 Vite，并在 OpenAI 账户中确认账单和密钥访问权限。

Juno故障排除 让症状指导你：process is not defined 意味着密钥查询仍需改造，空白页面通常意味着输出在控制台中，认证错误指向密钥或账户。每个都有一个单一的修复。冷静地按顺序一次处理一个。

Juno故障排除 按顺序检查：源代码读取 Vite 变量、.env 使用匹配的名称、每个模型 ID 都是当前的、你在监看里程碑的真正输出位置。这个顺序反映了请求的构建方式，所以第一条破裂的链条就是你的问题所在。修复它并重新运行，不要碰任何其他东西。

Juno故障排除 无声的 agent 有四个嫌疑人：密钥从未进入 bundle、模型 ID 不再存在、OpenAI 拒绝了账户，或 UI 丢弃了返回的消息。按这个顺序质问它们，因为每个早期的失败都能伪装成后期的。顺序搞错了会把五分钟的修复变成一个晚上；相信我。