Codex CLI MCP 教程：构建投资组合仪表板智能体

您或许已经注意到，AI 编码智能体在需要编写复杂函数或调试棘手错误时非常有用。但它们常常会撞上“墙”——一旦您需要的信息不在项目文件里，它们往往就帮不上忙了。

试想一下，如果您的编码智能体能够跳出当前环境，主动拉取实时数据、查询最新文档，或者代表您调用各类工具，那它的能力就会大幅提升。

在本教程中，我将逐步演示如何使用 Codex CLI 和 Model Context Protocol（MCP）实现这一点。我们将讲解 Codex CLI 与 MCP 协同工作的基础原理，使用实时股票数据从零构建一个金融仪表板项目，介绍多智能体模式，并讨论安全最佳实践。

为了最大化学习效果，非常建议您动手跟练。请先创建一个新的 Next.js 项目，确认已正确安装 Codex CLI，并从 Alpha Vantage 获取免费 API 密钥，准备开始构建。

如果您刚接触 agentic AI，强烈建议报名我们的AI Agent Fundamentals技能路径。

Codex CLI MCP 基础知识

在正式编码前，我们需要理解所用工具。下面来拆解 MCP 是什么，以及 Codex CLI 如何利用它。

什么是 MCP？

MCP 即 Model Context Protocol，由 Anthropic 提出，用于标准化 AI 系统连接外部工具与数据源的开放标准。从技术上讲，它通过 STDIO（标准输入/输出）或 HTTP 承载 JSON-RPC 2.0。

来源：truefoundry

其重要意义在于有效解决了过去的“集成噩梦”：以往若要让 LLM 连接特定数据库或工具，常常需要为特定组合定制连接器——既混乱又难维护，也不易扩展。

借助 MCP，我们获得了一套统一的协议来连接所有 LLM 工具，用标准接口取代了定制集成，大幅简化了格局。

若您想深入了解其底层机制，可以参考这篇从零构建 MCP 服务器与客户端的演练。

什么是 Codex CLI？

接下来聊聊 Codex CLI。它是 OpenAI 推出的轻量级、基于终端的编码智能体。与 Claude Code 或 Cursor 等工具类似，它旨在真正理解您的整个项目上下文，而不只是当前打开的文件。

它将一切汇聚于同一处：高效的代码索引、对话历史，以及真实的命令执行，统一在一个文本用户界面（TUI）中。其几乎所有行为都可通过编辑 config.toml 文件来控制与定制，管理非常方便。

Codex 如何实现 MCP

在 MCP 实现方面，Codex 同时支持 STDIO 服务器与可流式的 HTTP 服务器：

• STDIO 服务器以本地进程运行。您可以将其理解为在本机直接运行的特定命令与参数。
• Streamable HTTP 服务器通过 URL 远程连接，并可选支持 Bearer Token 或 OAuth 身份验证。

一个非常方便的特性是，Codex CLI 与 IDE 扩展实际上共享同一个 config.toml 文件。这意味着不论您在终端还是编辑器中工作，都能获得一致的 MCP 工具集；无需重复配置，省时省力。

Codex 也很好地处理了身份验证，支持通过 codex mcp login <server-name> 命令进行 OAuth 登录。您还可以使用配置中的 enabled_tools 或 disabled_tools 精细控制智能体可用的具体工具。

Codex CLI MCP 环境搭建

理论已经讲完，接下来开始动手配置。在本节中，我们将逐步完成 MCP 服务器的设置，让它们随时为您工作。

先决条件

在将 Codex 接入 MCP 与 Agents SDK 之前，请确保以下事项已就绪：

• 本机已安装 Codex CLI。您可以在终端运行 npm install -g @openai/codex 进行全局安装。运行 codex --version 验证安装是否成功。

• 本机已完成 Codex 登录。运行一次 codex login（或在无头环境中运行 codex login --device-auth），并验证 codex 在终端中可正常使用。

