企业官网建设流程全解析

智能体这个词这两年掉价得挺厉害。演示视频里它能自己查资料、自己写代码、自己调接口，看得人热血沸腾；真接进业务系统跑两天，画风就变了——谁授权的、调了什么工具、把哪张表的数据带出去了、出错之后从哪儿查，全是一笔糊涂账。我最近半年在几个团队里推智能体落地，被问得最多的不是"选哪个模型"，而是"这东西跑起来之后，我到底怎么管它"。

OpenClaw 企业版 OCE 这次发布，主打的就是这个痛点：开源、免费、可自托管，并且把"持证上岗"这四个字摆到了台面上。说白了，它想解决的不是智能体聪不聪明，而是智能体能不能被企业放心地放进生产环境。这篇东西我打算按自己实际的部署和验证路径来写：先拆清楚"持证上岗"到底指哪几件事，再看 OCE 的架构是怎么回应这些事的，然后是一台机器从零跑起来的完整步骤、权限与审计的具体配置、三个能立刻用的场景，最后是我踩过的坑和一张排查速查表。不管你是刚开始接触智能体的开发，还是已经在给团队做技术选型的负责人，应该都能从里面拿走点能直接用的东西。

1. 先把“持证上岗”这个词拆开看

1.1 智能体从演示走向生产，卡点从来不在模型能力

很多人以为智能体落地难是因为模型不够强，我实测下来的结论正好相反。现在主流的开源模型在工具调用、结构化输出这些基础能力上已经够用了，真正让项目卡住的是另外三件事：一是不可预测，同一个问题问两遍，它可能走两条完全不同的工具链路，第二遍就出错了；二是不可追溯，出了问题你只能看到一段聊天记录，看不到它中间调了什么、传了什么参数、拿到了什么返回；三是不可约束，你没法限定它只能查哪几张表、只能调哪几个接口、单次任务最多花多少钱。

这三件事在个人玩具项目里无所谓，在企业里每一条都是硬门槛。我见过一个团队做了个挺漂亮的客服智能体，Demo 阶段领导很满意，一提到上线，安全那边只问了一句"它能不能读用户手机号"，项目就停了三周。后来他们花了比开发更长的时间去补权限和日志，才勉强过审。

所以 OCE 这类企业发行版的价值，不在于它内置了多强的 Agent 能力——那部分是开源社区共有的——而在于它把身份、权限、审计、沙箱这些东西做成了平台级的基础设施，而不是让每个开发者自己用胶水代码糊一遍。这个区别很关键：前者是一次性投入，后者是每个项目重复踩一遍坑。

1.2 身份、权限、审计：企业真正要的是这三张证

我把"持证上岗"理解成三层含义，对应三个技术能力，缺一不可。

第一张证是身份。智能体在系统里必须是一个能被识别的主体，有自己的 ID、自己的凭证、自己的归属部门。这一点听起来很基础，但很多自建方案里，智能体是直接复用某个管理员的 API Key 在跑，出了事根本分不清是人干的还是机器干的。OCE 里每个 Agent 都有独立的身份标识，调用外部系统时用的是绑定的服务凭证，凭证可以单独吊销，不影响其他 Agent。

第二张证是权限。身份解决了"你是谁"，权限解决"你能干什么"。这里最容易犯的错误是权限给太宽——反正智能体要调工具，那就把工具全开给它。正确的做法是反过来：默认全关，按场景逐个开，而且开的时候要带约束条件，比如"只能查订单表，且只能查当前用户自己的订单"。OCE 的工具注册机制支持在工具层面挂参数级的约束策略，这个后面第 4 章会详细讲。

第三张证是审计。审计不是简单记个日志，而是要能回答四个问题：谁发起的、智能体做了什么决策、调用了哪些工具、产生了什么副作用。这里面最容易被忽略的是"决策过程"，也就是模型的思考链路和工具的中间返回。OCE 的做法是把整个执行过程拆成一条 trace，每一步都有 span，可以按 trace_id 完整回放。这个能力在做故障复盘的时候价值极高，我后面会给一个真实用上的例子。

