1. 项目概述：让AI编码代理真正“活”起来

你有没有过这种体验？写一个复杂的排序算法，或者调试一段嵌套了五层Promise的异步逻辑，Codex、Claude Code这类AI编码代理能瞬间给出优雅、正确、带注释的解决方案——它像一位经验丰富的老同事，坐在你工位旁，手指在键盘上飞舞。但只要问题稍微跨出代码文件边界，比如“查一下当前AAPL股价”、“把这份JSON数据转成Excel并邮件发给财务”，它立刻就卡住，开始兜圈子，甚至胡编乱造。不是它笨，是它被关在一个叫“项目上下文”的透明玻璃房里，看得见，摸不着。

这个玻璃房，就是传统AI编码代理最大的瓶颈。它能理解你整个Next.js项目的结构，却对窗外真实世界一无所知。而真正的工程效率革命，恰恰发生在玻璃房内外的连接处。本教程要做的，就是亲手砸开这扇玻璃门，用Codex CLI和Model Context Protocol（MCP）为你的AI代理装上“手脚”和“眼睛”——让它能主动调用Alpha Vantage API拉取实时股价，能通过Context7服务器查阅最新版TypeScript文档，甚至能同时指挥两个AI代理，一个算风险，一个改UI，像一支训练有素的特种小队一样并行作战。

这不是一个玩具Demo，而是一套可直接复用于生产环境的工程化方案。我从零开始搭建了一个股票投资组合风险看板，所有核心功能——从计算夏普比率、识别高波动性股票，到最终渲染出带红绿预警的UI卡片——全部由AI代理自主完成。过程中，我踩了至少7个坑：从STDIO服务器超时导致连接失败，到多Agent并发时环境变量污染，再到MCP工具列表过载引发的模型幻觉。这些细节，官方文档不会写，但它们才是决定你项目成败的关键。接下来，我会像带你一起debug一样，把每一个决策背后的“为什么”、每一个参数背后的“怎么算”、每一个报错背后的“怎么修”，掰开揉碎讲清楚。无论你是刚接触Agentic AI的新手，还是正在为CI/CD流水线寻找自动化利器的资深工程师，这篇内容都值得你花45分钟，把它完整地敲进自己的终端里。

2. 核心原理拆解：MCP与Codex CLI如何协同工作

2.1 MCP：为AI代理铺设的“标准高速公路”

在深入操作前，必须先理解MCP（Model Context Protocol）的本质。它不是一个具体的工具，而是一套“交通规则”。想象一下，过去每个AI模型想连接一个外部服务，都得自己造一辆车、铺一条专属小路、再雇一个司机。连接数据库？造一辆DB专用车。调用天气API？再铺一条天气专线。结果就是，你的代码库里堆满了各种定制化的、互不兼容的“小路”，维护成本高得吓人，换一个服务就得重写一套。

MCP干了一件极其聪明的事：它定义了一条所有人都必须遵守的“高速公路”标准。这条高速路只认一种“语言”——JSON-RPC 2.0，并且只允许两种“入口”：一种是本地进程（STDIO），另一种是远程URL（HTTP）。这意味着，无论你开发的是一个股票行情查询工具，还是一个GitHub仓库分析器，只要它遵循MCP协议，它就自动成为所有兼容MCP的AI代理（如Codex、Claude Code）的“通用加油站”。

提示：MCP的“标准化”价值，在于它把“集成复杂度”从O(n²)降到了O(n)。过去，N个模型连接M个工具，需要N×M个定制连接器；现在，只需要N个模型实现一次MCP客户端，M个工具实现一次MCP服务器，一切就自然打通了。

这个协议的底层非常轻量。一个典型的MCP请求，就是一个JSON对象：

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "alphavantage.get_price_history",
  "params": {"symbol": "AAPL"}
}

而响应，也严格遵循JSON-RPC格式：

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "prices": [182.34, 183.12, 181.98, ...],
    "dates": ["2024-05-01", "2024-05-02", "2024-05-03", ...]
  }
}

正是这种极致的简洁，保证了它的可移植性和健壮性。它不关心你用Python、Rust还是Go来实现服务器，也不关心你的前端是React还是Vue，只要消息格式对得上，就能跑起来。

2.2 Codex CLI：一个高度可编程的“AI代理操作系统”

Codex CLI远不止是一个“更聪明的命令行”。把它理解为一个“AI代理操作系统”更为贴切。它的核心设计哲学是：将AI的能力模块化、可配置、可编排。这体现在三个关键层面：