• 对于多智能体工作流，您还需要一个 OpenAI API 密钥。请在 OpenAI 控制台获取，并在 shell 中通过 export OPENAI_API_KEY="sk-..." 设置。

• 已设置外部工具所需的环境变量。例如，Alpha Vantage 会从 ALPHA_VANTAGE_KEY 读取您的行情数据密钥，运行示例前也应以同样方式导出。

获取 AlphaVantage API 密钥的方法：

1. 访问 AlphaVantage 支持页面。
2. 填写简短注册表（机构、角色与邮箱）。
3. 页面将立即显示您的 API 密钥。请复制并妥善保存。

免费层每天最多允许 25 次 API 请求。对于更高需求，Alpha Vantage 提供高级套餐。

通过 CLI 添加 MCP 服务器

接下来使用命令行与 codex mcp add 命令新增服务器。这样无需手动改配置文件，大部分工作 Codex 会替您完成。

例如，若您希望添加一个用于文档查询的服务器，可以使用 Context7 MCP。请在终端运行：

codex mcp add context7 -- npx -y @upstash/context7-mcp

通过 config.toml 添加 MCP 服务器

虽然 CLI 命令非常适合快速上手，但有时您需要更高的可控性，或只是想看清底层在做什么。这种情况下，可以直接编辑配置文件。

需要注意，配置可存在于两个位置，且作用域不同：

• 全局配置文件位于 ~/.codex/config.toml，适用于您参与的所有项目

• 项目级配置文件位于特定项目目录内的 .codex/config.toml。通常，当两者冲突时，以项目级配置为准。

并非所有 MCP 服务器都带有专用 CLI 安装命令。这种情况下，您需要在 ~/.codex/config.toml 中直接配置，指定 Codex 启动服务器进程所需的命令与参数。无论是通过 STDIO 在本地运行，还是通过 HTTP 远程连接，都由您完全掌控。

AlphaVantage MCP 服务器即属于此类。打开 config.toml 并添加以下代码块：

[mcp_servers.alphavantage]
command = "uvx"
args = ["av-mcp", "<your-key>”]技术支持

免责声明：在 config.toml 中硬编码 API 密钥并非真实项目的推荐做法。请避免在任何受版本控制（如 GitHub）、与他人共享或部署到服务器的项目中这样做，因为凡是能读取该文件的人都可能滥用您的密钥。就本教程而言，这样做可接受，因为 config.toml 位于您的主目录（~/.codex/）且仅限于您的机器。

建议在该块中加入 startup_timeout_sec=30，覆盖默认的 10 秒超时，确保有足够时间建立连接。

管理 MCP 服务器

配置了多个服务器后，您需要掌握管理方式。Codex 提供了一组命令来保持一切井然有序。

查看当前已安装的服务器：运行 codex mcp list。若需查看某个服务器的具体信息（如我们刚添加的 Alpha Vantage），可运行 codex mcp get alphavantage。当然，如果您不再需要某个服务器（例如 Context7），可以通过 codex mcp remove context7 将其移除。

最后，在活跃的 Codex 会话中，您可以核验一切是否正常运行。直接在聊天界面输入 /mcp，即可查看已连接工具的状态。您应能看到 alphavantage 与 context7，状态均为 Status: enabled。

使用 Codex 与 MCP 构建股票投资组合风险仪表板

纸上得来终觉浅，最好的学习方式是构建真实项目。本节我们将从零搭建一个可用的“股票投资组合风险仪表板”，利用 Codex 与 MCP 拉取真实行情数据并计算风险指标。

为展示仪表板，项目将使用 TypeScript（基于 JavaScript 的编程语言）。如需温习不同层级的要点，建议查阅我们的TypeScript 面试题指南。

项目搭建

按照以下步骤搭建项目：

1. 初始化项目：在终端运行标准的 Next.js 创建命令：npx create-next-app@latest portfolio-dashboard --typescript

2. 接受默认提示，以确保标准配置

3. 进入新项目文件夹：cd portfolio-dashboard

4. 为 UI 组件创建子目录：mkdir components

5. 在 components 子目录下创建投资组合卡片组件（.tsx 文件）：components/PortfolioCard.tsx

该组件定义了一个 PortfolioCard，渲染一个样式化卡片，展示一组模拟持仓（AAPL 与 TSLA），显示每只股票的代码、持股数量与当前价格。它使用 Tailwind CSS 进行布局与样式，卡片为白底，价格以祖母绿配色显示。效果如下：

// components/PortfolioCard.tsx
import React from 'react';

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

const mockPositions: Position[] = [
  { symbol: 'AAPL', shares: 10, price: 150.00 },
  { symbol: 'TSLA', shares: 5, price: 900.00 },
];

export const PortfolioCard = () => {
  return (
    // Added text-slate-900 to ensure visibility on the white background
    <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>
  );
};技术支持

保存该文件后，请在主文件 app/page.tsx 中引入并使用 <PortfolioCard/>，以便在浏览器中查看：

// 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">
      <PortfolioCard />
    </main>
  );
}技术支持