注意：审计日志本身也是敏感数据。完整的工具入参出参里很可能包含用户隐私字段，落盘前一定要做脱敏，而且日志的保留周期要和你的数据合规策略对齐，别一存就是三年。

1.3 为什么“开源 + 自托管”在这个阶段是刚需

有人会问，直接用云端托管版的智能体平台不行吗，为什么要自己折腾部署。这个问题在三个场景下答案很明确。

第一类是数据不出域的硬约束。金融、医疗、部分制造业的客户数据，合同里写死了不能离开指定网络环境。哪怕云端平台承诺不训练、不留存，法务那一关也过不去。自托管是唯一解。

第二类是深度定制的需求。企业的工具生态往往是内部系统，接口文档老旧、鉴权方式五花八门、有些还是十几年前的 SOAP。托管平台的工具接入能力再强，也很难覆盖这些奇葩情况。开源的好处是你可以直接改代码，实在不行就在工具适配层写个中间件。

第三类是成本可控。按调用量计费的模式在小规模试点时很香，一旦铺开到几百人日常使用，账单会变得很难看。自托管的前期投入是固定的服务器成本，边际成本接近于零。我粗略算过一笔账：一个中等规模团队每天几千次智能体调用，自托管的月度成本大概是用量的三分之一到二分之一，规模越大差距越明显。

当然，自托管不是没有代价。你要自己负责升级、自己扛故障、自己调性能。所以选型的时候一定要看这个项目的迭代活跃度和文档质量，一个半年不更新的开源项目，再好的架构也别碰。OCE 作为企业发行版，在这方面相对稳一些，它有一个明确的主线版本和 LTS 策略，升级路径是可预期的。

2. OCE 的整体设计与模块拆解

2.1 四层架构：接入、编排、执行、观测

我把 OCE 的架构按职责切成四层，这个切法不是官方文档里的原文，是我自己在部署和读代码过程中整理出来的理解方式，对排查问题特别有用。

接入层负责对外暴露能力，包括 Web 控制台、HTTP API、以及各种渠道的适配器。这一层的关键设计是会话隔离——不同用户、不同渠道进来的请求会被分配到独立的会话上下文里，互不污染。我之前踩过一个坑，两个用户同时用同一个 Agent，上下文串了，A 用户看到 B 用户的订单号，这种事在接入层没做好隔离的时候非常容易发生。

编排层是大脑，负责意图识别、任务规划、工具选择和结果聚合。这一层决定了智能体的行为逻辑，也是各家平台差异最大的地方。OCE 用的是比较经典的"规划-执行-观察"循环，支持多轮工具调用和中间结果的自我修正。编排层还有一个重要的能力是流程编排，也就是把多个 Agent 串成一条工作流，前一个的输出作为后一个的输入，这个在复杂业务里比单个全能 Agent 靠谱得多。

执行层是手脚，包含工具运行时、代码沙箱、模型调用网关。这一层是安全风险最集中的地方，因为所有对外的副作用都从这里发出。OCE 在这里做了比较重的隔离设计，工具调用走独立的进程池，代码执行走容器沙箱，模型调用走统一的网关做限流和计费。

观测层贯穿全局，负责日志、指标、链路追踪。这一层平时感觉不到存在，出事的时候是救命的。我建议部署完之后第一件事就是把观测层接通，别等出了问题再回头补。

四层之间的关系可以用一句话概括：接入层管"谁在跟我说话"，编排层管"我要做什么"，执行层管"我具体怎么做"，观测层管"我刚才做了什么"。排查问题的时候，按这个顺序从上往下找，基本不会迷路。

2.2 运行时设计：会话、上下文与沙箱

会话管理这块，OCE 用的是"会话-任务-步骤"三级结构。一个会话可以包含多个任务，一个任务包含多个步骤。这个粒度设计得比较合理，因为实际业务里用户的诉求往往是连续的，比如"帮我查下上周的订单"接着"那这几个退款的处理一下"，这属于同一个会话下的两个任务。