第一，统一的上下文管理。 Codex会自动索引你项目里的所有文件，构建一个语义化的知识图谱。当你问“ PortfolioCard.tsx 里 mockPositions 的数据结构是什么？”，它不需要去grep，而是直接从内存索引中提取，速度极快。这个索引过程是增量式的，你改一个文件，它只更新那一部分，而不是全量重扫。

第二，TUI（文本用户界面）驱动的交互范式。 它没有图形界面，所有操作都通过键盘和文本流完成。这看似复古，实则强大。TUI意味着它可以被脚本完美控制，可以无缝集成到CI/CD流水线中，也可以被另一个AI代理（比如用Python写的Orchestrator）当作一个“黑盒工具”来调用。你在终端里输入 /mcp 看到的工具状态列表，本质上就是这个OS的“任务管理器”。

第三， config.toml ：一切行为的“中央处理器”。 这个配置文件是Codex的灵魂。它不像 .env 文件那样只存环境变量，而是定义了整个AI代理的“人格”和“能力”。你可以在这里精确指定：

• 哪些MCP服务器是启用的（ enabled_tools = ["alphavantage", "context7"] ）
• 哪些是禁用的（ disabled_tools = ["github"] ）
• 每个服务器的启动命令、参数、超时时间
• 甚至AI模型的温度（ temperature = 0.3 ）和最大token数（ max_tokens = 2048 ）

这种基于配置的编程方式，让Codex的定制化成本极低。你想为团队创建一个“前端开发专用Agent”？只需一份 frontend-config.toml ；想为后端创建一个“API安全审计Agent”？再配一份 backend-config.toml 。切换成本就是一行 codex --config frontend-config.toml 。

2.3 Codex与MCP的深度耦合：STDIO与HTTP双模驱动

Codex对MCP的支持，不是简单的“能用”，而是深度融入其架构。它支持两种MCP服务器模式，每种都有其不可替代的场景：

STDIO模式（推荐用于本地工具）： 这是Codex最原生、性能最高的模式。当你执行 codex mcp add context7 -- npx -y @upstash/context7-mcp 时，Codex实际上是在后台启动了一个独立的Node.js进程。这个进程的标准输入（stdin）和标准输出（stdout）被Codex的主进程直接接管。所有的JSON-RPC请求和响应，都通过内存管道（pipe）进行，毫秒级延迟，零网络开销。这也是为什么Context7这类需要快速响应文档查询的工具，必须走STDIO——如果每次查一个函数签名都要等HTTP往返，体验会断崖式下跌。

HTTP模式（推荐用于远程/云服务）： 对于Alpha Vantage这类需要认证、有访问频率限制的第三方API，HTTP模式是唯一选择。Codex会作为一个HTTP客户端，向你配置的URL发起POST请求。它的优势在于灵活性：你可以轻松地将一个运行在VPS上的Python Flask服务，或一个部署在Cloudflare Workers上的无服务器函数，注册为Codex的一个MCP工具。更重要的是，HTTP模式天然支持Bearer Token和OAuth认证，安全性更高。

注意：在 config.toml 中配置HTTP服务器时，务必使用 url = "https://your-server.com/mcp" ，而不是 command = "curl" 。后者是错误的，Codex会尝试把它当作一个本地命令去执行，导致连接失败。

这两种模式的共存，让Codex具备了“混合云”的能力：本地工具闪电般响应，远程服务安全可控，两者在同一个Agent内部无缝协作。这正是构建复杂多Agent系统的基础。

3. 实操环境搭建：从零配置一个可工作的MCP工作台

3.1 环境准备：确保基石稳固

在敲下第一个命令前，我们必须确保四个基石绝对稳固。任何一块松动，后续的调试都会变成一场噩梦。我建议你按顺序、逐条验证，不要跳过。

1. Codex CLI安装与认证（v0.23.0+） 这是整个链条的起点。请务必确认版本号，因为v0.22.x及更早版本存在严重的 config.toml 注入漏洞。

# 全局安装（推荐）
npm install -g @openai/codex

# 验证版本（必须 >= v0.23.0）
codex --version

# 登录认证（这是最关键的一步！）
codex login
# 如果在无GUI的服务器上，用设备码登录
codex login --device-auth

