跳到主要内容
AI教程

Codex SEO 教程：在 Codex CLI 中完成网站 SEO、GEO 与结构化数据审计

本教程介绍如何安装 Codex SEO，并使用 Codex CLI 执行全站、单页、技术、内容、Schema、AI 搜索、本地与电商 SEO 审计，同时讲解报告、API 接入、漂移监控和使用边界。

AI我搜编辑部阅读约 12 分钟
Codex SEO 教程：在 Codex CLI 中完成网站 SEO、GEO 与结构化数据审计

Codex SEO 是什么

Codex SEO 是一套运行在 OpenAI Codex CLI 中的免费开源 SEO 审计技能。你只需提供网站地址，它就能检查网站并生成按优先级排序的行动计划，而不只是罗列一组互不关联的告警。

项目移植自 Agrici Daniel 的 claude-seo，将上游的审计方法、技能与脚本适配到了 Codex CLI。项目采用 MIT 协议，不按网站收费，也不要求安装第三方 SEO 服务。

Codex SEO 本身开源且没有按站计费，但执行审计时仍会使用当前 Codex 会话所配置的模型。完整审计需要运行多个角色，因此通常比单页分析消耗更多 token。

核心能力

Codex SEO 由 26 个子技能和 19 个专家角色剧本组成。一次完整审计最多会让 17 个角色依次分析网站，并将每个角色的发现写入文件留证。

  • 技术 SEO：检查可抓取性、收录线索、XML sitemap、robots.txt、重定向、页面速度和 Core Web Vitals。
  • 内容与 E-E-A-T：分析经验、专业性、权威性、可信度、薄内容和主题覆盖情况。
  • 结构化数据：发现并校验现有 Schema.org 标记，也可以生成建议标记。
  • AI 搜索与 GEO：评估页面被 Google AI Overviews、AI Mode、ChatGPT、Perplexity 和 Gemini 引用的可能性。
  • Agent 就绪度：检查 AI Agent 访问、llms.txt、Markdown、WebMCP 等相关能力。
  • 本地与电商 SEO：覆盖 Google Business Profile、评价、地图包、商品页面和多语言网站。
  • 策略与持续监控：提供行业规划、竞品页面、内容简报、语义聚类和基于 SQLite 快照的 SEO 漂移监控。

安装前准备

开始前需要准备以下环境：

  • 支持 skills 的 OpenAI Codex CLI。
  • Python 3.11 至 3.14。
  • 用于克隆仓库的 Git。

默认情况下不需要 SEO 服务 API key。安装器会将技能复制到 ~/.agents/skills/，这是 Codex 发现用户技能的位置；同时创建包含无头浏览器的隔离 Python 运行时，不会修改系统全局 Python 环境。

安装 Codex SEO

macOS 与 Linux

克隆仓库并运行安装脚本：

git clone --depth 1 https://github.com/zhtyyx/codex-seo.git
bash codex-seo/install.sh

Windows PowerShell

在 PowerShell 中执行：

git clone --depth 1 https://github.com/zhtyyx/codex-seo.git
powershell -ExecutionPolicy Bypass -File codex-seo\install.ps1

初始化与环境检查

如果需要创建或刷新隔离运行时与 Chromium，可以在 Codex CLI 中运行：

$seo setup

若只想检查环境而不修改系统，则运行：

$seo doctor

$seo doctor 是只读体检，适合在安装后或遇到问题时确认依赖状态。

第一次执行 SEO 审计

  1. 在终端中运行 codex 启动 Codex CLI。
  2. 使用 $seo 提及技能。
  3. 提供准备分析的网站或页面地址。
  4. 等待各个专家角色完成分析并查看生成的行动计划。
codex

$seo audit https://example.com

$seo audit 会执行全站审计，适合第一次摸清网站整体问题。系统会自动识别 SaaS、本地服务、电商、内容站或代理机构等业务类型，并据此调整检查项。

你也可以直接使用自然语言，例如：

帮我做一次 SEO 审计，网址是 https://example.com

四个常用入门命令

全站审计

$seo audit https://example.com

运行完整专家流程，输出按优先级排列的修复与优化计划。每条建议会说明重要性、判断依据、依赖项以及验证是否生效的方法。

单页深度分析

$seo page https://example.com/pricing

当你只关心定价页、产品页、落地页或文章页时，可以使用单页分析，避免直接执行成本更高的完整审计。

AI 搜索就绪度分析

$seo geo https://example.com

该命令面向生成式引擎优化，评估页面是否容易被 AI 搜索引用、AI 爬虫能否访问，以及品牌在 Wikipedia、Reddit、YouTube 和 LinkedIn 等公开平台上的存在感。

结构化数据检查

$seo schema https://example.com

该命令可以发现和校验页面中的 Schema.org 标记，并给出生成结构化数据的建议。

按目标选择审计命令

技术 SEO

  • $seo technical https://example.com：执行九大类技术审计。
  • $seo sitemap https://example.com：分析网站的 XML sitemap。
  • $seo sitemap generate：生成 XML sitemap。
  • $seo images https://example.com：分析图片优化问题。
  • $seo hreflang https://example.com：审计或生成多语言 hreflang 配置。
  • $seo programmatic https://example.com：分析和规划程序化 SEO。
  • $seo unlighthouse https://example.com：在本地进行多页面 Lighthouse 分析。