上下文管理是我认为最值得说的一块。智能体的上下文窗口是有限的，工具返回的内容又往往很长，如果不做裁剪，几轮下来就爆了。OCE 的策略是分层保留：系统提示词和关键约束永久保留，最近 N 轮对话完整保留，更早的对话压缩成摘要，工具返回的大块内容走外部存储、上下文里只留引用和摘要。这个策略实测下来比粗暴截断效果好很多，尤其是在长任务场景下，智能体不会"忘记"最初的目标。

代码沙箱这块要重点说。OCE 支持让智能体写代码并执行，这在数据分析场景里非常有用，但风险也最大。它的沙箱设计有几个关键点：容器隔离、文件系统只读挂载加临时可写目录、网络默认关闭（需要显式开白名单）、CPU 和内存有硬限制、执行超时有强制中断。我在测试的时候特意让它跑了个死循环，15 秒后被干净地杀掉，宿主机没受影响，这个表现是合格的。

提示：沙箱的网络策略千万别图省事设成完全放开。我见过有团队为了让智能体能装 pip 包，直接给了外网访问权限，结果智能体在调试过程中把一个内部服务的健康检查接口刷了几千次。正确做法是配一个内部镜像源，或者提前把常用依赖打进基础镜像。

2.3 模型接入与路由：不把鸡蛋放一个篮子

模型接入层支持两类：一是通过标准协议接入的在线模型服务，二是本地部署的推理服务。OCE 把这块抽象成了统一的 Provider 接口，配置里填地址、密钥、模型名就行，切换模型不需要改业务代码。

我比较欣赏的是它的路由策略设计。你可以按任务类型配不同的模型：简单的意图分类用小模型，复杂的规划用大模型，代码生成用专门的代码模型。这个策略带来的成本优化非常可观。我做过一个对比测试，同一个业务流程，全用大模型跑一轮的成本是 0.42 元/次，按路由策略拆分后降到 0.11 元/次，响应时间还快了将近 40%。原因很简单，大部分步骤其实不需要那么强的模型，用小模型反而更快。

路由还带来一个隐性好处是容灾。主模型服务偶发超时的时候，可以配置自动降级到备用模型，虽然效果会打折扣，但业务不至于直接挂掉。这个配置在线上环境里是必需的，我有一次就靠这个降级策略扛过了一个下午的服务波动。

本地推理服务的接入需要注意显存估算。以 7B 参数模型为例，FP16 精度下权重占约 14GB，加上 KV Cache 和框架开销，实际需要 18GB 左右的显存；INT8 量化后权重约 7GB，总需求降到 11GB 上下；INT4 再砍一半，6GB 左右能跑起来，但复杂推理任务的准确率会有明显下降。我的建议是，如果只是做意图分类和简单抽取，INT8 完全够用；如果要做多步规划，别省这点显存，上 FP16 或者直接走在线服务。

3. 部署实操：一台机器把 OCE 跑起来

3.1 资源估算与参数计算

先把资源账算清楚，别上来就买机器。OCE 的部署形态分两种：轻量单机版和集群版。绝大多数团队从单机版起步就够了，等并发上来了再考虑集群。

单机版的资源需求主要看两件事：模型是走在线服务还是本地部署，以及并发用户数。

如果模型走在线服务，OCE 本体是很轻的。我的测试环境是 8 核 16GB 内存，同时跑控制台、API 服务、任务队列、PostgreSQL、Redis 和一个向量库，峰值内存占用 9.2GB，CPU 峰值 60% 左右。这个配置支撑 50 人左右的团队日常使用没有问题。

并发能力的估算可以按一个简单公式来：所需 worker 数 = 峰值 QPS × 平均单次任务耗时（秒）。举个例子，如果高峰期每分钟有 30 次智能体调用，平均每次任务耗时 8 秒，那么30/60 × 8 = 4，也就是至少需要 4 个 worker 并发处理。留一倍余量，配 8 个 worker 比较稳妥。每个 worker 的内存占用大概 300-500MB，这部分要算进总账里。

如果要在本地跑模型，显存是大头。假设用 7B 模型的 INT8 量化版本，单卡 11GB 起步；如果要支持 8 路并发，KV Cache 会额外吃掉 6-8GB，那就得 24GB 显存的卡。这个账一定要提前算，别等部署完了发现跑不动。