实操心得： codex login 命令会生成一个 ~/.codex/auth.json 文件，里面存储了你的OpenAI认证令牌。这个文件的权限必须是600（仅所有者可读写）。如果权限不对，Codex会在启动时静默失败。你可以用 ls -l ~/.codex/auth.json 检查，用 chmod 600 ~/.codex/auth.json 修复。

2. OpenAI API Key设置 Codex本身需要Key来调用大模型，而你的自定义MCP服务器（如Alpha Vantage）也可能需要。我们采用最安全的环境变量方式：

# 在你的shell配置文件中（~/.zshrc 或 ~/.bashrc）添加
export OPENAI_API_KEY="sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
# 立即生效
source ~/.zshrc
# 验证是否生效
echo $OPENAI_API_KEY | cut -c1-10 # 应该输出 sk-xxxxxxxx

3. Alpha Vantage API Key获取与配置 免费Key足够本教程使用，但要注意其25次/天的限制。

# 获取Key后，同样用环境变量设置
export ALPHA_VANTAGE_KEY="YOUR_ALPHA_VANTAGE_API_KEY"
# 同样写入shell配置文件，避免重启终端后失效

4. Next.js开发环境 我们用Next.js作为前端载体，因为它开箱即用的TypeScript和热重载，能让效果立竿见影。

# 创建项目（注意：必须用--typescript）
npx create-next-app@latest portfolio-dashboard --typescript

# 进入项目
cd portfolio-dashboard

# 启动开发服务器（保持它在后台运行）
npm run dev

此时，打开 http://localhost:3000 ，你应该能看到Next.js的默认欢迎页。这是我们的“画布”，所有AI生成的UI都将渲染在这里。

3.2 MCP服务器配置：CLI与Config.toml的双轨策略

配置MCP服务器有两种方式，它们不是互斥的，而是互补的。我称之为“快速上手”和“精细控制”双轨制。

轨道一：CLI命令快速添加（适合标准工具） 对于社区已打包好的工具，如Context7，CLI是最快的方式：

# 添加Context7文档查询工具
codex mcp add context7 -- npx -y @upstash/context7-mcp

# 添加一个用于代码搜索的工具（例如，基于本地git仓库）
codex mcp add code-search -- npx -y @modelcontextprotocol/code-search

执行后，Codex会自动将配置写入 ~/.codex/config.toml 。你可以用 codex mcp list 查看已安装的服务器，用 codex mcp get context7 查看其详细配置。

轨道二：手动编辑 config.toml （适合定制化/HTTP工具） Alpha Vantage的MCP服务器没有官方CLI包，我们必须手动配置。打开全局配置文件：

# 使用你喜欢的编辑器
code ~/.codex/config.toml

在文件末尾，添加以下区块：

[mcp_servers.alphavantage]
command = "uvx"
args = ["av-mcp", "YOUR_ALPHA_VANTAGE_API_KEY"]
startup_timeout_sec = 30

这里有几个关键点需要解释：

• command = "uvx" ： uvx 是UltraViolet（uv）包管理器的执行器，比 npx 更快、更可靠。如果你没有安装 uv ，请先运行 curl -LsSf https://astral.sh/uv/install.sh | sh 。
• args ： av-mcp 是Alpha Vantage的MCP服务器包名， YOUR_ALPHA_VANTAGE_API_KEY 是你的Key。 切记，这只是教程的权宜之计。 在生产环境中，你必须使用环境变量注入，如下所示：

  [mcp_servers.alphavantage]
  command = "uvx"
  args = ["av-mcp", "${ALPHA_VANTAGE_KEY}"]
  env = { ALPHA_VANTAGE_KEY = "${ALPHA_VANTAGE_KEY}" }
  

• startup_timeout_sec = 30 ：这是血泪教训。Alpha Vantage服务器首次启动时，需要下载并缓存一些基础数据，10秒的默认超时（Codex的硬编码值）经常不够。将其设为30秒，能避免90%的“服务器启动失败”报错。

注意： config.toml 的语法非常严格。 [mcp_servers.alphavantage] 必须顶格， command 前面不能有空格，字符串值必须用双引号包裹。一个多余的空格或引号，都会导致Codex启动失败，并抛出一个毫无意义的 TOML parse error 。

3.3 服务器状态验证：在进入AI世界前，先点亮你的仪表盘

配置完成后，绝不能直接开始写Prompt。必须先验证所有MCP服务器是否真的“在线”。这是专业和业余的最大区别。

第一步：全局状态检查 在任意目录下，启动Codex：

