企业官网建设流程全解析

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_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= ，API 端点固定为 https://taotoken.net/api （注意这个地址不加 UTM 参数，直接用于代码里的 base_url）。

具体来说，你需要准备三件套：

如果你用的是 Claude Code 或 OpenClaw 这类编码 Agent，配置方式略有不同。Claude Code 需要在 settings 里指定 Anthropic 兼容端点，OpenClaw 则通过 MCP 或环境变量注入。下面给一个通用的环境变量配置，适用于大多数 Agent 框架：

export TAOTOKEN_BASE_URL="https://taotoken.net/api" export TAOTOKEN_API_KEY="sk-你的Key" export TAOTOKEN_MODEL="claude-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_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= 。接入细节参考文档：https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_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.js（App 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; charset=utf-8' }, }); } return new NextResponse(doc.markdown, { headers: { 'Content-Type': 'text/markdown; charset=utf-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 URL：https://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; charset=utf-8 Vary: Accept

Vary: 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 URL="https://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 URL：https://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/api，Key 填你的 TaoToken Key，Model 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 2>&1 | grep -i "accept\|content-type\|vary"

6. 把 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_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= 。如果只是临时验证模型对 Markdown 的理解效果，可以直接在模型对话页面测试：https://taotoken.net/chat?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= 。

最后说一个实际经验：Agent 可读性优化不是一次性工程。每次你调整页面结构、换 CDN、改路由，都可能影响协商逻辑。把 curl 验证脚本当成回归测试的一部分，比事后排查省事得多。