存储方面，PostgreSQL 存业务数据，向量库存知识库索引，两者都需要持久化卷。一个中等规模的知识库（十万级文档块）在向量库里大概占 2-3GB，加上索引膨胀，预留 20GB 比较安全。日志和 trace 数据增长很快，建议单独挂一块盘，按 30 天保留期估算，每天 10 万次调用的量级大概需要 50GB。

3.2 容器化部署的完整步骤

OCE 官方提供的是容器编排方案，我用的是单机容器组合的方式，下面是完整流程。这些步骤我在两台不同配置的机器上验证过，基本可以直接抄。

第一步，装容器运行时和编排工具。版本别太老，我用的是容器引擎 24.x 加编排工具 v2.20 以上，老版本在这个项目上会遇到网络配置的兼容问题。

# 确认版本 docker --version docker compose version

第二步，拉代码并准备配置文件。

git clone <oce-repo-address> oce cd oce/deploy cp .env.example .env

第三步，编辑.env，这是最关键的环节。核心变量大概这几组：

# 基础配置 OCE_HOST=0.0.0.0 OCE_PORT=8000 OCE_SECRET_KEY=<32位以上随机字符串> OCE_LOG_LEVEL=info # 数据库 OCE_DB_URL=postgresql://oce:oce_pass@postgres:5432/oce OCE_REDIS_URL=redis://redis:6379/0 # 向量库 OCE_VECTOR_BACKEND=pgvector OCE_VECTOR_DIM=1024 # 模型接入 OCE_MODEL_PROVIDER=openai_compatible OCE_MODEL_BASE_URL=<你的模型服务地址> OCE_MODEL_API_KEY=<密钥> OCE_MODEL_NAME=<模型名>

OCE_SECRET_KEY这个值千万别用示例里的默认值，它用来签发会话凭证和加密存储的敏感配置，泄露了等于把整个平台交出去。生成方式建议用openssl rand -hex 32。

向量维度OCE_VECTOR_DIM要和你的嵌入模型输出维度严格一致，这个填错了不会报错，但检索结果会完全乱掉，非常隐蔽。我一开始填了 768，结果检索出来的内容驴唇不对马嘴，排查了大半天才发现是这个参数。

第四步，启动服务。

docker compose up -d docker compose ps

正常情况下会起六个容器：oce-api、oce-worker、oce-web、postgres、redis、oce-init。oce-init是一次性的初始化容器，跑完就退出，状态显示Exited (0)是正常的，别以为是挂了。

第五步，初始化数据库和创建管理员账号。

docker compose exec oce-api python -m oce.cli db upgrade docker compose exec oce-api python -m oce.cli create-admin \ --email admin@example.internal \ --password '<强密码>'

第六步，验证。浏览器打开http://<机器IP>:8000，能看到登录页就说明主链路通了。再用命令行确认健康检查接口：

curl -s http://localhost:8000/healthz | jq

返回里应该包含各依赖组件的状态，数据库、缓存、向量库都应该是ok。有任何一项不是ok，先解决它，别急着往下走。

3.3 初始化配置：模型、密钥与存储

服务跑起来只是第一步，真正决定能不能用的是配置。这部分我按优先级排一下。

模型配置要在控制台的模型管理里做，不要直接改数据库。配的时候注意三点：一是超时时间要设，默认值往往偏长，我一般设成 60 秒，超时了快速失败比一直挂着好；二是要配重试策略，网络抖动导致的失败重试两次基本能解决，但要注意幂等，工具调用类的请求不要盲目重试；三是把用量限额配上，防止某个 Agent 跑飞了把额度烧光。

密钥管理是最容易被忽视的一环。OCE 支持把外部系统的凭证存成加密的 Secret，Agent 引用的时候只看到 Secret 的名字，看不到明文。这个机制一定要用起来，绝对不要在 Agent 的提示词或者工具配置里硬编码密钥。我见过太多项目把数据库密码直接写在提示词里，一旦提示词被日志记下来，等于全网公开。

