代码代理真正的价值，不是“会写代码”，而是能够在读取文件、搜索仓库、修改源码、执行测试等工具之间形成可靠闭环。对于通过 OpenCode 或 OpenRouter 接入的 Ox Alpha 而言，工具调用参数校验正是这个闭环中的关键防线：它既影响任务能否顺利完成，也决定一次错误调用会停留在接口层，还是演变为误删文件、改错路径或执行危险命令。
参数校验为什么会影响代理成功率
工具调用通常不是模型直接执行操作，而是模型生成工具名称和参数，由宿主程序解析、校验并执行。例如，代理可能提出调用文件编辑工具，并给出目标路径、原始文本和替换内容。根据 OpenRouter 工具调用文档，模型负责提出调用建议，真正的工具执行发生在客户端。因此，客户端不能把模型输出当成可信指令，而应将其视为需要验证的外部输入。
参数校验过于宽松时，格式正确并不代表语义正确。路径可能指向工作区外部，行号可能超出范围，命令参数可能带有破坏性选项，工具名称也可能与当前注册列表不一致。此类调用一旦直接执行，轻则产生无效修改，重则覆盖配置、泄露环境信息或破坏仓库状态。
参数校验过于苛刻同样会降低成功率。如果接口只接受一种绝对固定的字段顺序、拒绝可安全转换的类型，或者把可选字段误设为必填，Ox Alpha 即使理解了任务，也可能因为轻微格式偏差反复调用失败。代理随后会消耗更多上下文进行重试，甚至进入“修参数而不是修代码”的循环。
需要校验的不只是 JSON 格式
第一层是结构校验。每个工具都应通过 JSON Schema、Zod 或同类机制明确字段类型、必填项、枚举值、长度限制和是否允许额外属性。OpenRouter Agent SDK 提供了基于 Zod 的类型安全工具定义，并支持输入与输出校验，可参考 工具定义说明。关闭未声明字段，能够减少模型臆造参数被静默接收的概率。
第二层是语义校验。合法字符串不一定是合法路径，合法命令也不一定适合自动执行。文件参数应完成路径规范化，并确认其仍位于授权工作区内；补丁工具应检查目标文本是否唯一匹配；搜索工具应限制结果数量；命令工具应识别重定向、管道、递归删除和远程下载等高风险行为。
第三层是状态校验。代码代理的调用存在上下文依赖，例如文件可能在读取后被其他进程修改，测试命令可能依赖尚未安装的组件，前一次工具调用也可能已经失败。因此，执行修改前应核对文件版本、哈希或修改时间，避免代理基于过期内容覆盖新变更。
校验如何提高实际任务完成率
良好的校验器不应只返回“参数错误”，而要生成可供模型纠正的结构化反馈，包括错误字段、约束要求、收到的值以及是否允许重试。例如，相比笼统返回“调用失败”，明确说明“path 必须位于项目根目录内，当前路径经过规范化后指向外部目录”，更容易让 Ox Alpha 在下一轮修正调用。
对于可无损修复的问题，可以在执行前进行有限归一化，例如移除路径中的重复分隔符、把整数形式的字符串转换为数字，或为缺省的只读参数补充安全默认值。但系统应把修复后的参数写入审计日志，不能悄悄改变具有业务含义的字段，否则排查问题时难以还原真实调用链。
还应区分“可重试错误”和“不可执行错误”。字段缺失、枚举值错误通常可以反馈给模型重试；越权访问、危险命令或敏感文件读取则应直接阻断，并要求人工审批。这样既避免因小问题中止整个任务，也不会为了表面上的成功率放松安全边界。
降低误操作风险的权限设计
参数合法只说明调用符合接口规则，不代表调用已获授权。OpenCode 将工具操作划分为允许、询问和拒绝三种处理方式，并支持根据工具输入设置细粒度规则，详见 权限配置文档。因此，参数校验应与最小权限、工作区隔离和人工审批共同使用。
- 读写分离：默认允许读取普通源码，对写入、覆盖和补丁操作要求更严格的路径校验。
- 命令分级：自动放行状态查询和测试命令，对安装依赖、网络访问、删除、发布及推送操作要求审批。
- 目录隔离：拒绝访问项目目录外的路径，并单独保护密钥文件、环境变量文件和版本控制凭据。
- 结果复核：修改后必须展示差异并运行限定范围的测试，不能仅凭工具返回成功就判断任务完成。
- 循环熔断：同一工具以相同参数连续失败时停止自动重试，转为重新规划或请求人工介入。
如何评估校验策略是否有效
团队不宜只统计代理最终是否给出答案，而应观察完整工具链。建议记录参数解析失败率、语义校验拒绝率、自动纠正成功率、平均重试次数、人工审批比例、补丁回滚次数和危险调用拦截情况。测试集应同时包含正常任务、缺失字段、错误类型、路径穿越、重复补丁、超长参数及命令注入等场景。
评估时还要避免把所有拒绝都算作失败。一次危险调用被正确拦截，虽然没有完成模型原计划，却属于安全系统的成功。更合理的目标是同时衡量任务完成质量与风险控制效果，并通过失败原因分类找到模型、工具描述、参数模式或权限规则中的真实瓶颈，而不是单纯追求更高的自动执行比例。
总结
Ox Alpha 的代码能力决定了它能提出多好的方案，参数校验则决定这些方案能否安全地转化为真实操作。高质量的实现应覆盖结构、语义、状态和权限四个层次，为可修复错误提供精确反馈，对越权和高风险行为保持强制阻断，再配合差异审查、测试验证与审计日志。参数校验不是拖慢代理的额外步骤，而是提升有效成功率、减少无效重试并控制误操作范围的基础设施。