此时运行 npm run dev，浏览器中的输出应类似这样：

在开始与 AI 协同编码前，需要确保智能体已就绪。保持运行 npm run dev 的终端不动，在新的终端窗口中：

1. 运行前文提到的 MCP 配置命令（如尚未执行）

2. 通过 export ALPHA_VANTAGE_KEY=”<your-key>” 导出 API 密钥

3. 在同一终端窗口中运行 codex 启动 Codex 智能体

实现夏普比率功能

我们首先计算夏普比率（Sharpe ratio），这是评估风险调整后收益的关键指标。通常，查询公式并寻找合适库会比较繁琐——这次交给 Codex 来处理。

在 Codex 终端会话中输入以下提示：

"Add Sharpe ratio calculation for each position to PortfolioCard.tsx. Use Context7 to check the function signature if needed."

您会看到 Codex 开始行动。首先它可能会使用 Context7 工具查询技术分析库（ta-lib 或 JavaScript 等价库）的文档，以确保使用正确的输入；随后会自动修改您的 PortfolioCard.tsx 文件。

它很可能会扩展 mockPositions 并添加一个用于计算比率的辅助函数，大致如下：

function calculateSharpe(prices: number[]) {
  // Codex implements the logic here using standard deviation and mean returns
  // resulting in a return value like 1.23
}技术支持

并更新 JSX 以渲染该指标：

<PortfolioCard sharpe={calculateSharpe(prices)}/>技术支持

查看浏览器，您现在应该能在持仓旁看到夏普比率（例如 1.23），如下所示：

添加波动率告警

现在让仪表板联动起来，并使用 AlphaVantage 的真实金融数据。我们希望在股票变得过于波动时收到告警。这里将“高波动”定义为 7 日波动率大于 3%。

在 Codex 终端中输入：

"Flag positions where 7-day volatility > 2% using Alpha Vantage data. Fetch the price history for the symbols in my list."

这正是 MCP 大显身手的地方。Codex 会识别到需要外部数据，并调用 alphavantage.get_price_history("AAPL") 与 alphavantage.get_price_history("TSLA") 获取真实世界的数据点。

拿到数据后，它会编写逻辑，计算这些价格的标准差，并最终更新组件样式以直观标记风险。

您将看到 PortfolioCard 代码被更新为包含条件样式。逻辑可能类似：

<li className={volatility > 2 ? "text-red-500 font-bold" : "text-green-500"}>
  {pos.symbol}: {volatility}%
</li>技术支持

查看运行中的应用，您可能会看到 AAPL 为绿色（安全）、TSLA 为红色（波动），全部基于智能体拉取的实时行情数据。

最终效果可能如下：

最终界面可能与上图略有不同，具体取决于 Codex 的实现。当然，您也可以在提示中更精确地描述期望的界面。

如果您希望设计更大的系统并了解交接、工具边界与评估，建议学习我们的Building Scalable Agentic Systems课程。

以 MCP 服务器模式运行 Codex