存储配置分两块。知识库的文件存储建议用对象存储而不是本地磁盘，本地磁盘在多副本部署的时候会有一致性问题。向量索引的话，如果是十万级以下的规模，pgvector 就够了，运维成本最低；上了百万级再考虑专门的向量库，因为 pgvector 在这个量级上的检索延迟会明显上升。

还有一块是会话历史存储。默认配置是存在数据库里的，量大了之后表会膨胀得很快。建议配一个定期归档策略，超过 90 天的会话转冷存储，主表只保留近期数据。这个配置不加，跑三个月数据库就能到几十 GB。

3.4 从单机走向集群的注意事项

当单机扛不住的时候，就要考虑集群化。OCE 的集群部署不算复杂，但有几个坑必须提前知道。

第一个坑是会话粘性。智能体的会话上下文是有状态的，如果请求被负载均衡随机打到不同实例上，上下文就断了。解决办法是把会话状态外置到 Redis，或者在负载均衡层做一致性哈希。OCE 支持前者，配置里打开OCE_SESSION_BACKEND=redis就行，这个开关一定要在扩容前打开，否则扩容当天就会出问题。

第二个坑是任务队列的重复消费。多 worker 场景下，如果一个任务处理时间超过了队列的可见性超时，会被另一个 worker 重新捞起来执行，导致重复副作用。解决办法是把超时时间设得比最长任务耗时还长，同时让所有工具调用支持幂等键。这个坑我在一个批量处理场景里踩过，一个任务被执行了三次，重复发了两封通知邮件，非常尴尬。

第三个坑是配置漂移。集群里各实例的配置如果不一致，会出现"有时候能用有时候不能用"的诡异现象。建议所有配置走统一配置中心或者挂载同一份配置卷，别手动改某一台机器。

扩容的时机判断，我的经验是看三个指标：API 的 P95 延迟持续超过 3 秒、任务队列积压持续超过 100 条、CPU 持续高于 70%。任意一个满足了就可以考虑加实例，不要等用户投诉了才动手。

4. 让智能体真正“持证”：权限与审计落地

4.1 智能体身份体系怎么设计

身份体系的设计原则我总结成一句话：一个 Agent 一份身份，一个场景一套权限。听起来简单，执行起来要克制住"图省事直接复用"的冲动。

具体做法上，我建议按业务域划分 Agent，而不是按功能划分。比如"客服域 Agent""运营域 Agent""财务域 Agent"，每个域下面再按细分场景建具体的 Agent 实例。这样划分的好处是权限边界天然清晰，客服域的 Agent 不可能拿到财务数据，从架构上就杜绝了越权。

每个 Agent 的身份信息要包含四个要素：唯一 ID、归属域、责任人、有效期。前三个好理解，第四个"有效期"经常被忽略。很多团队的 Agent 建完就永久有效，人员离职了、业务下线了，Agent 还在跑，凭证还在生效，这是很大的隐患。我的做法是默认给 90 天有效期，到期前自动提醒责任人续期，没人管就自动禁用。

凭证绑定这块要注意最小权限。别用一个超级账号的 Key 给所有 Agent 用。正确做法是为每个 Agent 单独申请服务账号，只授予它实际需要的那几个接口。麻烦是麻烦了点，但出事的时候能精准定位和快速止血。我在一次安全演练里做过对比：权限收敛的 Agent 被诱导越权时，调用直接被网关拒绝；权限放开的 Agent 则成功读到了不该读的数据。这个差别就是设计阶段有没有多花那半小时。

4.2 工具调用的三道闸门

工具调用是智能体产生副作用的地方，也是风险最高的地方。OCE 提供了三层控制机制，我把它叫"三道闸门"，建议全部打开。

第一道闸门是工具白名单。Agent 只能调用注册给它的工具，未注册的工具调用请求直接拒绝。这一层挡住的是"智能体自己发明了一个工具"的情况。别觉得不可能，模型在提示词被污染的情况下确实会尝试调用未定义的工具，虽然多半会失败，但日志里那一堆报错很影响排查。