codex

当看到 > 提示符后，输入：

/mcp

你会看到一个清晰的表格，列出所有已配置的服务器及其状态：

Name          Status    Type     Command
alphavantage  enabled   stdio    uvx av-mcp ...
context7      enabled   stdio    npx @upstash/context7-mcp ...

如果某个服务器显示 disabled 或 error ，说明配置有误，必须返回上一步修正。

第二步：项目级状态检查 进入你的 portfolio-dashboard 项目根目录，再次运行 codex 。此时，Codex会加载项目级的 .codex/config.toml （如果存在）。为了确保项目配置不会覆盖全局配置，我们创建一个空的项目配置：

mkdir .codex
touch .codex/config.toml

然后再次运行 /mcp 。你应该看到和全局一致的状态。这证明了Codex的配置继承机制工作正常：项目级配置为空，所以它完全继承了全局配置。

第三步：工具连通性测试 仅仅“在线”还不够，必须测试它能否真正“干活”。在Codex的聊天界面中，输入一个简单、明确的指令：

Use the alphavantage tool to get the current price for AAPL.

Codex会短暂思考，然后调用 alphavantage.get_quote("AAPL") 。几秒钟后，你应该看到类似这样的JSON响应：

{
  "Global Quote": {
    "05. price": "182.4500",
    "07. latest trading day": "2024-05-15",
    "09. change": "-0.2300",
    "10. change percent": "-0.13%"
  }
}

如果看到这个，恭喜你，你的MCP工作台已经100%就绪。如果看到 Error: Failed to call tool ，请立即检查 ALPHA_VANTAGE_KEY 环境变量是否设置正确，以及 config.toml 中的 args 字段是否拼写无误。

4. 构建实战：从零打造一个AI驱动的股票风险看板

4.1 初始化项目结构：为AI铺好第一块砖

一个成功的AI项目，始于一个清晰、规范的项目结构。AI不是万能的，它需要良好的“脚手架”才能发挥最大效能。我们从最基础的UI组件开始，手动创建，为后续的AI增强打下坚实基础。

1. 创建核心UI组件 在 portfolio-dashboard 项目中，执行以下命令：

# 创建components目录
mkdir components

# 创建PortfolioCard组件
code components/PortfolioCard.tsx

将以下代码粘贴进去：

import React from 'react';

type Position = {
  symbol: string;
  shares: number;
  price: number;
};

// 初始的模拟数据，AI将在此基础上扩展
const mockPositions: Position[] = [
  { symbol: 'AAPL', shares: 10, price: 150.00 },
  { symbol: 'TSLA', shares: 5, price: 900.00 },
];

export const PortfolioCard = () => {
  return (
    <div className="p-6 border border-slate-200 rounded-xl shadow-sm bg-white text-slate-900">
      <h2 className="text-xl font-bold mb-4">My Portfolio</h2>
      <ul className="divide-y divide-slate-100">
        {mockPositions.map((pos) => (
          <li key={pos.symbol} className="flex justify-between py-3">
            <div className="flex flex-col">
              <span className="font-bold text-slate-800">{pos.symbol}</span>
              <span className="text-sm text-slate-500">{pos.shares} shares</span>
            </div>
            <span className="font-mono font-semibold text-emerald-600">
              ${pos.price.toFixed(2)}
            </span>
          </li>
        ))}
      </ul>
    </div>
  );
};

这段代码的关键在于 mockPositions 数组。它不是一个静态的占位符，而是AI的“数据契约”。AI知道，它要处理的对象，必须有 symbol 、 shares 、 price 这三个属性。这为后续的AI增强提供了明确的输入/输出接口。

2. 将组件挂载到页面 编辑 app/page.tsx ，替换为：

import { PortfolioCard } from "../components/PortfolioCard";

export default function Page() {
  return (
    <main className="min-h-screen flex items-center justify-center bg-slate-50 p-4">
      <PortfolioCard />
    </main>
  );
}

运行 npm run dev ，打开浏览器，你应该看到一个干净、现代的白色卡片，上面列着AAPL和TSLA的模拟持仓信息。这就是我们的“画布”，也是AI即将施展魔法的舞台。

4.2 AI增强第一步：添加夏普比率计算

夏普比率（Sharpe Ratio）是衡量投资组合风险调整后收益的核心指标。手动实现它需要理解均值、标准差、无风险利率等概念，并调用统计库。而AI可以一步到位。