到目前为止，我们一直在用 Codex 作为调用其他工具的主界面。更有意思的是：Codex 自身也能充当 MCP 服务器。

这意味着，您可以将 Codex 强大的文件编辑与命令执行能力暴露给其他 MCP 客户端，从而让其他 AI 智能体在其工作流中把 Codex 当作工具使用。最大优势在于能够实现并行执行。

例如，您可以设计一个工作流：一个智能体使用 Codex 构建前端 UI，另一个完全独立的智能体使用另一实例的 Codex 编写后端 API。由于它们以独立进程运行，可以同时工作，潜在地将开发时间减半。

启动 Codex 服务器模式

要切换至该模式，使用命令：codex mcp-server。

运行后，Codex 不再表现为聊天界面，而是开始通过标准输入/输出（STDIO）监听来自其他程序的指令。

在集成到复杂系统之前，务必先测试其是否正常工作。Model Context Protocol 团队提供了一个方便的检视工具。您可以在终端运行以下命令，启动一个连接本地 Codex 实例的网页界面：

npx @modelcontextprotocol/inspector codex mcp-server

浏览器会打开一个页面，您可以手动向 Codex 发送命令并查看响应，这对调试非常有用。界面如下：

集成 OpenAI Agents SDK

如果您是 Python 开发者，可能希望使用 OpenAI Agents SDK 在自定义脚本中编排 Codex，这样就能让 Python 程序“雇佣” Codex 完成特定编码任务。

下面是一个快速示例。您可以使用 MCPServerStdio 启动 Codex 进程：

在 Python 虚拟环境中安装 openai-agents 包：

pip install openai-agents

要设置 codex 进程，创建 orchestrator.py 文件并写入以下代码：

from agents import Agent
from agents.mcp import MCPServerStdio

# initialize connection
codex_server = MCPServerStdio(
    name="Codex CLI",
    params={
        "command": "npx",
        "args": ["-y", "codex", "mcp-server"]
    },
    client_session_timeout_seconds=360000,
)
# create codex agent
agent = Agent(
    name="Lead Developer",
    mcp_servers=[codex_server]
)技术支持

在此设置中，Codex MCP 服务器会暴露两个主要工具：codex() 与 codex-reply()。理解它们的区别很重要，这能确保智能体持续保持上下文：

• 当您想启动全新的会话或任务时，使用 codex()。
• 当您想延续现有对话或对刚完成的工作迭代时，使用 codex-reply()。它需要 conversationId 参数以将请求映射到正确的会话。

client_session_timeout_sessions 是客户端与相应 MCP STDIO 服务器保持会话的最长时间。我们将 Codex 设为相当充裕的 360,000 秒（100 小时），以便长时工作流可复用同一 MCP 会话而不至于因空闲超时而中断。

社区封装

社区也提供了更易用的封装。其中值得一提的是 GitHub 上的 codex-mcp-wrapper 仓库。该封装专为将 Codex 集成至其他环境（如 Claude Code）而设计。

编排 Codex CLI MCP 多智能体金融流水线

了解如何以服务器模式运行 Codex 后，我们看一个更具威力的场景：编排一个多智能体流水线，让多个 AI 智能体协同工作，相比单一智能体显著加速我们对金融仪表板的升级。

如果多智能体设计让您感觉抽象，可以参考这篇常见智能体架构的清晰解读，了解多智能体在哪些场景真正有用。

协调风险与 UI 智能体

在该设置中，我们使用 Python 脚本作为编排器来管理工作流。与其让一个智能体包揽所有任务，我们将其拆分为两个专精的智能体：

• Codex-Risk，专注量化分析
• Codex-UI，专注前端实现

由于我们现在通过 Agents SDK 以无头 MCP 服务器方式运行 Codex，因此不仅 SDK 与 Codex 进程要对 OpenAI 进行认证，而不仅仅是交互式的 Codex CLI。

为简化且保证可靠性，请在运行编排器前确保环境中已设置 OPENAI_API_KEY（或可选的 CODEX_API_KEY），以便链路中的每一环都能访问模型。在新终端中运行：