内容与搜索体验

  • $seo content https://example.com：分析 E-E-A-T 与内容质量。
  • $seo content-brief 目标主题：生成包含目标关键词、大纲和内链建议的内容简报。
  • $seo cluster 目标关键词：执行基于 SERP 的语义聚类。
  • $seo sxo https://example.com：分析页面类型、用户故事和用户画像等搜索体验因素。
  • $seo competitor-pages https://example.com：生成竞品对比页面建议。

本地、外链与电商

  • $seo local https://example.com：检查 GBP、引用、评价和地图包表现。
  • $seo maps [command]：使用 geo-grid、GBP 审计和竞对半径等地图情报能力。
  • $seo backlinks https://example.com：通过 Moz、Bing 和 Common Crawl 等来源分析外链画像。
  • $seo ecommerce https://example.com：执行电商 SEO 与市场情报分析。

完整审计如何工作

  1. 识别网站类型：先判断网站属于 SaaS、本地服务、电商、内容站还是代理机构，并调整后续检查范围。
  2. 专家依次分析：技术、内容、结构化数据、速度和 AI 搜索等角色按顺序执行任务。
  3. 发现落盘：每个角色完成后会保存自己的发现文件，为结论保留依据。
  4. 问题评分：系统对发现进行评分，而不是仅按出现顺序展示。
  5. 生成行动计划：最终报告按照优先级组织建议，并说明原因、依赖关系和验证方式。

报告默认保存为 Markdown。如果需要 PDF，可以要求 Codex“生成 PDF 报告”，并通过 $seo google report 输出。

进阶使用技巧

先做小范围分析，再运行全站审计

完整的 $seo audit 会在主会话中运行最多 17 个角色，token 消耗高于单页检查。对于大型网站，可以先用 $seo page、$seo technical、$seo content 或 $seo schema 验证重点页面，再决定是否运行全站审计。

按行业生成战略计划

$seo plan 支持 SaaS、本地服务、电商、内容发布和代理机构等类型：

$seo plan saas
$seo plan local
$seo plan ecommerce
$seo plan publisher
$seo plan agency

使用与业务相符的类型，有助于让规划围绕正确的搜索场景展开。

接入 Google 数据

Codex SEO 无需 API key 即可使用。如果需要真实字段数据，可以运行以下命令配置免费的 Google API：

$seo google setup

可接入的数据包括 PageSpeed Insights、Chrome UX Report、Google Search Console 和 GA4。密钥只保存在本机。

未配置 Google API key 时，Core Web Vitals 属于实验估算，收录状态也主要根据页面信息推断。涉及重要决策时，应结合真实字段数据与搜索平台数据复核。

监控 SEO 漂移

Codex SEO 可以通过 SQLite 快照建立基线、比较变化并查看历史：

$seo drift baseline https://example.com
$seo drift compare https://example.com
$seo drift history https://example.com

这组命令适合在改版、迁移、模板更新或持续发布内容后检查 SEO 状态是否发生偏移。

检查 AI Agent 能否使用网站

$seo agentic https://example.com

该命令检查 Lighthouse Agentic Browsing X/N、AI Agent 访问、llms.txt、Markdown 和 WebMCP 等项目。它与 $seo geo 的侧重点不同：前者关注 Agent 使用网站的能力，后者更关注页面在生成式搜索中的可发现性和可引用性。

审计 JavaScript 网站

Codex SEO 支持 Next.js、React、Vue 和其他依赖 JavaScript 渲染的网站。当页面必须执行 JavaScript 才显示内容时，它会自动使用无头浏览器，并按照访客看到的页面进行审计。

如果关键内容必须在滚动或点击后才加载，结果仍可能出现噪音。建议手动检查这类交互区域，并将自动审计结论与浏览器实际表现进行对照。

可选扩展

基础审计不依赖付费扩展，但项目提供了若干可选集成。使用这些服务时需要自行准备对应账号或配置。

  • $seo image-gen [use-case]：为 SEO 素材生成 AI 图片。
  • $seo seranking [command]：分析 ChatGPT、Gemini、Perplexity、AI Overviews 和 AI Mode 中的 AI 声量份额。
  • $seo profound [command]：跟踪 LLM 引用及其时间序列。
  • $seo bing [command] https://example.com：使用 Bing 站长工具与 IndexNow 提交能力。

隐私、边界与卸载

数据如何处理

Codex SEO 运行在 Codex CLI 中，被分析的页面和相关数据会发送给当前 Codex 会话背后的 OpenAI 模型，处理方式与其他 Codex 任务一致。生成的报告以文件形式保存在本机。

除非主动接入扩展或 API，否则没有额外 SEO 服务接收数据。部分检查可能读取 Wikipedia、Reddit 和 Common Crawl 等公开来源。

需要注意的边界

  • 未连接 Google API 时，Core Web Vitals 为实验估算。
  • 未连接真实平台数据时，收录状态主要根据页面推断。
  • 依赖滚动、点击或复杂交互才加载关键内容的页面可能产生噪音。
  • 完整审计会使用更多 token，应根据网站规模选择命令。

卸载

如果不再使用，可以运行仓库提供的卸载脚本：

bash uninstall.sh

该命令用于移除已安装的技能。

结语

Codex SEO 将技术检查、内容质量、Schema、GEO、本地 SEO、电商 SEO 和持续监控整合进 Codex CLI。建议先通过 $seo doctor 确认环境，再以 $seo page 或专项命令熟悉流程，最后使用 $seo audit 生成完整的优先级行动计划。

如需查询全部参数和扩展配置，可查看项目的 GitHub 仓库及其中的安装、命令、架构、故障排查、安全与隐私文档。