第二道闸门是参数级约束。光控制"能调哪个工具"不够，还要控制"能用什么参数调"。比如查订单的工具，要约束只能查当前会话用户自己的订单 ID，不能传任意 ID 进去。OCE 支持在工具定义里挂参数校验策略，可以是正则、可以是枚举、也可以是一段自定义的校验逻辑。这个能力非常关键，因为绝大多数数据泄露不是通过"调用了不该调的工具"，而是"调对了工具但传了不该传的参数"。

第三道闸门是人工确认。对于高危操作，比如退款、删除、对外发送，建议配置成需要人工确认。OCE 的做法是把这类调用挂起，推一条确认消息给指定的人，确认后才继续执行。这会牺牲一点效率，但换来的是可控性。我的建议是按金额或者影响范围分级：小额低风险的全自动，超过阈值的走确认，这样既不影响日常效率，又守住了底线。

提示：人工确认的审批人不要设成发起人自己，否则等于没有审核。审批链路要落到具体的岗位角色上，而不是具体的人，这样人员变动时不会断。

4.3 审计日志与全链路追踪

审计这块我想讲一个真实用上的例子。有一次线上反馈说某个数据被改错了，但没人承认操作过。我们从 OCE 的 trace 里捞出了那条记录，发现是一个定时触发的 Agent 在批量处理时，因为上游返回的数据格式变了，把某个字段解析成了空值，然后写回了数据库。整条链路从触发时间、模型决策、工具入参、返回结果到写库操作，全部有记录，十分钟定位到根因。

这个例子说明，审计日志的价值不在于"记录"，而在于"能还原现场"。要做到这一点，日志里必须包含几个关键字段：

字段设计上有个细节要注意：入参出参存摘要不存全量。全量存的话，日志里会混进大量用户隐私数据，合规上过不去，存储成本也扛不住。摘要的做法是保留结构、脱敏值域，比如订单号保留后四位，金额保留量级。

日志的保留策略我建议分三级：热数据 7 天，存在数据库里支持即时查询；温数据 90 天，存对象存储，查询走异步；冷数据按合规要求保留，一般不超过一年。这个分级能显著降低成本，同时不影响日常排查。

追踪这块，OCE 支持标准的链路追踪协议，可以对接主流的可观测平台。我的建议是把 trace 和你现有的监控体系打通，这样智能体的问题能和普通服务的问题放在一起看，排查效率高很多。单独搞一套的话，出问题时要在两个系统之间来回切，很痛苦。

5. 场景验证：三个能立刻跑起来的用法

5.1 内部知识问答：从能答到答得准

这是最容易落地的场景，也是最多团队做砸的场景。做砸的原因通常不是技术问题，而是知识库的质量问题。

我接手过一个知识问答项目，之前的效果很差，用户问三个问题有两个答不准。我看了下他们的知识库，是把整个内部文档系统全量灌进去了，里面有大量过期的、重复的、格式混乱的内容。检索的时候捞出来的全是噪音，模型再好也答不对。

正确的做法是分层处理。第一层做准入筛选，只把权威的、在有效期内的高质量文档纳入，过期的、草稿状态的直接排除。第二层做结构切分，别按固定长度硬切，要按语义边界切，标题、章节、表格各自成块，块与块之间保留层级关系。第三层做元数据标注，每块内容都打上来源、更新时间、适用范围这些标签，检索时可以按标签过滤。

切分粒度的选择上，我的经验值是 300-800 字一块，太短了上下文不够，太长了检索精度下降。对于操作手册类的文档，按步骤切分效果最好；对于政策制度类的，按条款切分效果最好。

配置上还有个关键参数是召回数量。默认召回的 3-5 条往往不够，我一般设成 10 条然后加一个重排序环节，筛出最相关的 3 条给模型。重排序模型的引入让准确率提升非常明显，我测的那批问题里，准确率从 62% 提到了 84%。这个环节值得花时间配。

还有一个容易忽略的点是兜底策略。知识库覆盖不到的问题，一定要让智能体明确说"没有找到相关内容，建议联系某某"，而不是硬编一个答案。我在提示词里加了强约束，并且用测试集专门验证了这块，避免它一本正经地胡说八道。

5.2 工单分派与初筛：把重复劳动干掉