export OPENAI_API_KEY=<your-key>技术支持

我们在一个 async with 块中初始化两个彼此独立的 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():
    async with MCPServerStdio(
        name="Codex-Risk-Server",
        params={
            "command": "npx",
            "args": ["-y", "codex", "mcp-server"],
            # Codex itself uses your existing auth (codex login / OPENAI_API_KEY)
            "env": {
                # pass through any env you already rely on inside Codex
                "OPENAI_API_KEY": os.getenv("OPENAI_API_KEY", ""),
                "CODEX_API_KEY": os.getenv("CODEX_API_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", ""),
                "CODEX_API_KEY": os.getenv("CODEX_API_KEY", ""),
            },
        },
        client_session_timeout_seconds=360000,
    ) as codex_ui_server:

        # 1. Define specialized agents (both just use the 'codex' tool)
        risk_agent = Agent(
            name="Codex-Risk",
            instructions=(
                "You are a quant analyst. Use the 'codex' tool to compute VaR and "
                "Sharpe ratio for all positions in the portfolio-dashboard project. "
                "Assume Alpha Vantage integration and volatility logic are already implemented "
                "in the code; reuse and extend that code instead of re-calling external APIs."
            ),
            mcp_servers=[codex_risk_server],
        )

        ui_agent = Agent(
            name="Codex-UI",
            instructions=(
                "You are a frontend developer. Use the 'codex' tool to update the UI in "
                "the portfolio-dashboard project. Your job is to add a VaR (95%) column "
                "to the RiskTable / PortfolioCard views, with clear red/green conditional styling."
            ),
            mcp_servers=[codex_ui_server],
        )

        # 2. Run Risk + UI agents concurrently
        risk_task = Runner.run(
            risk_agent,
            "Compute portfolio VaR (95%) for all positions and write the results into the codebase "
            "in a way that the UI can easily consume (e.g., exported constants or helper functions).",
        )
        ui_task = Runner.run(
            ui_agent,
            "Prepare or update the RiskTable / PortfolioCard components to display a VaR (95%) "
            "column, assuming the risk logic already exists in the project.",
        )

        risk_result, ui_result = await asyncio.gather(risk_task, ui_task)

        print("=== Codex-Risk result ===")
        print(risk_result.final_output)
        print("\n=== Codex-UI result ===")
        print(ui_result.final_output)

        # 3. Optional second pass: let UI agent consume the exact risk output
        followup_ui_result = await Runner.run(
            ui_agent,
            (
                "Now update the UI to wire in the actual VaR values. "
                f"Context from the risk agent: {risk_result.final_output}"
            ),
        )

        print("\n=== Codex-UI follow-up ===")
        print(followup_ui_result.final_output)


if __name__ == "__main__":
    asyncio.run(main())技术支持

在设置好 OpenAI API 密钥的同一终端窗口中，运行编排脚本：

python orchestrator.py技术支持

这些智能体将各自去通过 MCP 查询 Alpha Vantage 文档、获取历史数据，并编写 Python 或 TypeScript 逻辑来计算您投资组合的 VaR（在险价值）。

待两个 codex 实例完成所需更改后，您可以再次运行 npm run dev 命令，在浏览器中查看最终结果。大致如下：

通过拆分职责，我们将原本可能需要 20 分钟往返沟通的流程，变成全自动流水线：风险智能体负责数学计算，UI 智能体负责实现展示，数秒内即可更新仪表板。

并行任务执行

真正的魔力在于执行模型。在标准聊天界面中，工具调用是串行的——必须等数据获取完成，才能请求更新图表。

通过 MCP 与多智能体方法，我们实现了真正的并发。当Codex-Risk 智能体在等待 Alpha Vantage API 的网络响应时，Codex-UI 智能体已可开始搭建表格列与 CSS 类。

通过拆分职责，我们将可能需要 15～20 分钟往返的流程，压缩为精简流水线：从数据抓取到复杂风险分析再到完整 UI 实现，约 5 分钟即可完成。

