如果一个表单有 30 个字段每周还要重复填三次靠人工操作不仅慢还容易在必填项、格式校验和提交时机上出错。Codex 和 Claude Code 这类终端里的 AI 智能体价值正好体现在这种“规则明确、重复度高、容错率低”的任务上让模型读取目标页面的结构按约定规则填充字段再检查提交结果。接下来按安装、认证、Skill 配置、表单自动化示例和报错排查这条链路逐步说明怎么在真实项目里用起来。1. 先理解 Codex 和 Claude Code 是做什么的1.1 它们是终端里的 AI 智能体不是普通补全插件很多人第一次听到 Codex 和 Claude Code会本能地拿它们和 IDE 里的代码补全插件比较。这个理解方向不对。代码补全插件的核心能力是“在你写代码时预测下一段内容”它不会主动去读整个项目、执行命令、修改文件、观察运行结果。而 Codex CLI 和 Claude Code 是运行在终端里的智能体程序你给它一个目标它可以自行阅读项目文件、搜索代码、执行 Shell 命令、编辑文件并在多个步骤之间反复核对结果。举一个最简单的例子# 让智能体完成一个任务而不是面向单次补全 codex exec 把 config.py 里所有超时的默认值改成 30并更新注释 # Claude Code 进入交互式会话 claude用户提供的是“目标”模型负责把目标拆解成步骤并且每一步都保留上下文。这种工作方式决定了它适合处理的不只是写代码也包括批量修改配置、整理目录、生成脚本以及本文要重点讲的“按规则自动填表”。1.2 自动填表场景为什么适合交给 AI 智能体表单填写看起来简单实际包含一系列细小步骤知道每个字段的类型是文本框、下拉框、单选还是多选。知道每个字段的格式要求比如手机号、日期、金额。知道哪些字段是必填哪些字段有联动关系。填充之后还要检查是否成功再决定是否提交。这些步骤的特点是“规则明确、重复性高”但实现起来琐碎。人的优势是灵活劣势是重复操作容易疲劳、看错字段。普通脚本的优势是稳定劣势是页面只要改一点结构脚本就全部失效。AI 智能体处于两者之间它可以根据页面实际情况生成或修改操作脚本也能把“填表”这件事抽象成一组可以复用的规则。换句话说它的价值不是替你手填一次而是把“如何正确填表”的方法沉淀成 Skill 或指令之后每次遇到同类表单都能按同一套逻辑执行。1.3 两者的定位差异决定你用哪一个Codex 和 Claude Code 并不互斥。实际项目中有人两个都装遇到不同任务切换使用也有人只装其中一个。下面这张表可以帮助你快速判断对比项Codex CLIClaude Code开发方OpenAI 旗下的代码智能体工具Anthropic 旗下的终端智能体工具安装方式npm 全局安装npm 全局安装主要交互模式codex交互式会话、codex exec非交互模式claude交互式会话、权限确认机制记忆机制通过 AGENTS.md 等说明文件约束行为通过 CLAUDE.md 和 Skill 组织长期指令扩展方式自定义说明文件、Skill、外部命令Skill、Slash Command、脚本擅长场景代码库分析、批量修改、执行测试多文件修改、长任务跟踪、工程级重构这张表只描述常见使用方式。具体到某个版本命令名和配置路径可能有差异落地前先看本机版本的--help输出。2. 环境准备与安装先把两个 CLI 跑起来2.1 安装前先检查本机环境Codex 和 Claude Code 都通过 npm 分发所以本机必须能运行 Node.js 环境。常见要求是 Node.js 18 或更高版本具体以你安装的 CLI 版本对应 README 为准。在终端执行node -v npm -v如果 node 或 npm 不存在需要先安装 Node.js。生产服务器上建议通过 nvm 这类版本管理工具安装避免全局目录权限问题。Windows 用户还要注意PowerShell 和 CMD 对全局 npm 包路径的处理方式不同安装后出现“命令找不到”时先检查 npm 全局 bin 目录是否在 PATH 中。2.2 安装 Codex CLICodex CLI 的 npm 包名是openai/codex官方一般推荐 npm 全局安装npm install -g openai/codex安装完成后验证codex --version如果codex命令不存在先执行npm config get prefix确认输出目录是否在系统 PATH 中。部分平台还需要配置 npm 全局目录的写权限否则会报 EACCES 错误。Codex 的官方仓库也提供一键安装脚本适合不想通过 npm 管理的情况。具体脚本内容以仓库 README 为准这里不展开因为大多数场景下 npm 安装已经够用。2.3 安装 Claude CodeClaude Code 的 npm 包名是anthropic-ai/claude-codenpm install -g anthropic-ai/claude-code验证claude --version需要升级时使用 Claude Code 自带的更新命令claude update不建议在全局目录里直接拉取最新 npm 包覆盖因为 Claude Code 的运行依赖和权限模型会随版本调整先用claude --help确认当前版本支持哪些参数。2.4 安装完必须做的三项确认安装成功不等于可以正常使用。建议按顺序检查# 1. 确认命令能解析到正确路径 which codex which claude # 2. 确认版本号正常输出 codex --version claude --version # 3. 确认帮助信息可以查看 codex --help claude --help这里最容易踩的坑是“安装成功但命令不存在”。原因通常是 npm 全局目录没有被加入 PATH或者本机同时存在多个 Node 版本全局包装到了另一个版本的目录下。3. 认证与模型接入配置对了才能发起请求3.1 官方订阅登录方式Codex 和 Claude Code 的第一种接入方式是使用官方账号登录。Codex CLI 在交互会话中输入codex login按提示在浏览器里完成授权之后 CLI 会保存登录令牌。Claude Code 启动时如果检测到账号已订阅 Claude会要求授权确认后即可使用。codex loginclaude第一种方式适合个人日常使用配置最少风险和账号绑定。3.2 使用 API Key 方式团队或自动化环境里登录浏览器授权不方便通常会改用 API Key。Claude Code 比较常见的是通过环境变量指定export ANTHROPIC_API_KEY你的 API Key claudeCodex 则看版本支持情况有的版本通过codex login的扩展参数传入 API Key有的版本直接在环境变量里配置。具体参数名以本机codex login --help输出为准。codex login --help需要提醒的是API Key 是敏感信息不要写进项目代码或提交到 Git 仓库。建议通过 shell profile、CI 的 secrets 或专用的密钥管理工具注入。3.3 接入第三方模型接口时的注意点实际项目中很多人为了让 Codex 或 Claude Code 使用其他模型服务会配置自定义接口地址和模型名。这种做法本身没有问题但配置时要确认三件事接口地址是否兼容 Codex / Claude Code 的请求格式。模型名必须与接口服务支持的标识完全一致。接口服务是否支持流式响应、工具调用等智能体必需的能力。常见配置文件路径如下具体以本机版本为准Codex~/.codex/config.tomlClaude Code~/.claude/settings.json修改配置文件后要重启 CLI 会话再验证。如果发现配置没生效先检查是否改对了用户目录再检查进程是否真的完全退出。这里有一个高频坑模型名写错或写成一个不存在的版本启动时不会立刻报错但真正发请求时会出现“model not recognized”或 400 错误。后面第 6 节会专门处理这类报错。4. 用 Skill 把“自动填表”变成可复用能力4.1 Skill 机制是什么自动填表如果只是每次现场写一段提示词效率并不高。更好的做法是把填表方法封装成一个 Skill。Skill 本质上是“一组结构化的指令文件加可选脚本”放在固定目录里。智能体在启动时或收到相关指令时会读取 Skill 内容从而获得一套固定的执行规则。Claude Code 的项目级 Skill 通常放在.claude/skills/用户级 Skill 放在~/.claude/skills/Codex 也有类似的说明文件和 Skill 目录约定。举例目录结构大致是form-fill/ SKILL.md # 填表规则和操作方法 rules.json # 字段校验规则 fill_form.py # 可选操作浏览器页面的辅助脚本SKILL.md 是核心。它用 Markdown 描述这个技能在什么场景下使用、需要哪些输入、执行时要注意什么。4.2 编写一个自动填表 Skill下面是一个最小可用的SKILL.md示例实际项目要结合你自己的目录、页面和字段调整--- name: form-fill description: 根据 JSON 数据自动填写网页表单支持文本框、下拉框、单选和多选 --- # 自动填表技能 ## 使用场景 - 用户提供表单页面地址和 JSON 数据文件。 - 目标是按规则填充字段并校验提交结果。 ## 执行步骤 1. 读取 JSON 数据文件确认字段名。 2. 打开目标页面等待表单元素加载完成。 3. 对每个字段执行以下动作 - 文本框获取元素清空后填入数据。 - 下拉框按 option 的 value 或可见文本选择。 - 单选/复选按 label 或 value 点击。 4. 填写完成后重新读取页面值进行比对。 5. 比对通过后再点击提交按钮。 6. 截图或读取提交结果页确认是否成功。 7. 若出现校验失败将错误信息写入日志文件。 ## 注意事项 - 不要把伪造数据提交到真实业务系统除非已获得授权。 - 提交前必须做二次校验不能盲目点击。 - 页面元素找不到时输出页面截图和可用的元素列表便于定位。这个 Skill 的核心价值是约束“填表的顺序和检查时机”。没有这类规则时模型可能直接写脚本提交省略校验环节有了规则后每一步都必须按顺序执行。4.3 在 Codex 中使用 SkillCodex 运行时会读取项目内的说明文件比如 AGENTS.md也可以在其中引用 Skill 目录。使用方式类似codex exec 用 form-fill 技能填写 https://example.com/form data/test.json也可以先进入交互式会话codex然后在会话里输入同样的目标。Codex 会读取 Skill 内容再结合页面结构和数据文件生成执行方案。如果发现 Skill 没有被加载优先检查目录路径是否在 Codex 的搜索范围内以及 SKILL.md 头部的name和description是否写对。很多智能体只通过字段描述决定是否匹配技能描述写得含糊它就不会主动调用。4.4 在 Claude Code 中使用 SkillClaude Code 同样可以读取 Skill 文件。项目里常见的操作是claude进入会话后把 SKILL.md 所在目录加入上下文/add-dir .claude/skills/form-fill然后直接给出任务读取 data/test.json按 form-fill 技能填写 https://example.com/formClaude Code 会先确认行为是否被允许。对于涉及执行脚本、写文件、网络请求的操作它会向用户请求权限。第一次运行建议选择允许本次而不是永久允许等确认脚本安全后再调整权限策略。4.5 Skill 配置的关键参数速查配置项作用建议值或写法nameSkill 的唯一名称简短小写连字符如form-filldescription决定模型何时调用这个 Skill写清楚触发场景和入参执行步骤规定填表顺序和校验点必须包含“填充后校验”和“提交前确认”脚本位置可执行辅助脚本显式声明运行方式和依赖适用页面限定 Skill 生效范围明确页面和字段名避免误用5. 最小可复现的自动填表示例5.1 准备测试数据和表单页面假设测试页面是一个内部演示表单包含姓名、邮箱、日期、城市下拉框和“同意协议”复选框。数据用 JSON 文件管理{ name: 张三, email: zhangsanexample.com, date: 2025-01-10, city: beijing, agree: true }这里的关键是字段名和页面上表单元素的id或name保持一致。如果页面字段名与数据字段名不一致要么在数据层映射要么在脚本里做别名映射否则填表很容易错位。5.2 用 Playwright 生成填表脚本骨架Skill 描述的是规则真正执行时通常还需要一个操作浏览器的脚本。下面用 Python 和 Playwright 做一个骨架示例# fill_form.py import json import sys from playwright.sync_api import sync_playwright FORM_URL sys.argv[1] DATA_FILE sys.argv[2] with open(DATA_FILE, r, encodingutf-8) as f: data json.load(f) with sync_playwright() as p: browser p.chromium.launch(headlessFalse) page browser.new_page() page.goto(FORM_URL) page.wait_for_load_state(networkidle) # 文本框姓名、邮箱、日期 page.fill(#form-name, data[name]) page.fill(#form-email, data[email]) page.fill(#form-date, data[date]) # 下拉框按 value 选择城市 page.select_option(#form-city, data[city]) # 复选框根据数据决定是否勾选 if data.get(agree): page.check(#form-agree) # 填充后回读做二次校验 actual_name page.input_value(#form-name) if actual_name ! data[name]: raise RuntimeError(姓名填写校验失败) # 提交前截图便于排查 page.screenshot(pathbefore_submit.png) # 校验通过后再提交 page.click(#form-submit) page.wait_for_load_state(networkidle) browser.close()这段代码只演示核心思路。生产环境里选择器不能硬编码成这样因为页面结构一旦变化脚本就会失效。更稳妥的方式是优先使用>pip install playwright playwright install chromium python fill_form.py https://example.com/form data/test.json正常运行时会看到浏览器打开、字段填充、截图、提交的整个流程。提交后脚本退出码为 0并且before_submit.png里能看到填写完成的表单。如果页面元素找不到Playwright 会抛出超时异常错误信息里会包含选择器和等待时长。这时候先去浏览器开发者工具里确认真实 DOM再回到脚本里修正 selector而不是反复重试同一个选择器。5.4 批量填表时的数据组织一次填一个表单的意义有限重点是批量。批量场景下常见做法是python fill_form.py https://example.com/form data/2025-01-10.json python fill_form.py https://example.com/form data/2025-01-11.json也可以由 Skill 读取整个目录对每个 JSON 文件执行一次填表流程并将每次结果写入单独的日志文件。注意批量执行时页面上的日期、编号等字段必须变化否则可能触发重复提交校验。6. 高频报错与排查思路6.1 切换模型后请求返回 400使用社区模型切换工具时常会遇到这样的日志片段处理 codex endpoint /responses 时失败 provider: deepseek model: deepseek-v4-flash upstream_status: http 400 cause: thinking 模式下reasoning_content 必须回传给 API这段日志的含义是请求经过本地转发服务转发给模型接口时上游返回了 400。具体原因是模型开启了 thinking 推理模式但后续请求没有把上一次的reasoning_content回传给接口导致上游拒绝。排查顺序先关闭不需要的推理模式再看是否还会报错。检查转发服务版本确认它是否正确透传reasoning_content字段。换用该接口明确支持的模型名避免使用演示字段里的模型标识。打开上游接口的完整响应日志看 400 的具体 body而不是只看状态码。这类问题多数不是 Codex 或 Claude Code 本身的问题而是“CLI 版本、转发服务版本、模型接口格式”三者之间的版本匹配问题。6.2 模型名称不被当前版本识别典型报错deepseek-v4-pro is not a model this version of claude code recognizes原因很直接CLI 版本内置的模型列表里没有这个名字或者接口服务并不存在该模型。处理办法用claude --version确认版本再升级到支持该模型的新版本。检查模型名拼写包括大小写和连字符。到模型接口服务的管理后台确认实际可用的模型标识。不要为了消除报错随便改模型名改完要实际发一次请求验证。6.3 组织订阅被禁用报错原文类似your organization has disabled claude subscription access for claude code这种情况是账号所属组织的管理员在后台关闭了 Claude 订阅对 Claude Code 的访问权限。个人无法通过配置绕过正确做法是联系组织管理员在订阅设置里开启对应权限。自动化部署环境里也可以改用 API Key 计费方式绕开订阅权限限制。6.4 地区不可用提示如果启动时出现类似“Claude Code 在您所在地区可能不可用”的提示说明当前账号或环境不在官方支持范围内。正确做法是先查阅官方支持地区说明确认是否真的可用再决定是否继续。不要使用任何绕过地区限制的方式这类操作既不符合官方条款也会带来账号风险。6.5 报错排查优先级参考问题现象常见原因检查方式处理建议命令不存在npm 全局目录不在 PATHwhich codex、npm config get prefix修正 PATH或重装 Node 版本管理工具登录后仍无法使用订阅或 API Key 未生效查看 CLI 认证状态重新登录或切换 API Key 方式模型名不被识别版本过旧或拼写错误claude --version查看接口支持列表升级 CLI修正模型标识请求返回 400请求格式与上游接口不匹配查看上游完整响应 body关闭推理模式或升级转发服务Skill 未加载目录路径或 description 不对检查目录、名称、描述修正 SKILL.md 头部字段填表后校验失败字段映射或选择器错误截图、打印回读值使用稳定选择器和字段映射7. 实际项目中的最佳实践7.1 学习环境与生产环境要分开对待本地尝试自动填表时应该使用演示系统或自有测试系统不要拿真实业务表单反复实验。学习阶段可以这样做用本机 Docker 起一个测试页面构造各种字段类型。允许 CLI 交互式确认权限。不断调整 Skill 规则观察模型行为变化。生产环境则需要额外补齐日志记录每次填表的数据、页面、提交结果和错误堆栈。权限运行脚本的账号严格限制数据读取范围。监控提交失败要有告警不能静默失败。回滚批量填表前先备份原始数据。合规确认填写对象的授权范围和数据处理要求数据来源不明时不要批量提交。7.2 自动填表项目最常踩的坑坑一把页面选择器写死在脚本里。页面重构一次脚本就全崩。建议优先使用稳定的> 终端AI智能体Codex与Claude Code表单自动填充实战指南
如果一个表单有 30 个字段每周还要重复填三次靠人工操作不仅慢还容易在必填项、格式校验和提交时机上出错。Codex 和 Claude Code 这类终端里的 AI 智能体价值正好体现在这种“规则明确、重复度高、容错率低”的任务上让模型读取目标页面的结构按约定规则填充字段再检查提交结果。接下来按安装、认证、Skill 配置、表单自动化示例和报错排查这条链路逐步说明怎么在真实项目里用起来。1. 先理解 Codex 和 Claude Code 是做什么的1.1 它们是终端里的 AI 智能体不是普通补全插件很多人第一次听到 Codex 和 Claude Code会本能地拿它们和 IDE 里的代码补全插件比较。这个理解方向不对。代码补全插件的核心能力是“在你写代码时预测下一段内容”它不会主动去读整个项目、执行命令、修改文件、观察运行结果。而 Codex CLI 和 Claude Code 是运行在终端里的智能体程序你给它一个目标它可以自行阅读项目文件、搜索代码、执行 Shell 命令、编辑文件并在多个步骤之间反复核对结果。举一个最简单的例子# 让智能体完成一个任务而不是面向单次补全 codex exec 把 config.py 里所有超时的默认值改成 30并更新注释 # Claude Code 进入交互式会话 claude用户提供的是“目标”模型负责把目标拆解成步骤并且每一步都保留上下文。这种工作方式决定了它适合处理的不只是写代码也包括批量修改配置、整理目录、生成脚本以及本文要重点讲的“按规则自动填表”。1.2 自动填表场景为什么适合交给 AI 智能体表单填写看起来简单实际包含一系列细小步骤知道每个字段的类型是文本框、下拉框、单选还是多选。知道每个字段的格式要求比如手机号、日期、金额。知道哪些字段是必填哪些字段有联动关系。填充之后还要检查是否成功再决定是否提交。这些步骤的特点是“规则明确、重复性高”但实现起来琐碎。人的优势是灵活劣势是重复操作容易疲劳、看错字段。普通脚本的优势是稳定劣势是页面只要改一点结构脚本就全部失效。AI 智能体处于两者之间它可以根据页面实际情况生成或修改操作脚本也能把“填表”这件事抽象成一组可以复用的规则。换句话说它的价值不是替你手填一次而是把“如何正确填表”的方法沉淀成 Skill 或指令之后每次遇到同类表单都能按同一套逻辑执行。1.3 两者的定位差异决定你用哪一个Codex 和 Claude Code 并不互斥。实际项目中有人两个都装遇到不同任务切换使用也有人只装其中一个。下面这张表可以帮助你快速判断对比项Codex CLIClaude Code开发方OpenAI 旗下的代码智能体工具Anthropic 旗下的终端智能体工具安装方式npm 全局安装npm 全局安装主要交互模式codex交互式会话、codex exec非交互模式claude交互式会话、权限确认机制记忆机制通过 AGENTS.md 等说明文件约束行为通过 CLAUDE.md 和 Skill 组织长期指令扩展方式自定义说明文件、Skill、外部命令Skill、Slash Command、脚本擅长场景代码库分析、批量修改、执行测试多文件修改、长任务跟踪、工程级重构这张表只描述常见使用方式。具体到某个版本命令名和配置路径可能有差异落地前先看本机版本的--help输出。2. 环境准备与安装先把两个 CLI 跑起来2.1 安装前先检查本机环境Codex 和 Claude Code 都通过 npm 分发所以本机必须能运行 Node.js 环境。常见要求是 Node.js 18 或更高版本具体以你安装的 CLI 版本对应 README 为准。在终端执行node -v npm -v如果 node 或 npm 不存在需要先安装 Node.js。生产服务器上建议通过 nvm 这类版本管理工具安装避免全局目录权限问题。Windows 用户还要注意PowerShell 和 CMD 对全局 npm 包路径的处理方式不同安装后出现“命令找不到”时先检查 npm 全局 bin 目录是否在 PATH 中。2.2 安装 Codex CLICodex CLI 的 npm 包名是openai/codex官方一般推荐 npm 全局安装npm install -g openai/codex安装完成后验证codex --version如果codex命令不存在先执行npm config get prefix确认输出目录是否在系统 PATH 中。部分平台还需要配置 npm 全局目录的写权限否则会报 EACCES 错误。Codex 的官方仓库也提供一键安装脚本适合不想通过 npm 管理的情况。具体脚本内容以仓库 README 为准这里不展开因为大多数场景下 npm 安装已经够用。2.3 安装 Claude CodeClaude Code 的 npm 包名是anthropic-ai/claude-codenpm install -g anthropic-ai/claude-code验证claude --version需要升级时使用 Claude Code 自带的更新命令claude update不建议在全局目录里直接拉取最新 npm 包覆盖因为 Claude Code 的运行依赖和权限模型会随版本调整先用claude --help确认当前版本支持哪些参数。2.4 安装完必须做的三项确认安装成功不等于可以正常使用。建议按顺序检查# 1. 确认命令能解析到正确路径 which codex which claude # 2. 确认版本号正常输出 codex --version claude --version # 3. 确认帮助信息可以查看 codex --help claude --help这里最容易踩的坑是“安装成功但命令不存在”。原因通常是 npm 全局目录没有被加入 PATH或者本机同时存在多个 Node 版本全局包装到了另一个版本的目录下。3. 认证与模型接入配置对了才能发起请求3.1 官方订阅登录方式Codex 和 Claude Code 的第一种接入方式是使用官方账号登录。Codex CLI 在交互会话中输入codex login按提示在浏览器里完成授权之后 CLI 会保存登录令牌。Claude Code 启动时如果检测到账号已订阅 Claude会要求授权确认后即可使用。codex loginclaude第一种方式适合个人日常使用配置最少风险和账号绑定。3.2 使用 API Key 方式团队或自动化环境里登录浏览器授权不方便通常会改用 API Key。Claude Code 比较常见的是通过环境变量指定export ANTHROPIC_API_KEY你的 API Key claudeCodex 则看版本支持情况有的版本通过codex login的扩展参数传入 API Key有的版本直接在环境变量里配置。具体参数名以本机codex login --help输出为准。codex login --help需要提醒的是API Key 是敏感信息不要写进项目代码或提交到 Git 仓库。建议通过 shell profile、CI 的 secrets 或专用的密钥管理工具注入。3.3 接入第三方模型接口时的注意点实际项目中很多人为了让 Codex 或 Claude Code 使用其他模型服务会配置自定义接口地址和模型名。这种做法本身没有问题但配置时要确认三件事接口地址是否兼容 Codex / Claude Code 的请求格式。模型名必须与接口服务支持的标识完全一致。接口服务是否支持流式响应、工具调用等智能体必需的能力。常见配置文件路径如下具体以本机版本为准Codex~/.codex/config.tomlClaude Code~/.claude/settings.json修改配置文件后要重启 CLI 会话再验证。如果发现配置没生效先检查是否改对了用户目录再检查进程是否真的完全退出。这里有一个高频坑模型名写错或写成一个不存在的版本启动时不会立刻报错但真正发请求时会出现“model not recognized”或 400 错误。后面第 6 节会专门处理这类报错。4. 用 Skill 把“自动填表”变成可复用能力4.1 Skill 机制是什么自动填表如果只是每次现场写一段提示词效率并不高。更好的做法是把填表方法封装成一个 Skill。Skill 本质上是“一组结构化的指令文件加可选脚本”放在固定目录里。智能体在启动时或收到相关指令时会读取 Skill 内容从而获得一套固定的执行规则。Claude Code 的项目级 Skill 通常放在.claude/skills/用户级 Skill 放在~/.claude/skills/Codex 也有类似的说明文件和 Skill 目录约定。举例目录结构大致是form-fill/ SKILL.md # 填表规则和操作方法 rules.json # 字段校验规则 fill_form.py # 可选操作浏览器页面的辅助脚本SKILL.md 是核心。它用 Markdown 描述这个技能在什么场景下使用、需要哪些输入、执行时要注意什么。4.2 编写一个自动填表 Skill下面是一个最小可用的SKILL.md示例实际项目要结合你自己的目录、页面和字段调整--- name: form-fill description: 根据 JSON 数据自动填写网页表单支持文本框、下拉框、单选和多选 --- # 自动填表技能 ## 使用场景 - 用户提供表单页面地址和 JSON 数据文件。 - 目标是按规则填充字段并校验提交结果。 ## 执行步骤 1. 读取 JSON 数据文件确认字段名。 2. 打开目标页面等待表单元素加载完成。 3. 对每个字段执行以下动作 - 文本框获取元素清空后填入数据。 - 下拉框按 option 的 value 或可见文本选择。 - 单选/复选按 label 或 value 点击。 4. 填写完成后重新读取页面值进行比对。 5. 比对通过后再点击提交按钮。 6. 截图或读取提交结果页确认是否成功。 7. 若出现校验失败将错误信息写入日志文件。 ## 注意事项 - 不要把伪造数据提交到真实业务系统除非已获得授权。 - 提交前必须做二次校验不能盲目点击。 - 页面元素找不到时输出页面截图和可用的元素列表便于定位。这个 Skill 的核心价值是约束“填表的顺序和检查时机”。没有这类规则时模型可能直接写脚本提交省略校验环节有了规则后每一步都必须按顺序执行。4.3 在 Codex 中使用 SkillCodex 运行时会读取项目内的说明文件比如 AGENTS.md也可以在其中引用 Skill 目录。使用方式类似codex exec 用 form-fill 技能填写 https://example.com/form data/test.json也可以先进入交互式会话codex然后在会话里输入同样的目标。Codex 会读取 Skill 内容再结合页面结构和数据文件生成执行方案。如果发现 Skill 没有被加载优先检查目录路径是否在 Codex 的搜索范围内以及 SKILL.md 头部的name和description是否写对。很多智能体只通过字段描述决定是否匹配技能描述写得含糊它就不会主动调用。4.4 在 Claude Code 中使用 SkillClaude Code 同样可以读取 Skill 文件。项目里常见的操作是claude进入会话后把 SKILL.md 所在目录加入上下文/add-dir .claude/skills/form-fill然后直接给出任务读取 data/test.json按 form-fill 技能填写 https://example.com/formClaude Code 会先确认行为是否被允许。对于涉及执行脚本、写文件、网络请求的操作它会向用户请求权限。第一次运行建议选择允许本次而不是永久允许等确认脚本安全后再调整权限策略。4.5 Skill 配置的关键参数速查配置项作用建议值或写法nameSkill 的唯一名称简短小写连字符如form-filldescription决定模型何时调用这个 Skill写清楚触发场景和入参执行步骤规定填表顺序和校验点必须包含“填充后校验”和“提交前确认”脚本位置可执行辅助脚本显式声明运行方式和依赖适用页面限定 Skill 生效范围明确页面和字段名避免误用5. 最小可复现的自动填表示例5.1 准备测试数据和表单页面假设测试页面是一个内部演示表单包含姓名、邮箱、日期、城市下拉框和“同意协议”复选框。数据用 JSON 文件管理{ name: 张三, email: zhangsanexample.com, date: 2025-01-10, city: beijing, agree: true }这里的关键是字段名和页面上表单元素的id或name保持一致。如果页面字段名与数据字段名不一致要么在数据层映射要么在脚本里做别名映射否则填表很容易错位。5.2 用 Playwright 生成填表脚本骨架Skill 描述的是规则真正执行时通常还需要一个操作浏览器的脚本。下面用 Python 和 Playwright 做一个骨架示例# fill_form.py import json import sys from playwright.sync_api import sync_playwright FORM_URL sys.argv[1] DATA_FILE sys.argv[2] with open(DATA_FILE, r, encodingutf-8) as f: data json.load(f) with sync_playwright() as p: browser p.chromium.launch(headlessFalse) page browser.new_page() page.goto(FORM_URL) page.wait_for_load_state(networkidle) # 文本框姓名、邮箱、日期 page.fill(#form-name, data[name]) page.fill(#form-email, data[email]) page.fill(#form-date, data[date]) # 下拉框按 value 选择城市 page.select_option(#form-city, data[city]) # 复选框根据数据决定是否勾选 if data.get(agree): page.check(#form-agree) # 填充后回读做二次校验 actual_name page.input_value(#form-name) if actual_name ! data[name]: raise RuntimeError(姓名填写校验失败) # 提交前截图便于排查 page.screenshot(pathbefore_submit.png) # 校验通过后再提交 page.click(#form-submit) page.wait_for_load_state(networkidle) browser.close()这段代码只演示核心思路。生产环境里选择器不能硬编码成这样因为页面结构一旦变化脚本就会失效。更稳妥的方式是优先使用>pip install playwright playwright install chromium python fill_form.py https://example.com/form data/test.json正常运行时会看到浏览器打开、字段填充、截图、提交的整个流程。提交后脚本退出码为 0并且before_submit.png里能看到填写完成的表单。如果页面元素找不到Playwright 会抛出超时异常错误信息里会包含选择器和等待时长。这时候先去浏览器开发者工具里确认真实 DOM再回到脚本里修正 selector而不是反复重试同一个选择器。5.4 批量填表时的数据组织一次填一个表单的意义有限重点是批量。批量场景下常见做法是python fill_form.py https://example.com/form data/2025-01-10.json python fill_form.py https://example.com/form data/2025-01-11.json也可以由 Skill 读取整个目录对每个 JSON 文件执行一次填表流程并将每次结果写入单独的日志文件。注意批量执行时页面上的日期、编号等字段必须变化否则可能触发重复提交校验。6. 高频报错与排查思路6.1 切换模型后请求返回 400使用社区模型切换工具时常会遇到这样的日志片段处理 codex endpoint /responses 时失败 provider: deepseek model: deepseek-v4-flash upstream_status: http 400 cause: thinking 模式下reasoning_content 必须回传给 API这段日志的含义是请求经过本地转发服务转发给模型接口时上游返回了 400。具体原因是模型开启了 thinking 推理模式但后续请求没有把上一次的reasoning_content回传给接口导致上游拒绝。排查顺序先关闭不需要的推理模式再看是否还会报错。检查转发服务版本确认它是否正确透传reasoning_content字段。换用该接口明确支持的模型名避免使用演示字段里的模型标识。打开上游接口的完整响应日志看 400 的具体 body而不是只看状态码。这类问题多数不是 Codex 或 Claude Code 本身的问题而是“CLI 版本、转发服务版本、模型接口格式”三者之间的版本匹配问题。6.2 模型名称不被当前版本识别典型报错deepseek-v4-pro is not a model this version of claude code recognizes原因很直接CLI 版本内置的模型列表里没有这个名字或者接口服务并不存在该模型。处理办法用claude --version确认版本再升级到支持该模型的新版本。检查模型名拼写包括大小写和连字符。到模型接口服务的管理后台确认实际可用的模型标识。不要为了消除报错随便改模型名改完要实际发一次请求验证。6.3 组织订阅被禁用报错原文类似your organization has disabled claude subscription access for claude code这种情况是账号所属组织的管理员在后台关闭了 Claude 订阅对 Claude Code 的访问权限。个人无法通过配置绕过正确做法是联系组织管理员在订阅设置里开启对应权限。自动化部署环境里也可以改用 API Key 计费方式绕开订阅权限限制。6.4 地区不可用提示如果启动时出现类似“Claude Code 在您所在地区可能不可用”的提示说明当前账号或环境不在官方支持范围内。正确做法是先查阅官方支持地区说明确认是否真的可用再决定是否继续。不要使用任何绕过地区限制的方式这类操作既不符合官方条款也会带来账号风险。6.5 报错排查优先级参考问题现象常见原因检查方式处理建议命令不存在npm 全局目录不在 PATHwhich codex、npm config get prefix修正 PATH或重装 Node 版本管理工具登录后仍无法使用订阅或 API Key 未生效查看 CLI 认证状态重新登录或切换 API Key 方式模型名不被识别版本过旧或拼写错误claude --version查看接口支持列表升级 CLI修正模型标识请求返回 400请求格式与上游接口不匹配查看上游完整响应 body关闭推理模式或升级转发服务Skill 未加载目录路径或 description 不对检查目录、名称、描述修正 SKILL.md 头部字段填表后校验失败字段映射或选择器错误截图、打印回读值使用稳定选择器和字段映射7. 实际项目中的最佳实践7.1 学习环境与生产环境要分开对待本地尝试自动填表时应该使用演示系统或自有测试系统不要拿真实业务表单反复实验。学习阶段可以这样做用本机 Docker 起一个测试页面构造各种字段类型。允许 CLI 交互式确认权限。不断调整 Skill 规则观察模型行为变化。生产环境则需要额外补齐日志记录每次填表的数据、页面、提交结果和错误堆栈。权限运行脚本的账号严格限制数据读取范围。监控提交失败要有告警不能静默失败。回滚批量填表前先备份原始数据。合规确认填写对象的授权范围和数据处理要求数据来源不明时不要批量提交。7.2 自动填表项目最常踩的坑坑一把页面选择器写死在脚本里。页面重构一次脚本就全崩。建议优先使用稳定的>