金融级 Agent 工程设计：从 agent-trade-kit 提炼的 6 个核心原则

Agent 能做的事越来越多，但很少有人认真讲Agent安全。这个问题在 Agent 操作低风险任务时还好说。但当 Agent 开始操作真实账户、真实资金、真实数据时，容错空间就完全不一样了。一次错误的工具调用，可能意味着一笔无法撤销的交易，或者一份提前泄露的合同。

金融场景是这个问题最极端的压力测试。OKX在上个月开源了 agent-trade-kit，核心是一个 MCP Server，让 Claude、OpenClaw等这些Agent直接操作交易所账户。下单、查持仓、配置网格机器人、设置止损止盈，这些交易任务全部通过自然语言驱动、自动执行。它要解决的核心矛盾，是让一个输出本质上不确定的系统（LLM），去安全操作一个容错空间极低的系统（金融账户）。工具全部通过配置接入，调用由自然语言驱动。

我把它的架构文档、安全设计、工具定义都看了一遍，整理出6个设计决策。这些原则放在金融场景是必须的，放在其他需要 Agent 操作真实资源的场景：财务系统、ERP 集成、RPA 替代同样成立。

一、凭证从不进入 LLM 的上下文

用过 MCP 的人都遇到过这个问题：怎么给 Agent 传 API Key？最简单的做法是直接塞进 system prompt，或者让用户在对话里粘贴。大量开源的 MCP 实现就是这么做的。

agent-trade-kit 的做法是：API Key 设置在本地的 ~/.okx/config.toml，由本地运行的 MCP 进程读取，在整个调用链路中，LLM 模型本身永远看不到这个密钥。

LLM 的输出本质上不可完全审计，模型在某次工具调用里把上下文里的敏感信息带出去，既可能是 prompt injection 攻击的结果，也可能只是模型的幻觉行为。更麻烦的是，你在事后根本没办法区分这两种情况。agent-trade-kit 把认证层放在 MCP 进程里，模型只能通过工具调用触发操作，自动化流程不接触凭证。

任何需要 Agent 操作真实账户的系统，凭证都应该存在执行层，而在上下文层压根不存在。这个区别还影响可追溯性，执行层的操作日志是清晰的，而上下文层的信息流动是混沌的。

二、四层安全降级，给不同信任程度精确的配置空间

大多数人给 Agent 加安全限制时，想到的是一个开关：安全模式开/关，只读/读写。agent-trade-kit 做了四层。

第一层是 —demo 模拟盘模式。Agent 操作的是 OKX 的模拟账户，所有下单行为都真实执行，但不消耗真实资金。逻辑和 staging 环境一样，相同的代码路径，隔离的数据。

第二层是 —read-only 只读模式。Agent 只能查询，任何 write 操作会被直接拒绝。价格、持仓、历史订单都可以看，下单类工具调用在这一层直接失效。

第三层是模块级权限控制。整个 toolkit 有七个模块：market、spot、swap、futures、option、account、bot。启动时通过 —modules 指定加载哪些：

okx-trade-mcp --modules spot,account

如果不开 option 模块，期权相关的工具根本不会出现在 MCP 的工具列表里。Agent 看不到这些工具，自然不会尝试调用。

第四层是实盘的逐笔确认。即使在完整权限下，每一笔 write 操作执行前都需要用户显式确认。

这四层的价值在于给不同场景提供了精确的配置空间。只想让 Agent 做市场分析的用户，用 —modules market —read-only，连账户信息都不暴露。要完全自动化的量化策略，才需要完整权限加严密的操作审计。

这里有一个设计哲学值得单独说：最小权限原则在 Agent 场景里比传统软件更重要。 传统软件如果有个多余的权限，多数情况下它就是闲置的。Agent 会主动使用它感知到的所有能力，且它的判断是概率性的。给它的权限表面越大，一次错误判断能造成的破坏半径就越大。

三、工具爆炸问题的解法：按需加载

agent-trade-kit 目前有 82 个工具。

把 82 个工具定义全部配置进 MCP Server，每次调用都会把这些工具的 schema 带进模型的 context。代价有两个：一是 token 消耗，工具 schema 通常比用户问题本身占更多 token；二是选择歧义，工具越多，模型在”用哪个工具”这个决策上出错的概率越高，尤其是功能相近的工具之间。

任何认真使用过 function calling 的人都会遇到这个问题：工具超过 20 个之后，模型在调用时选择工具的准确率会出现肉眼可见的下降，特别是在工具命名和描述相近的情况下。

agent-trade-kit 把工具拆成四个独立的 Skill：okx-cex-market（市场数据）、okx-cex-trade（交易执行）、okx-cex-portfolio（组合管理）、okx-cex-bot（机器人策略）。只安装和加载需要的 Skill，其余工具完全不在 context 里。

这在 MCP 生态里叫 Skills 协议，但本质是工具命名空间的模块化，对应的通用 Agent 设计问题叫 tool routing——如何在运行时决定给 Agent 暴露哪些工具。

工具路由可以是静态的（像 agent-trade-kit，启动时配置），也可以是动态的（根据用户意图实时检索相关工具，RAG 式的工具召回）。两种都有适用场景，但核心原则一致：在特定任务上下文里，给 Agent 最少数量的、最相关的工具。

