1. 当 AI Agent 成为你的新读者网站为什么突然“读不懂”了你可能已经发现一个现象同样一篇技术文档人类读者看完觉得清晰但丢给 AI Agent 或 OpenClaw 去抓取时返回的摘要要么缺关键参数要么把结论搞反。这不是模型能力问题而是你的网站从结构上就不是给机器读的。过去十年我们做 SEO核心是讨好搜索引擎爬虫和人类眼球关键词密度、meta description、内链锚文本、首屏 hero banner。但 AI Agent 的阅读方式和传统爬虫完全不同。它不渲染视觉排版不点击轮播图不在弹窗里找“跳过”。它只做一件事按 HTTP 响应体解析内容然后尝试理解。这里有个关键差异传统爬虫拿到 HTML 后会索引全文而 AI Agent 受上下文窗口限制通常只读前 N 行或前几 KB。如果你的核心信息埋在第 800 字之后或者藏在 JavaScript 动态渲染的 Tab 里Agent 根本看不到。更麻烦的是Agent 依赖链接层级导航——它从首页顺着a标签往下走如果你的链接文字是“点击这里”而不是“认证配置文档”它就会迷路。所以问题不是“内容好不好”而是“内容能不能被机器稳定提取”。这篇教程面向三类人正在维护技术文档站的开发者、做 SaaS 产品需要被 AI 搜索引用的团队、以及想让 OpenClaw 这类 Agent 稳定读取自己网站内容的工程师。我会用三步改造法从 Content Negotiation 响应头、Markdown 输出模板到统一 Key/API 通道的接入验证每一步都给可复制的配置和 curl 验证命令。先明确一个概念Content Negotiation内容协商是 HTTP 协议里的标准机制。当请求头带Accept: text/markdown时服务器可以判断“来的是 AI Agent”然后返回精简的 Markdown 而不是完整 HTML。人类用户访问同一 URL 时不带这个头照常返回渲染好的页面。一条 URL两种响应互不干扰。我试过在 Nginx 和 Next.js 上分别实现这套逻辑实测下来 Agent 的解析准确率提升非常明显。下面从环境准备开始一步步来。2. TaoToken 统一 Key 通道让 Agent 抓取和模型调用走同一条路在动手改网站之前先解决一个容易被忽略的前置问题Agent 抓取你的内容后往往需要调用大模型做总结、问答或结构化提取。如果你的网站有多个模型供应商、多个 API Key 散落在不同环境变量里Agent 的调用链路会非常脆弱——换一个模型就要改一次配置Key 泄露风险也高。TaoToken 在这里的角色是统一 Key 通道。它把不同模型的调用收敛到一个 Base URL 和一把 API Key 上Agent 侧只需要配置一次后续切换模型只改 Model ID 即可。官网入口在 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 端点固定为 https://taotoken.net/api 注意这个地址不加 UTM 参数直接用于代码里的 base_url。具体来说你需要准备三件套配置项值说明Base URLhttps://taotoken.net/api所有模型请求的统一入口API Key在控制台生成建议按项目分 Key便于轮换Model ID按需选择如claude-sonnet-4-20250514等如果你用的是 Claude Code 或 OpenClaw 这类编码 Agent配置方式略有不同。Claude Code 需要在 settings 里指定 Anthropic 兼容端点OpenClaw 则通过 MCP 或环境变量注入。下面给一个通用的环境变量配置适用于大多数 Agent 框架export TAOTOKEN_BASE_URLhttps://taotoken.net/api export TAOTOKEN_API_KEYsk-你的Key export TAOTOKEN_MODELclaude-sonnet-4-20250514对于使用auth.json的 Codex 类工具配置片段如下路径按你的实际安装位置调整{ base_url: https://taotoken.net/api, api_key: sk-你的Key, model: claude-sonnet-4-20250514 }如果你用 Cline 或带 MCP 的编辑器插件MCP server 配置里同样填这三件套{ mcpServers: { taotoken: { url: https://taotoken.net/api, headers: { Authorization: Bearer sk-你的Key } } } }这里要提醒一点不要把生产数据库的直连信息塞进 MCP 配置Agent 只需要通过 API 通道拿模型能力数据层保持隔离。另外Key 不要硬编码在仓库里用环境变量或密钥管理服务注入。配置完成后先用一个最小请求验证通道是否通curl -s https://taotoken.net/api/v1/models \ -H Authorization: Bearer $TAOTOKEN_API_KEY | head -c 500如果返回模型列表 JSON说明 Key 和 Base URL 都正确。这一步没通过后面的网站改造做了也白做因为 Agent 拿到内容后调不动模型。关于 Key 的生成和管理可以走 API Keys 页面https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。接入细节参考文档https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。3. 可复制配置Nginx 与 Next.js 的 Content Negotiation 落地这一步是核心改造。目标当请求头包含Accept: text/markdown时返回纯 Markdown否则返回正常 HTML。下面给两套方案按你的技术栈选一套。3.1 Nginx 方案用 map 做内容协商Nginx 本身不生成 Markdown但可以通过map指令判断 Accept 头然后把请求转发到预生成的.md文件或后端接口。假设你的文档站已经为每个页面生成了对应的.md文件放在/var/www/docs-md/目录下。在nginx.conf的http块里加map $http_accept $is_agent { default 0; ~*text/markdown 1; }然后在server块里配置server { listen 80; server_name your-site.com; root /var/www/html; location / { if ($is_agent) { rewrite ^/(.*)$ /md/$1.md last; } try_files $uri $uri/ /index.html; } location /md/ { internal; alias /var/www/docs-md/; default_type text/markdown; add_header Vary Accept; } }关键点add_header Vary Accept必须加否则 CDN 或缓存层可能把 Markdown 响应错误地缓存给人类用户。internal保证/md/路径不对外暴露。3.2 Next.js 方案middleware 动态判断如果你用 Next.jsApp Router 或 Pages Router 都行在middleware.ts里做判断更灵活import { NextRequest, NextResponse } from next/server; export function middleware(request: NextRequest) { const accept request.headers.get(accept) || ; const isAgent accept.includes(text/markdown); if (isAgent) { const url request.nextUrl.clone(); url.pathname /api/markdown${url.pathname}; return NextResponse.rewrite(url); } const response NextResponse.next(); response.headers.set(Vary, Accept); return response; } export const config { matcher: [/((?!_next|api/markdown|favicon.ico).*)], };然后在app/api/markdown/[...slug]/route.ts里读取对应内容并转成 Markdown 返回import { NextRequest, NextResponse } from next/server; import { getDocBySlug } from /lib/docs; export async function GET( request: NextRequest, { params }: { params: { slug: string[] } } ) { const slug params.slug.join(/); const doc await getDocBySlug(slug); if (!doc) { return new NextResponse(# 404\n\n内容不存在, { status: 404, headers: { Content-Type: text/markdown; charsetutf-8 }, }); } return new NextResponse(doc.markdown, { headers: { Content-Type: text/markdown; charsetutf-8, Vary: Accept, }, }); }3.3 Markdown 模板前 500 字决定 Agent 的理解Agent 只读前 N 行所以 Markdown 输出的开头必须是“结论先行”。推荐模板# 页面标题 一句话说明这个页面解决什么问题。 ## 核心信息 - 关键参数 A值 - 关键参数 B值 - 快速开始命令npm install xxx ## 详细说明 正文内容保持标题层级清晰 ## 相关链接 - [认证配置](/docs/auth) - [API 参考](/docs/api)注意不要放导航、面包屑、CTA 按钮、用户评价。Agent 不需要这些它们只会增加 token 消耗和解析噪声。同样的内容Markdown 比 HTML 节省 40% 到 60% 的 token解析准确率也更高。3.4 给 OpenClaw 加一个 llms.txt 入口除了 Content Negotiation还可以在网站根目录放一个llms.txt主动告诉 Agent 你的站点结构。格式很简单# 你的站点名称 站点简介一句话。 ## 文档 - [快速开始](https://your-site.com/docs/start.md): 安装和初始化 - [认证配置](https://your-site.com/docs/auth.md): API Key 和权限 - [API 参考](https://your-site.com/docs/api.md): 接口列表OpenClaw 这类 Agent 在抓取前会优先检查llms.txt有的话直接按图索骥省去遍历链接的开销。这个文件放在public/llms.txt即可Next.js 会自动作为静态资源返回。4. 验证请求用 curl 和 Agent 抓取对比改造前后效果配置写完了必须验证。分两步先用 curl 模拟 Agent 请求再用真实 Agent 抓取对比。4.1 curl 验证响应头与内容改造前请求你的页面curl -s -H Accept: text/markdown https://your-site.com/docs/auth | head -c 300如果返回的是!DOCTYPE html开头的一堆标签说明 Content Negotiation 没生效。改造后应该返回# 认证配置 本文说明如何生成 API Key 并配置权限。 ## 核心信息 - Base URLhttps://taotoken.net/api - 认证方式Bearer Token ...同时检查响应头curl -sI -H Accept: text/markdown https://your-site.com/docs/auth | grep -i content-type\|vary期望输出Content-Type: text/markdown; charsetutf-8 Vary: AcceptVary: Accept是必须的否则缓存层会把 Markdown 响应错误地返回给浏览器用户。4.2 对比人类请求curl -s https://your-site.com/docs/auth | head -c 200应该返回正常 HTML包含html、head等标签。两条请求走同一 URL响应不同说明协商逻辑正确。4.3 Agent 抓取对比用 OpenClaw 或任意支持 Markdown 抓取的 Agent 做对比测试。改造前Agent 抓取后总结的内容往往丢失关键参数改造后Agent 能准确提取 Base URL、认证方式、快速开始命令。你可以写一个简单的对比脚本#!/bin/bash URLhttps://your-site.com/docs/auth echo 改造前模拟 HTML 抓取 curl -s $URL | sed s/[^]*//g | tr -s \n \n | head -20 echo echo 改造后Markdown 协商 curl -s -H Accept: text/markdown $URL | head -20对比两段输出你会看到 Markdown 版本的信息密度明显更高没有导航和脚本噪声。4.4 验证 TaoToken 通道在 Agent 链路中可用Agent 抓取内容后通常会调用模型做总结。用 curl 模拟这一步curl -s https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer $TAOTOKEN_API_KEY \ -H Content-Type: application/json \ -d { model: claude-sonnet-4-20250514, messages: [ {role: user, content: 总结以下内容的关键参数\n\n# 认证配置\n\n- Base URLhttps://taotoken.net/api\n- 认证方式Bearer Token} ] } | head -c 500如果返回包含“Base URL”和“Bearer Token”的总结说明从抓取到模型调用的整条链路通了。这一步验证的是 Agent 场景下的端到端可用性不只是网站改造本身。5. 本篇常见错排查401、local proxy failed 与 reading choices 报错改造过程中最容易踩的坑集中在认证和响应解析上。下面按真实报错逐一排查。5.1 401 Unauthorized这是最常见的。Agent 调用 TaoToken 时返回 401原因通常是 Key 没传对或 Base URL 写错。检查清单# 确认环境变量已注入 echo $TAOTOKEN_API_KEY | head -c 8 # 确认 Base URL 没有多余斜杠 echo $TAOTOKEN_BASE_URL # 正确https://taotoken.net/api # 错误https://taotoken.net/api/ 或 https://taotoken.net/api/v1/注意Base URL 填https://taotoken.net/api具体路径由 SDK 或请求体拼接。如果你手动拼/v1/chat/completions完整地址是https://taotoken.net/api/v1/chat/completions。多一个斜杠或少一个/v1都会导致 401 或 404。5.2 local proxy failed这个报错通常出现在 Agent 框架配置了本地代理但代理未启动或者代理配置指向了错误的端口。排查步骤# 检查本地代理进程 ps aux | grep -i proxy # 检查端口监听 lsof -i :7890如果你没有使用本地代理检查 Agent 配置里是否残留了HTTP_PROXY或HTTPS_PROXY环境变量env | grep -i proxy有的话清掉unset HTTP_PROXY HTTPS_PROXY然后重新发起请求。注意这里说的代理是本地开发环境的网络配置不是让你去搭什么特殊通道只是排查环境变量污染。5.3 reading choices 报错这个报错一般出现在模型返回结构不符合预期时。比如你期望choices[0].message.content但实际返回了错误对象。排查方法curl -s https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer $TAOTOKEN_API_KEY \ -H Content-Type: application/json \ -d {model:claude-sonnet-4-20250514,messages:[{role:user,content:hi}]} \ | python3 -m json.tool | head -30看返回的 JSON 结构。如果error字段有内容按错误信息处理如果choices为空检查 Model ID 是否正确。Model ID 写错时部分接口会返回空 choices 而不是明确报错。5.4 OAuth 相关报错如果你用 Claude Code 或类似工具可能会遇到 OAuth token 过期。这类工具通常有自己的认证流程和 API Key 是两套机制。排查# 查看 Claude Code 配置目录 ls ~/.claude/ # 检查 auth 相关文件 cat ~/.claude/auth.json 2/dev/null | head -c 200如果 OAuth 过期重新走一遍登录流程或者改用 API Key 模式。在 Claude Code 里配置 Anthropic 兼容端点时Base URL 填https://taotoken.net/apiKey 填你的 TaoToken KeyModel ID 按需选择。三件套缺一不可。5.5 Markdown 协商不生效如果 curl 带Accept: text/markdown仍返回 HTML检查第一Nginx 的map指令是否放在http块而不是server块。第二Vary头是否被其他add_header覆盖。第三CDN 是否缓存了旧响应清缓存后重试。第四Next.js middleware 的matcher是否排除了目标路径。排查时可以用curl -v看完整请求响应curl -v -H Accept: text/markdown https://your-site.com/docs/auth 21 | grep -i accept\|content-type\|vary6. 把 Agent 可读性纳入日常发布流程改造完成后建议把这几项检查固化到发布流程里。每次文档更新跑一遍验证脚本#!/bin/bash set -e URLS( https://your-site.com/docs/start https://your-site.com/docs/auth https://your-site.com/docs/api ) for url in ${URLS[]}; do ct$(curl -sI -H Accept: text/markdown $url | grep -i content-type | tr -d \r) echo $url - $ct if [[ $ct ! *text/markdown* ]]; then echo 警告$url 未返回 Markdown fi done这个脚本可以挂到 CI 里每次合并前跑一次。另外llms.txt要随文档结构同步更新新增页面时记得加链接。对于需要长期跑 Agent 任务的场景比如让 OpenClaw 持续抓取你的文档做问答建议用 Coding Plan 管理调用配额和模型切换https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。如果只是临时验证模型对 Markdown 的理解效果可以直接在模型对话页面测试https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。最后说一个实际经验Agent 可读性优化不是一次性工程。每次你调整页面结构、换 CDN、改路由都可能影响协商逻辑。把 curl 验证脚本当成回归测试的一部分比事后排查省事得多。