这个场景的投入产出比是我见过最高的。一个中等规模的支撑团队，每天几百个工单，人工分派的准确率和速度都受限于值班人员的经验和状态。

用 OCE 做这件事的流程是：工单进来触发 Agent，Agent 先做意图分类判断类型，然后抽取关键信息（产品、模块、错误码、紧急程度），接着匹配历史相似工单给出初步排查建议，最后根据分类结果分派到对应的处理组。

实现上的关键点是分类体系要和现有流程对齐。别自己重新设计一套分类，直接沿用现有的工单分类标准，否则智能体分出来的结果和工单系统对不上，等于白做。我在配置的时候把现有的分类标准和每个分类的判断依据都写进了提示词，还给了正反例子各三五个，分类准确率能到 85% 以上。

紧急程度的判断要保守。宁可误判成紧急让人工多看一眼，也不能把紧急的判定成普通。我的做法是给紧急判断加一个"存疑就升一级"的规则，牺牲一点准确率换安全。

这块还能做一个延伸：相似工单推荐。把历史工单的处理记录做成知识库，新工单进来时先检索相似的历史案例，把处理方案附在分派信息里。这个功能对一线人员帮助很大，尤其是处理冷门问题的时候。

5.3 数据分析助手：沙箱能力的最佳试验场

这个场景能充分发挥代码沙箱的价值。用户用自然语言提问，智能体先去查数据结构，然后生成查询代码，在沙箱里执行，拿到结果后做可视化和解读。

实测下来有几个经验值得分享。第一是给智能体一份准确的数据字典，表名、字段名、含义、取值范围都写清楚，这比让它自己去猜准确率高太多。第二是强制走只读账号，分析场景永远不需要写权限，这个约束要在数据库层面做死，不能只靠提示词。第三是限制单次查询的资源消耗，加个查询超时和结果集行数上限，防止一条没加条件的查询把数据库拖垮。我配的是 30 秒超时、十万行上限，够用且安全。

生成的代码要做静态检查，把 DROP、DELETE、UPDATE 这类关键字直接拦掉。虽然账号是只读的，双保险没坏处。还有就是执行结果要校验合理性，比如用户问"上个月销售额"，返回了个 0 或者一个明显离谱的数，要提示用户而不是直接展示。我在提示词里加了合理性检查的指令，让它对异常结果做二次确认。

这个场景的实际效果，我测的那批问题里，简单查询（单表聚合、条件筛选）的准确率接近 95%，涉及多表关联和复杂口径的准确率降到 70% 左右。所以定位要清楚：它是给业务人员做快速探索的工具，不是替代专业报表的手段。复杂分析还是要走既有的 BI 流程。

5.4 压测与成本核算：上线前必须做的一笔账

上线前一定要做压测，而且要带着成本一起看。我用的是一个 50 并发、持续 10 分钟的测试脚本，模拟真实用户的操作序列。

结果大概是这样的：平均响应时间 4.2 秒，P95 延迟 11 秒，P99 延迟 23 秒，错误率 0.3%（主要是模型服务的偶发超时）。这个表现在可用范围内，但 P99 偏高，主要原因是复杂规划任务的步骤多，尾延迟拉得比较长。优化方式是给规划步骤设一个最大步数上限，超过就强制收敛，我设的 8 步，P99 降到了 14 秒。

成本方面，我按三种模型配置做了对比：

混合路由的性价比明显最高。我的配置策略是：意图分类和参数抽取用小模型，任务规划和结果生成用大模型，代码生成用专门的代码模型。这个配比在保证效果的前提下把成本压到了四分之一。

还有一笔隐性成本是重试和失败重跑。失败率 1% 听起来不高，但如果失败的任务要重跑三次，实际成本就多了 3%。所以宁可把提示词调好、把工具容错做好，也别指望重试兜底。

6. 踩坑记录与排查速查表

6.1 部署阶段的高频问题

容器起不来，日志里报数据库连接失败。九成是OCE_DB_URL里的主机名写错了，容器间通信用的是服务名不是 localhost。另外检查一下数据库容器是否已经就绪，编排工具虽然支持依赖顺序，但数据库真正可接受连接和容器启动之间有几十秒的差，建议给应用容器配一个健康检查加延迟启动。