1. 发出精准Prompt 在另一个终端窗口中，确保 npm run dev 仍在运行，然后启动Codex：

cd portfolio-dashboard
codex

在Codex的聊天界面中，输入以下Prompt：

Add Sharpe ratio calculation for each position to PortfolioCard.tsx. Use Context7 to check the function signature if needed. The formula is: (Return - RiskFreeRate) / StandardDeviation. Assume a risk-free rate of 0.02 (2%). Calculate it for the historical prices of each stock and display it in the card.

这个Prompt之所以有效，是因为它包含了AI成功所需的全部要素：

• 明确的目标文件 ： PortfolioCard.tsx
• 明确的任务 ： Add Sharpe ratio calculation
• 明确的工具指引 ： Use Context7 to check the function signature
• 明确的数学公式 ：给出了完整的计算逻辑
• 明确的假设 ： Assume a risk-free rate of 0.02

2. 观察AI的工作流 Codex会按以下步骤执行：

• Step 1：工具调用 —— 它首先会调用 context7.search ，搜索关键词 "javascript sharpe ratio calculation" ，找到一个合适的开源库（如 simple-statistics ）。
• Step 2：代码生成 —— 它会生成一个 calculateSharpe 辅助函数，该函数接收一个价格数组，计算其年化收益率和波动率。
• Step 3：数据获取 —— 它会修改 mockPositions ，为每个股票添加一个 history 属性，用于存储历史价格。
• Step 4：UI集成 —— 它会更新JSX，在每一行股票信息后，添加一个 <span> 标签，显示计算出的夏普比率，例如 Sharpe: 1.23 。

3. 关键代码解析 AI生成的 calculateSharpe 函数，核心逻辑如下：

function calculateSharpe(prices: number[]): number {
  // 计算日收益率
  const returns = prices.slice(1).map((price, i) => 
    (price - prices[i]) / prices[i]
  );
  
  // 计算年化平均收益率（假设252个交易日）
  const annualizedReturn = returns.reduce((a, b) => a + b, 0) / returns.length * 252;
  
  // 计算年化波动率（标准差）
  const mean = returns.reduce((a, b) => a + b, 0) / returns.length;
  const variance = returns.reduce((a, b) => a + Math.pow(b - mean, 2), 0) / returns.length;
  const annualizedVolatility = Math.sqrt(variance * 252);
  
  // 夏普比率 = (年化收益 - 无风险利率) / 年化波动率
  const riskFreeRate = 0.02;
  return (annualizedReturn - riskFreeRate) / annualizedVolatility;
}

实操心得：AI生成的代码通常很“保守”，它会优先选择最广为人知的库和最直白的算法。如果你想让它使用更高效的算法（如Welford算法计算方差），你必须在Prompt中明确指出：“Use Welford's online algorithm for numerically stable variance calculation.”

4.3 AI增强第二步：接入实时市场数据与波动率预警

模拟数据只是起点，真正的价值在于实时性。我们将让AI利用Alpha Vantage MCP服务器，拉取真实的7日股价数据，并根据波动率触发视觉预警。

1. 发出高阶Prompt 在Codex中，输入：

Flag positions where 7-day volatility > 2% using Alpha Vantage data. Fetch the price history for the symbols in my list (AAPL, TSLA) using the alphavantage.get_price_history tool. Calculate the standard deviation of the closing prices over the last 7 days. If the volatility is > 2%, render the stock symbol in red and bold; otherwise, render it in green.

这个Prompt的精妙之处在于它指明了 数据源 （ alphavantage.get_price_history ）、 计算逻辑 （ standard deviation of the closing prices ）和 UI反馈 （ red and bold vs green ）。

2. AI的并行思维 Codex会同时启动两个“线程”：

• 数据线程 ：调用 alphavantage.get_price_history("AAPL") 和 alphavantage.get_price_history("TSLA") ，并行获取两组数据。
• 逻辑线程 ：编写一个 calculateVolatility 函数，该函数接收一个包含 close 价格的数组，计算其标准差。

3. 生成的条件渲染逻辑 AI会将 <li> 标签的 className 属性改为动态的：

<li 
  className={`flex justify-between py-3 ${
    volatility > 2 ? "text-red-500 font-bold" : "text-green-500"
  }`}