四、结构化错误设计，直接决定 Agent 自我修复的能力上限

agent-trade-kit 的错误返回格式长这样：

{
  "tool": "swap_place_order",
  "error": true,
  "type": "OkxApiError",
  "code": "51020",
  "message": "Order quantity invalid",
  "endpoint": "POST /api/v5/trade/order",
  "traceId": "abc123def456",
  "timestamp": "2026-03-03T10:00:00.000Z",
  "serverVersion": "1.0.4"
}

大多数 MCP 实现的错误处理很粗糙，要么直接把底层异常的 message 字符串抛出来，要么包一层自然语言描述返回给模型。

这在 Agent 场景里会造成什么问题？

Agent 在 agentic loop 里需要自主处理异常，决定是重试、换参数、还是放弃并告知用户。它做出这个决策的唯一依据，是工具调用返回的内容。如果返回的是 “Something went wrong”，Agent 几乎必然产生错误推断，它可能用同样的参数重试（因为不知道错误原因），也可能编造一个听起来合理但完全错误的解释。

结构化的错误返回解决的是 Agent 的错误分类问题。拿上面这个例子：code: “51020” 是 OKX 的标准错误码，代表数量参数不合法；endpoint 字段指明是哪个接口出错。两个信息加在一起，Agent 可以准确判断这是参数错误，应该修正 sz（数量）参数后重试，而不是换接口或者放弃。

traceId 的设计也值得单说。它主要给人类排错用，但对 Agent 的长期可靠性同样关键。在生产环境里事后复盘某次异常行为，有 traceId 就能精确还原当时的调用链路，没有的话基本靠猜。

给 Agent 的错误信息质量，直接决定了它自我修复的能力上限。 而且这个设计必须在工具定义阶段就确定，一旦 Agent 的决策逻辑开始依赖特定的错误字段，再改就会破坏已有的行为。

五、Demo 环境与生产环境的物理隔离

这一点在文档里只有一句话，但实际上容易被忽视。

agent-trade-kit 的 demo 模式和 live 模式使用完全不同的 OKX 账户和 API 端点，两者在数据层面没有任何交叉。

最常见的偷工减料做法是用一个 sandbox: true 的参数来控制，底层走同一套代码逻辑，只是换了个请求标志位。这种做法的隐患是：代码里任何一个地方漏掉了对这个标志位的判断，测试行为就会打到生产环境。

agent-trade-kit 用物理隔离代替逻辑隔离：demo 账户有自己的 API Key，live 账户有自己的 API Key，通过 —profile 切换的是整个凭证配置。代码层面根本不存在”测试流量意外打生产”的可能，因为两套环境没有共享任何技术资源。

这个设计和第一条的凭证安全形成了呼应：凭证存在配置文件里，用多个 profile 隔离不同权限级别的访问是自然的扩展。实盘交易的 profile，只读查询的 profile，模拟盘的 profile，各自有各自的凭证和权限范围，互不干扰，也互不污染。

六、CLI 作为确定性执行层与 AI 执行层并存

agent-trade-kit 除了 MCP Server，还提供了独立的 CLI 工具 okx-trade-cli。官方把它描述成”terminal 交易工具”，但它承担的角色远不止于此。

CLI 可以被 Agent 通过 shell 工具直接调用，作为 MCP 之外的另一条执行路径。在 token 效率上有实际优势，MCP 的工具调用走完整的 JSON-RPC 协议，CLI 的调用更轻量，在高频场景下节省的上下文开销是可观的。

更重要的是，CLI 使整个工具链可以脱离 AI 客户端独立运行。用 cron job 定时调用 okx market ticker BTC-USDT，把输出塞进另一个脚本做处理，完全不需要 LLM 参与。这意味着 agent-trade-kit 是一个通用的程序化交易接口，AI 是其中一种接入方式，不强依赖。

构建面向 Agent 的工具时，同时提供一个面向程序的接口，两者共享相同的核心逻辑。 好处不只是灵活性，还有可测试性——CLI 的行为是确定的，可以对它写精确的自动化测试，然后用这些测试间接验证 Agent 的工具调用是否符合预期。这是一个很实用的工程技巧，在纯 MCP 实现里做 Agent 行为的单测往往很痛苦，有了 CLI 这个确定性层，问题就简单很多。

最后

把这6个设计点放在一起，都在回答同一个问题：怎么在 AI 的不确定性和现实系统的严苛要求之间建立可靠的隔离层。

凭证隔离是信任边界的划定。四层权限降级是容错半径的控制。工具按需加载是决策复杂度的压缩。结构化错误是自我修复能力的上限设定。物理环境隔离是测试和生产无法相互污染的保证。CLI 层是确定性和概率性两种执行路径的共存设计。

这些原则放在金融场景里是必须的，放在其他高风险 Agent 场景里同样成立。agent-trade-kit 是一个认真做过的参考实现，MIT 开源，代码可审计。

开源仓库：https://github.com/okx/agent-trade-kit

原文信息

作者：WY（@akokoi1） 原文地址：