控制台能打开但登录后白屏。这个通常是静态资源路径问题，或者反向代理没有正确转发。如果你在前面挂了一层代理，确认X-Forwarded-Proto和X-Forwarded-For这两个头有正确传递，否则应用生成的跳转地址会不对。

初始化脚本报表已存在。说明之前跑过一次没跑完。先手动确认数据库里的迁移版本表，看看停在哪个版本，然后从那个版本继续。别直接删库重来，除非你确定里面没有需要保留的数据。

文件上传失败。检查两处：上传大小限制和存储路径权限。上传大小在配置里和反向代理里都要改，只改一处不生效。存储路径如果挂的是宿主机目录，注意容器内的用户 ID 和宿主机是否一致，权限不匹配会写不进去。

6.2 运行阶段的高频问题

智能体不调用工具，一直在自言自语。这是提示词问题。检查工具的description写得够不够清楚，模型是靠描述来判断什么时候用哪个工具的。描述里要写清楚工具干什么、什么情况下用、参数怎么填。我见过描述只写了个"查询数据"的，模型根本不知道什么时候该用，自然就不调。

工具调用参数格式错误反复重试。模型生成的参数偶尔不符合 schema，重试几次能对上但很浪费。解决办法是在工具定义里给参数加示例，越具体的示例效果越好。另外可以开启参数自动修复，把校验错误回传给模型让它自己改。

上下文超长导致截断。开启上下文分层管理，把长返回的内容外置。同时检查一下是不是有工具返回了超大的结果，比如一个查询返回了几万行，这种情况要在工具层就做限制。

响应特别慢但资源没跑满。大概率是在等模型服务。看一下模型调用的耗时分布，如果是长尾严重，考虑加超时和降级。还有一个可能是流式输出没开，用户要等全部生成完才看到内容，体感上会慢很多。

同一个问题两次回答不一样。这个在智能体场景里是常态，因为工具返回的数据可能变了。如果你需要确定性结果，把温度参数调到 0，并且固定工具返回的排序。

6.3 常见问题速查表

6.4 几条我认为最值钱的经验

第一条，先用最小可用配置跑通全流程，再谈优化。我见过太多团队在部署阶段就纠结用哪个向量库、要不要上集群、模型选哪个，结果两周过去还没跑起来一个 Demo。正确的顺序是先让它跑起来，能回答一个问题，然后再逐步替换组件。

第二条，把提示词当代码管理。提示词的改动对效果影响巨大，必须有版本控制、有测试集、有回归验证。我现在的做法是每个 Agent 的提示词都有独立文件，改完跑一遍固定测试集，准确率掉了就不合并。这个习惯能省掉无数次"昨天还好好的今天怎么就不行了"。

第三条，观测先行。部署完第一件事是把日志和追踪接通，第二件事才是配业务。顺序反了的话，出问题时你只能靠猜。

第四条，别追求全能 Agent。一个能处理所有事情的 Agent，最后往往什么都处理不好。按场景拆分，每个 Agent 职责单一，提示词写得精准，效果反而更好维护也更容易。

第五条，给智能体设边界比给能力更重要。能力可以慢慢加，边界一旦放开就很难收回来。宁可一开始限制得严一点，被业务吐槽几句，也别等出了事故再回头补。

这套东西我在两个不同规模的团队里推过，从最初的"这东西不靠谱"到后来的"离不开"，中间真正的转折点不是模型升级，而是把权限和审计这套基建补齐了。有了这层保障，业务方敢用，安全方敢放，运维方敢维护。技术本身的进步是线性的，但信任的建立是阶跃的，跨过去之后整个事情的性质就变了。

如果你们也准备动手，我的建议是先挑一个数据敏感度最低、流程最标准化的场景做试点，把身份、权限、审计这三件事完整跑一遍。这个过程大概需要两到三周，会有点枯燥，但跑完之后你会对整个体系有完全不同的理解，后面铺开到其他场景就是复制粘贴的事了。