>
  <div className="flex flex-col">
    <span className="font-bold text-slate-800">{pos.symbol}</span>
    <span className="text-sm text-slate-500">{pos.shares} shares</span>
  </div>
  <div className="text-right">
    <span className="font-mono font-semibold">
      ${pos.price.toFixed(2)}
    </span>
    <br />
    <span className="text-xs">
      Vol: {volatility.toFixed(2)}%
    </span>
  </div>
</li>

4. 实时效果验证 保存文件后，刷新浏览器。你会看到，AAPL可能显示为绿色（波动率1.8%），而TSLA则显示为醒目的红色加粗（波动率3.5%）。这不再是静态的模拟，而是基于真实市场脉搏的动态反馈。AI已经完成了从“数据获取”到“计算分析”再到“UI呈现”的全链路闭环。

5. 进阶实战：构建多Agent并行风险分析流水线

5.1 为什么需要多Agent？单点瓶颈的破局之道

单Agent模式就像一个全能但忙碌的CEO。它既要研究财报（数据获取），又要写PPT（代码生成），还要给客户打电话（UI渲染）。当它在等待Alpha Vantage API的响应（网络I/O）时，CPU是空闲的；当它在编译TypeScript时，网络又是空闲的。这种串行模式，造成了巨大的资源浪费。

多Agent模式，则是将CEO拆分成一个C-suite高管团队：

• Codex-Risk Agent ：专职负责量化分析。它只关心数学、统计和金融模型，它的“工作台”里只有Alpha Vantage和 simple-statistics 。
• Codex-UI Agent ：专职负责前端实现。它只关心React、Tailwind CSS和用户体验，它的“工作台”里只有 PortfolioCard.tsx 和 RiskTable.tsx 。

这两个Agent可以 完全并行 地工作。Risk Agent在计算VaR（Value at Risk）时，UI Agent已经在为结果设计CSS类名了。这才是将“20分钟的人工流程”压缩到“5分钟的AI流水线”的核心秘密。

5.2 Python Orchestrator：用代码指挥AI军团

我们将用Python作为“总指挥”，通过OpenAI Agents SDK来协调两个Codex MCP服务器。创建 orchestrator.py 文件：

import os
import asyncio
from dotenv import load_dotenv
from agents import Agent, Runner
from agents.mcp import MCPServerStdio

load_dotenv()

async def main():
    # 启动两个独立的Codex MCP服务器（每个都是一个独立进程）
    async with MCPServerStdio(
        name="Codex-Risk-Server",
        params={
            "command": "npx",
            "args": ["-y", "codex", "mcp-server"],
            "env": {
                "OPENAI_API_KEY": os.getenv("OPENAI_API_KEY", ""),
                "ALPHA_VANTAGE_KEY": os.getenv("ALPHA_VANTAGE_KEY", ""),
            },
        },
        client_session_timeout_seconds=360000,
    ) as codex_risk_server, MCPServerStdio(
        name="Codex-UI-Server",
        params={
            "command": "npx",
            "args": ["-y", "codex", "mcp-server"],
            "env": {
                "OPENAI_API_KEY": os.getenv("OPENAI_API_KEY", ""),
            },
        },
        client_session_timeout_seconds=360000,
    ) as codex_ui_server:

        # 定义Risk Agent：它的指令必须极度聚焦
        risk_agent = Agent(
            name="Codex-Risk",
            instructions=(
                "You are a quant analyst. Your sole task is to compute the 95% Value at Risk (VaR) "
                "for all positions in the portfolio-dashboard project. You have access to the "
                "alphavantage.get_price_history tool. Use the historical prices to calculate VaR "
                "using the historical simulation method. Export the results as a constant object "
                "in a new file called 'lib/risk.ts'. Do not modify any UI files."
            ),
            mcp_servers=[codex_risk_server],
        )

        # 定义UI Agent：它的指令必须极度具体
        ui_agent = Agent(
            name="Codex-UI",
            instructions=(
                "You are a frontend developer. Your sole task is to update the UI to display "
                "the 95% VaR values. Import the 'risk' object from 'lib/risk.ts' and add a new "
                "column to the PortfolioCard table. Style the VaR value with conditional coloring: "
                "red if VaR > $1000, yellow if $500 < VaR <= $1000, green if VaR <= $500."
            ),
            mcp_servers=[codex_ui_server],
        )

        # 并行执行两个任务
        risk_task = Runner.run(
            risk_agent,
            "Compute 95% VaR for AAPL and TSLA and write the results to lib/risk.ts."
        )
        ui_task = Runner.run(
            ui_agent,
            "Update PortfolioCard.tsx to display the VaR column with conditional styling."
        )

        # 等待两个任务都完成
        risk_result, ui_result = await asyncio.gather(risk_task, ui_task)

        print("=== Risk Agent Output ===")
        print(risk_result.final_output)
        print("\n=== UI Agent Output ===")
        print(ui_result.final_output)