安全考量与限制

凡是能把代码连接到外界的强力工具，都必须谈安全。尽管 Codex 与 MCP 释放了强大能力，但也引入了新的攻击面与实际限制。在生产环境部署前，您需要了解这些问题。

配置层面的漏洞

最关键的安全点在配置文件本身。早期版本的 Codex CLI 存在已知漏洞：可将恶意命令注入 config.toml，并配合将 CODEX_HOME 重定向至本地目录的 .env 文件实现。这一问题已被修补，因此务必确保您运行的是v0.23.0 或更高版本。

但风险并不会因更新而完全消失。由于 Codex 会尊重项目级配置，如果您克隆了一个仓库，其中包含恶意的 .codex/config.toml，并且 .env 将 CODEX_HOME=./.codex，那么在该目录运行 codex 可能执行文件中定义的意外命令。

务必养成习惯：克隆新项目后先审计其配置文件，再运行任何命令。

MCP 的限制

从实际使用看，也有一些不够完善之处。目前在启动 CLI 时并没有内建“连通性测试”。Codex 不会在启动时自动告知某个 MCP 服务器是否离线或不可达。您基本需要提示模型类似“检查我的工具”，才能验证连接是否可用。

此外，尽管很想把所有工具都装上，但务必有所取舍。若挂载过多 MCP 服务器，模型性能会显著下降。工具越多，模型需要过滤的“噪声”越大，越可能困惑或导致幻觉。建议只挂载当前所需的 MCP 服务器。

Codex CLI 与 Claude Code 对比

最后，将 Codex CLI 与其近似竞品 Claude Code 做个比较。

若目标是自动化与持续集成（CI）流水线，Codex CLI 通常更合适。它轻量、易用、且高度可脚本化。相对地，Claude Code 在编辑器内的交互式编码体验上更为出色，针对重构、测试运行与项目级助手等提供了更强的内建体验。

配置风格也不同。Codex 使用 TOML 文件配置，~/.codex/config.toml 同时被 CLI 与 IDE 扩展共享，并可在每个仓库内通过 .codex/config.toml 进行项目级覆盖。这意味着环境默认共享，但可按项目定制。

Claude Code 通常采用基于 JSON 的设置，具有全局配置（例如 ~/.claude.json）以及项目级文件（如 .mcp.json 或项目设置），允许每个仓库定义其 MCP 服务器与行为，提升隔离性，但也意味着每个项目的初始设置可能略多一些。

两者都是 AI 编码智能体的前沿代表，选择取决于您的具体工作流：如果您更多把智能体视作驻留在终端或 CI 任务中的工具，Codex 往往更契合；若主要需要一个以编辑器为中心的编码伙伴，Claude Code 常会更自然。

若想更深入对比，建议阅读我们的Codex vs Claude Code 指南。

总结

本文覆盖了从 MCP 基本概念到构建自有 Codex 智能体的诸多内容。但如果只能带走一个要点，那就是工作流本身的威力：从配置 MCP 服务器、运行 Codex，到观察工具自动发现所需数据，这一整套流程让您构建功能的速度远超人工。

如果您刚开始上手，强烈建议不要一开始就搞得太复杂。先用 Context7 做文档查询，再配一个基于 API 的 MCP（比如今天搭的 Alpha Vantage）。先把这套流程练熟，再尝试多智能体协作。

当您具备信心后，可能性将无限。去探索更多 MCP：连接 Figma，直接从设计生成 UI 代码；或者接入 Sentry，让 Codex 自动诊断并修复生产故障。尝试使用 Codex 子智能体，看看您能把多少常规工作交给它们。工具已就绪，能力强大，等待您使用。

如果您对构建 AI 应用感兴趣，强烈建议报名我们的AI Engineering with LangChain技能路径。课程内容为 AI 原生，您将获得一位专属导师，从您的水平出发，教授成为 AI 工作流工程专家所需的精确技能。