1. WordPress 站点里 AI 写作的真实卡点
WordPress 在线参考文档这件事，我最早是在一个技术博客站上折腾的。站点本身跑着 WooCommerce 和几个自定义文章类型，运营同学每天要写产品说明、更新帮助中心、维护开发者文档。一开始大家各用各的 AI 工具，有人开浏览器标签页复制粘贴，有人在本地编辑器里写好再传上去，结果就是：同一个站点的文档风格不统一，Key 散落在不同人的浏览器插件里，月底对账根本说不清谁用了多少。
真正让我决定把链路收拢到站点内部的，是三个具体问题。第一，WordPress 后台的经典编辑器和区块编辑器都不带 AI 能力，运营要生成一段「函数参考」得先切到别的窗口，写完再回来排版，上下文全断了。第二，站点有 REST API，理论上可以让外部脚本调用/wp-json/wp/v2/posts直接写入草稿，但脚本里如果硬编码某个厂商的 Key，换模型、换额度、换计费方式时就要改代码重新部署。第三，文档生成不是一次性动作，帮助中心要持续更新，开发者参考要跟着版本走，没有一个统一的调用通道，每次都是重复劳动。
所以这篇要解决的问题很明确：在 WordPress 自有站点内，用一套统一的 Key 和 API 通道，把「后台编辑器辅助写作」和「REST API 批量生成文档」两条路径都打通。适合谁看？自己维护 WordPress 站点的开发者、技术博客运营、需要给产品写在线帮助文档的小团队。你不需要懂大模型原理，只要会改wp-config.php、会用curl或 Postman 发请求，就能跟着做下来。
核心检索词先摆出来：WordPress 在线参考文档、统一 Key、REST API 鉴权、wp-config 常量配置。这几个词后面会反复出现，因为它们就是整条链路的骨架。我试过把 Key 放在主题的functions.php里，也试过用插件设置页存，最后发现最稳的还是wp-config.php常量——它不进数据库、不被主题更新覆盖、也不会因为换插件而丢失。
先说清楚整体思路，避免你中途迷路。WordPress 站点要调 AI，本质是「服务端发 HTTP 请求」。浏览器端直接调会有跨域和 Key 暴露问题，所以正确姿势是：Key 存在服务端常量里，由 PHP 或外部脚本读取，再向统一的 API 地址发请求。这个统一地址就是 TaoToken 的 API 入口，它兼容 OpenAI 风格的/v1/chat/completions，所以 WordPress 生态里现成的 OpenAI 类库、REST 封装都能直接复用，不用为它单独写适配层。
接下来我会按「前置准备 → 可复制配置 → 验证请求 → 排错 → 分流」的顺序展开。每一步都给完整命令和参数，你照着敲就行。中间会穿插我踩过的坑，比如常量名写错导致读不到、REST 请求 401、返回体里choices读不到字段这些，都会在排错章节对照真实报错讲。
2. TaoToken 前置：统一 Key 与 API 通道怎么摆
在动手改 WordPress 之前，先把 TaoToken 这边的准备工作做完。这一步不复杂，但顺序不能乱，否则后面配置会来回返工。
2.1 拿到统一 Key 和 API 地址
TaoToken 的 API 入口是https://taotoken.net/api，注意这个地址后面不加任何 UTM 参数，它是给程序调用的干净入口。Key 的获取在控制台的 API Keys 页面，登录后新建一个 Key，复制出来先存到安全的地方。这个 Key 就是「统一 Key」——站点里所有 AI 调用都用它，不再区分写作、翻译、摘要各用各的。
模型对话的调试入口在模型对话页面，你可以先在那里发一条测试消息，确认 Key 有效、额度正常，再去改站点配置。这一步相当于「先验证通道，再接入业务」，能省掉很多在 WordPress 里排查网络问题的时间。
如果你后面要做长期编码或 Agent 类任务，比如让脚本自动根据代码仓库生成参考文档，可以了解下 Coding Plan，它面向的是持续性的编码场景，和单次文档生成是两种用法，按需选择就行。
2.2 为什么统一通道对 WordPress 特别重要
WordPress 站点的插件生态很杂。你装一个 AI 写作插件，它可能内置了某厂商的 SDK；再装一个 SEO 插件，它又自带一套摘要接口。每个插件各存一份 Key，结果就是：换 Key 要挨个插件改，额度用超了不知道是哪个插件干的，模型升级了插件不跟进你就用不上新模型。
统一通道的价值在于「一处配置，多处复用」。Key 存在wp-config.php常量里，主题、插件、外部脚本都从同一个常量读。API 地址也统一，今天用这个模型，明天换那个模型，只改请求体里的model字段，不改代码结构。对运营来说，后台编辑器的辅助写作和 REST API 的批量生成走的是同一条通道，风格和额度都可控。
2.3 接入位置梳理：后台编辑器 vs REST API
WordPress 里能接入 AI 的位置主要有两个，要分清楚。
第一个是后台编辑器。经典编辑器可以用the_editor相关钩子，区块编辑器可以用enqueue_block_editor_assets注入脚本，或者用rest_pre_dispatch在保存前做处理。更简单的做法是装一个支持自定义 API 地址的 AI 插件，把 Base URL 指向 TaoToken，Key 填统一 Key。这样运营在编辑器里点「生成摘要」「扩写段落」时，请求走的就是你的统一通道。
第二个是 REST API。WordPress 自带/wp-json/wp/v2/系列端点，你可以用外部脚本（PHP、Python、Node 都行）调用 TaoToken 生成内容，再通过 REST API 写入草稿。这条路径适合批量生成参考文档，比如根据函数列表自动产出帮助中心条目。
两条路径的鉴权方式不同：后台编辑器走的是 WordPress 自身的登录态和 nonce，AI 请求由服务端代理；REST API 写入走的是 WordPress 的应用密码（Application Password）或 JWT，而 AI 请求走的是 TaoToken 的 Bearer Key。这两层鉴权要分开配置，别混在一起。
2.4 安全边界：Key 不进前端
这一点必须单独强调。不管用哪种方式，TaoToken 的 Key 绝对不能出现在浏览器可见的 JS 里。区块编辑器注入的脚本如果直接带 Key，任何人打开开发者工具都能抄走。正确做法是：前端只发请求到 WordPress 自己的 REST 端点，由 PHP 在服务端读取常量、拼接 Key、转发给 TaoToken。这样 Key 始终留在服务器，前端拿不到。
同理，外部脚本调 TaoToken 时，Key 放在环境变量或配置文件里，不要提交到 Git 仓库。WordPress 站点的wp-config.php本身就不该进版本控制，这一点老手都懂，新手容易忽略。
前置工作到这里就齐了：一个统一 Key、一个 API 地址、两个接入位置、一条安全边界。下面进入可复制配置环节。
3. 可复制配置：wp-config 常量与 REST 请求示例
这一章是整篇的核心，所有配置都给完整片段，你直接复制改参数即可。配置分三块：wp-config.php常量、后台编辑器插件设置、REST API 请求示例。
3.1 wp-config.php 常量配置
打开站点根目录的wp-config.php，在/* That's all, stop editing! */这行之前插入以下常量。路径就是 WordPress 根目录下的wp-config.php，和wp-load.php同级。
// TaoToken 统一 API 配置 define('TAOTOKEN_API_BASE', 'https://taotoken.net/api'); define('TAOTOKEN_API_KEY', 'sk-你的统一Key'); define('TAOTOKEN_DEFAULT_MODEL', 'gpt-4o-mini'); define('TAOTOKEN_TIMEOUT', 60);四个常量的作用分别是：TAOTOKEN_API_BASE是 API 入口，注意结尾不带斜杠，拼接路径时自己补/v1/chat/completions；TAOTOKEN_API_KEY是统一 Key，所有调用共用；TAOTOKEN_DEFAULT_MODEL是默认模型 ID，后面请求体里可以覆盖；TAOTOKEN_TIMEOUT是超时秒数，文档生成内容长，建议不低于 60。
这里有个坑：常量名不要用OPENAI_API_KEY这种通用名，因为有些插件会自己定义同名常量，导致冲突或覆盖。用带前缀的TAOTOKEN_能避免大部分问题。
3.2 后台编辑器插件设置片段
如果你用的是支持自定义端点的 AI 写作插件，设置页通常有 Base URL、API Key、Model 三个字段。按下面填：
{ "base_url": "https://taotoken.net/api/v1", "api_key": "sk-你的统一Key", "model": "gpt-4o-mini", "temperature": 0.7, "max_tokens": 2048 }注意base_url这里带了/v1，因为多数插件会自动拼/chat/completions。如果你的插件要求填完整端点，那就写https://taotoken.net/api/v1/chat/completions。Model ID 要和 TaoToken 支持的模型列表一致，写错会返回模型不存在的错误。
有些插件把配置存在数据库的wp_options表里，这种情况下 Key 会进数据库。如果你介意，可以改用常量方式，在插件初始化钩子里用add_filter覆盖它的设置值，从常量读 Key。具体钩子名看插件文档，不同插件不一样。
3.3 REST API 请求示例：生成文档草稿
下面这段 PHP 代码可以放在主题的functions.php里，或者做成一个自定义插件。它的作用是：接收一个标题，调用 TaoToken 生成正文，再通过 WordPress REST API 写入草稿。
function taotoken_generate_doc_draft($title) { $api_base = defined('TAOTOKEN_API_BASE') ? TAOTOKEN_API_BASE : ''; $api_key = defined('TAOTOKEN_API_KEY') ? TAOTOKEN_API_KEY : ''; $model = defined('TAOTOKEN_DEFAULT_MODEL') ? TAOTOKEN_DEFAULT_MODEL : 'gpt-4o-mini'; if (empty($api_base) || empty($api_key)) { return new WP_Error('config_missing', 'TaoToken 常量未配置'); } $prompt = "请为以下主题写一篇在线参考文档，包含概述、参数说明和示例：\n" . $title; $response = wp_remote_post($api_base . '/v1/chat/completions', array( 'timeout' => TAOTOKEN_TIMEOUT, 'headers' => array( 'Authorization' => 'Bearer ' . $api_key, 'Content-Type' => 'application/json', ), 'body' => wp_json_encode(array( 'model' => $model, 'messages' => array( array('role' => 'system', 'content' => '你是技术文档写作助手。'), array('role' => 'user', 'content' => $prompt), ), 'temperature' => 0.7, )), )); if (is_wp_error($response)) { return $response; } $body = json_decode(wp_remote_retrieve_body($response), true); if (empty($body['choices'][0]['message']['content'])) { return new WP_Error('api_error', '返回体缺少 choices 字段'); } $content = $body['choices'][0]['message']['content']; $post_id = wp_insert_post(array( 'post_title' => $title, 'post_content' => $content, 'post_status' => 'draft', 'post_type' => 'post', )); return $post_id; }这段代码的关键点：用wp_remote_post而不是curl，因为 WordPress 自带 HTTP 封装，兼容性和代理设置更省心；鉴权用Authorization: Bearer头；返回体从choices[0].message.content取正文。写入用wp_insert_post，状态设为draft，避免直接发布未审核内容。
3.4 外部脚本调用示例
如果你不想把逻辑塞进 WordPress，也可以用外部 Python 脚本调 TaoToken，再通过 REST API 写入。先调 AI：
curl -X POST https://taotoken.net/api/v1/chat/completions \ -H "Authorization: Bearer sk-你的统一Key" \ -H "Content-Type: application/json" \ -d '{ "model": "gpt-4o-mini", "messages": [ {"role": "system", "content": "你是技术文档写作助手。"}, {"role": "user", "content": "为 wp_remote_post 函数写一段参考文档"} ], "temperature": 0.7 }'拿到返回的正文后，再用 WordPress 应用密码写入：
curl -X POST https://你的站点.com/wp-json/wp/v2/posts \ -u "用户名:应用密码" \ -H "Content-Type: application/json" \ -d '{ "title": "wp_remote_post 参考", "content": "这里放上一步生成的正文", "status": "draft" }'两层鉴权在这里体现得很清楚：第一层是 TaoToken 的 Bearer Key，第二层是 WordPress 的应用密码。应用密码在用户资料页生成，和登录密码不同，可以单独撤销。
配置部分到此完整。下面验证请求是否真的通。
4. 验证请求与成功结果
配置写完不代表链路通了，必须实际发一次请求看返回。验证分两步：先验证 TaoToken 通道，再验证 WordPress 写入。
4.1 验证 TaoToken 通道
用最简的 curl 命令测通道，不经过 WordPress：
curl -s -o /dev/null -w "%{http_code}" \ -X POST https://taotoken.net/api/v1/chat/completions \ -H "Authorization: Bearer sk-你的统一Key" \ -H "Content-Type: application/json" \ -d '{"model":"gpt-4o-mini","messages":[{"role":"user","content":"ping"}]}'期望返回200。如果返回401，说明 Key 无效或没带上；返回404，检查路径是不是写成了/api/chat/completions少了/v1；返回429，是额度或频率限制，去控制台看用量。
想看到完整返回体，去掉-o /dev/null -w部分，直接看 JSON。正常返回结构里会有choices数组，第一个元素的message.content就是模型输出。这个字段名要记牢，后面排错会用到。
4.2 验证 WordPress 侧调用
在 WordPress 里触发上面写的taotoken_generate_doc_draft函数，最简单的方式是加一个临时短代码：
add_shortcode('test_taotoken', function() { $result = taotoken_generate_doc_draft('测试文档标题'); if (is_wp_error($result)) { return '错误：' . $result->get_error_message(); } return '草稿已创建，ID：' . $result->get_error_message(); });在页面里插入[test_taotoken]，前台访问这个页面。如果返回「草稿已创建，ID：123」，说明整条链路通了。去后台文章列表看，应该有一条标题为「测试文档标题」的草稿，正文是 AI 生成的内容。
4.3 成功结果的判断标准
不要只看「没报错」就认为成功。真正的成功要满足三个条件：第一，HTTP 状态码 200；第二，返回体里choices[0].message.content非空；第三，WordPress 里确实多了一条草稿，且正文内容完整、没有截断。
内容截断是常见问题，通常是因为max_tokens设小了，或者超时时间不够。文档类内容动辄上千字，max_tokens建议 2048 起步，超时 60 秒起步。如果返回的正文在句子中间断掉，先调这两个参数。
4.4 用模型对话页面做交叉验证
如果你在 WordPress 里怎么都调不通，但 curl 能通，问题多半在 WordPress 的 HTTP 层。这时候去模型对话页面手动发一条同样的 prompt，确认模型侧没问题。如果模型对话页面正常，那就是wp_remote_post的参数或站点网络配置有问题，回到排错章节对照。
验证通过后，你就可以把短代码删掉，改成定时任务或手动触发的批量生成脚本。整条链路的核心就是「常量读 Key → 服务端发请求 → 解析 choices → 写入草稿」，四步都验证过，后面只是换 prompt 和换触发方式的事。
5. 常见报错排查：401、local proxy failed、choices 读不到
这一章对照真实报错讲。我把踩过的坑按错误信息分类，你遇到哪个查哪个。
5.1 401 Unauthorized
报错长这样：
{"error":{"message":"Invalid API key","type":"invalid_request_error"}}原因通常是三个：Key 复制时带了空格或换行；Authorization头拼成了Bearer sk-xxx带尾空格；常量没读到，TAOTOKEN_API_KEY实际是空字符串。
排查方法：在 PHP 里临时error_log(TAOTOKEN_API_KEY)看值对不对；用var_dump(strlen(TAOTOKEN_API_KEY))确认长度；curl 测试时把 Key 用引号包起来避免 shell 截断。如果 Key 本身没问题，检查是不是用了旧 Key，去控制台重新生成一个。
5.2 local proxy failed
这个报错通常出现在 WordPress 的 HTTP 请求层，信息类似：
cURL error 7: Failed to connect to ... port 443: Connection refused或者插件里显示local proxy failed。原因是站点的 HTTP 请求被本地代理拦截了，或者wp-config.php里定义了WP_PROXY_HOST之类的常量指向了一个不可用的代理。
排查：检查wp-config.php有没有WP_PROXY_HOST、WP_PROXY_PORT、WP_PROXY_USERNAME、WP_PROXY_PASSWORD这几个常量，有的话先注释掉。检查服务器环境变量http_proxy、https_proxy，有的话 unset。如果站点在容器里，检查容器网络能不能出站访问 443 端口，用curl -v https://taotoken.net/api测。
5.3 返回体读不到 choices
报错表现是代码里$body['choices'][0]['message']['content']为空，但 HTTP 状态码是 200。可能原因：返回体不是 JSON，而是 HTML 错误页；返回体是 JSON 但结构不同，比如某些错误响应只有error字段；wp_remote_retrieve_body拿到的内容被截断。
排查：先把原始返回体打出来看。
$raw = wp_remote_retrieve_body($response); error_log($raw);如果$raw是 HTML，说明请求打到了错误的地址，检查TAOTOKEN_API_BASE拼接后的完整 URL。如果$raw是 JSON 但只有error，看 error 内容对症处理。如果$raw是完整 JSON 但解析失败，可能是编码问题，用json_decode($raw, true)并检查json_last_error()。
5.4 OAuth 相关报错
如果你用的是 Claude Code 或某些 CLI 工具接入，可能遇到 OAuth 报错，比如OAuth token expired或invalid_grant。这类工具通常有自己的鉴权流程，和 WordPress 的 Bearer Key 不是一回事。排查时先确认你用的是 API Key 模式还是 OAuth 模式，两者不能混用。
如果工具要求填 Base URL、Key、Model ID 三件套，按这个填：Base URL 用https://taotoken.net/api，Key 用统一 Key，Model ID 用控制台里确认可用的模型名。三件套缺一个都会报鉴权或模型错误。CC Switch、Cline MCP、Codex 的auth.json这类配置，核心字段也是这三个，路径和字段名按各工具文档来，值从 TaoToken 控制台取。
5.5 超时与内容截断
报错信息类似cURL error 28: Operation timed out。文档生成内容长，默认超时往往不够。在wp_remote_post的timeout参数里设 60 或 120，同时确认 PHP 的max_execution_time足够大。如果站点用了 CDN 或反向代理，还要检查它们的超时设置，有些默认 30 秒就断。
内容截断则调max_tokens，设 2048 或 4096。注意max_tokens是输出上限，不是输入上限，输入 prompt 太长也会导致整体超时，prompt 控制在合理长度。
排错的核心思路是「分层定位」：先 curl 测通道，再 PHP 测调用，最后看 WordPress 写入。哪一层断，问题就在哪一层，不要一上来就怀疑模型。
6. 把链路用起来：从单篇到批量文档
配置和排错都过了，最后说说怎么把这套东西真正用起来。单篇生成只是验证，批量才是价值。
6.1 从函数列表批量生成参考文档
WordPress 的开发者参考文档通常按函数组织。你可以先整理一份函数名列表，存成数组或 CSV，然后循环调用生成函数，每篇写入一个草稿。核心逻辑和前面一样，只是把 prompt 模板化：
$functions = array('wp_remote_post', 'wp_insert_post', 'get_option'); foreach ($functions as $func) { $title = $func . ' 参考文档'; taotoken_generate_doc_draft($title); sleep(2); // 避免触发频率限制 }sleep(2)是必要的，批量请求太快容易触发 429。如果函数多，建议分批跑，每批之间间隔长一点。
6.2 用定时任务持续更新
WordPress 自带 WP-Cron，可以挂一个每日任务，检查哪些文档需要更新，自动重新生成草稿。这样帮助中心能跟着版本走，不用人工盯。定时任务的钩子写在插件里，回调里调生成函数，注意加日志，方便排查。
6.3 人工审核不能省
AI 生成的参考文档必须人工过一遍。模型可能编造不存在的参数，或者把函数签名写错。草稿状态就是给你审核用的，确认无误再发布。批量生成时尤其要注意，宁可慢一点，也不要让错误内容上线。
6.4 统一 Key 的额度管理
所有调用共用一个 Key，好处是可控，坏处是一处超限全站受影响。建议在控制台设置额度提醒，接近上限时收到通知。如果站点有多个运营，可以按用途分多个 Key，但 Base URL 和模型配置保持一致，这样既统一通道，又能分账。
6.5 下一步可以做什么
链路通了之后，可以扩展的方向不少：把生成逻辑接到自定义文章类型，专门管理参考文档；用分类和标签组织文档结构；在前台加搜索，让读者快速找到函数说明。这些都是在 WordPress 现有能力上叠加，不需要改 AI 调用部分。
如果你要做更复杂的 Agent 类任务，比如让脚本读代码仓库自动产出文档，可以看下 Coding Plan，它面向持续编码场景，和单次生成是互补的。API Key 的管理和文档都在控制台和接入文档里，遇到鉴权问题先去那里对照。
最后留一个实用技巧：把TAOTOKEN_DEFAULT_MODEL设成一个便宜且够用的模型做批量生成，需要高质量单篇时在请求体里覆盖model字段用更强的模型。这样成本和效果都能兼顾。整条链路的关键就是常量、请求、解析、写入四步，任何一步出问题，回到对应章节对照报错即可。