if __name__ == "__main__":
    asyncio.run(main())

这个脚本的关键设计点：

• async with 上下文管理器 ：确保两个Codex服务器在脚本结束时被优雅关闭，防止僵尸进程。
• env 字典传递 ：将关键的API Key注入到每个Codex子进程的环境中，这是它们能正常工作的前提。
• client_session_timeout_seconds=360000 ：设置为100小时，避免长时间运行的Agent因超时而中断。

5.3 执行与监控：见证并行流水线的威力

1. 安装依赖

pip install openai-agents python-dotenv

2. 运行Orchestrator

# 确保环境变量已加载
export OPENAI_API_KEY="sk-..."
export ALPHA_VANTAGE_KEY="YOUR_KEY"

# 运行脚本
python orchestrator.py

你会看到终端中交替打印出两个Agent的日志：

[Codex-Risk] Calling tool: alphavantage.get_price_history({"symbol": "AAPL"})
[Codex-UI] Reading file: components/PortfolioCard.tsx
[Codex-Risk] Calculating VaR for AAPL... Done.
[Codex-UI] Writing file: components/PortfolioCard.tsx

这种交错的输出，就是并行执行最直观的证据。

3. 效果验证 运行 npm run dev ，刷新浏览器。你将看到Portfolio Card中多了一个“VaR (95%)”列，AAPL可能显示为 $1,250 （红色），TSLA显示为 $890 （黄色）。这一切，都是在几秒钟内，由两个AI代理分工协作、并行完成的。

提示：如果遇到 Connection refused 错误，大概率是Codex MCP服务器启动失败。请检查 npx codex mcp-server 命令是否能在终端中单独运行成功。如果不行，回到 config.toml ，确认 startup_timeout_sec 是否足够长。

6. 常见问题与排查技巧实录

6.1 MCP服务器“假死”：连接超时与无声失败

现象： codex mcp list 显示服务器 enabled ，但当你在Prompt中要求它调用某个工具时，Codex没有任何反应，几秒后直接返回一个空结果，或者报错 Failed to call tool 。

根本原因： 这是最常见的陷阱。MCP服务器进程虽然启动了，但它可能卡在了初始化阶段（如下载大模型、连接数据库），而Codex的默认10秒超时已经到了，于是它就放弃了。

排查与解决：

1. 手动启动服务器 ：在终端中，直接运行 config.toml 中为该服务器配置的 command 和 args 。例如，对于Alpha Vantage：

   uvx av-mcp YOUR_KEY
   

   观察它的启动日志。如果卡在 Downloading cache... ，那就证实了是超时问题。

2. 增加超时时间 ：在 config.toml 中，为该服务器添加 startup_timeout_sec = 60 。

3. 检查STDIO缓冲区 ：某些Node.js工具默认使用行缓冲（line-buffered），而Codex期望的是无缓冲（unbuffered）输出。在 args 中添加 --no-buffer 参数（如果工具支持），或在 command 前加上 stdbuf -oL -eL （Linux/macOS）。

6.2 多Agent环境变量污染：一个Key，两个世界

现象： 当你运行 orchestrator.py 时，Codex-Risk Agent能成功调用Alpha Vantage，但Codex-UI Agent却报错 ALPHA_VANTAGE_KEY not found 。

根本原因： orchestrator.py 中，我们只给 codex_risk_server 的 env 字典里传入了 ALPHA_VANTAGE_KEY ，而 codex_ui_server 的 env 字典是空的。Codex-UI Agent启动时，无法读取到这个环境变量。

排查与解决：

• 方案一（推荐）：全局环境变量 ：在运行 python orchestrator.py 前，确保 ALPHA_VANTAGE_KEY 已在当前shell中导出。这样，所有子进程（包括两个Codex）都能继承它。
• 方案二（隔离）：为每个Agent显式传递 ：在 codex_ui_server 的 env 字典中，也加入 "ALPHA_VANTAGE_KEY": os.getenv("ALPHA_VANTAGE_KEY", "") 。

6.3 工具列表过载：当“太多选择”成为诅咒

**