Module `0xc0ffee::m` ＜a id=“0xc0ffee_m“＞＜/a＞
2026/9/19 0:57:37
1. 从 docmd AI 助手 401/404 切入：Token 应该从 TaoToken 出
在 Node 20 环境里跑 docmd，页面能打开，但内置 AI 助手一问就 401/404？这类问题通常不是 Markdown 写错，而是 AI 助手的 Key 和 Base URL 没落到 TaoToken。先到 TaoToken 官网 创建 Key，后面所有配置都以https://taotoken.net/api为 Base URL。本文面向 Node 开发者，目标很具体：在 Node 环境把 docmd 跑起来，让它把 Markdown 资料变成文档站，并让文档站里的 AI 助手通过 TaoToken 取 Token。真正消耗 Token 的是 docmd 内置 AI 助手，不是 Markdown 渲染，也不是静态站构建。因此你要区分两条链路：一条是 Node CLI 构建与本地预览，另一条是 AI 助手的模型请求。前者依赖 Node 版本和启动命令，后者依赖Base URL + API Key + 模型 ID。只要其中任意一项错了，就会出现“站点正常、AI 助手报错”的割裂现象。下面按可复现顺序拆开：先确认 Node 版本，再启动 docmd，再写环境变量模板，最后把 Claude Code、Codex、CC Switch 的配置分开处理，避免把ANTHROPIC_*错套到 Codex 上。
2. Node 版本与 docmd 启动命令：先把 Markdown 站跑起来
docmd 属于 Node 侧工具链，最稳妥的做法是使用仍然维护中的 LTS。建议 Node20.11.0以上，优先20.18.x或22.12.x；npm 建议10+，pnpm 建议9+。如果你还在 Node 16 或早期 Node 18，常见现象是 CLI 能安装但执行时报ERR_REQUIRE_ESM、fetch is not defined、structuredClone is not defined，或者在读取 Markdown 目录时因为文件系统 API 差异中断。docmd 的 AI 助手还会涉及流式响应、fetch、AbortController等能力，这些在较新的 Node LTS 中更稳定。
先检查本机环境：
node -v npm -v corepack enable pnpm -v如果node -v低于20.11.0，不要硬跑。用 nvm、fnm 或 Volta 切到 Node 20 LTS：
nvm install 20 nvm use 20 node -v接着确认 docmd CLI 是否可执行。不同版本的 docmd 初始化参数可能略有差异，先用--help看当前版本支持哪些子命令：
npx docmd@latest --help如果帮助信息正常输出，就可以初始化一个文档站项目。下面给出一条常见路径，若你的 docmd 版本使用不同子命令，以--help输出为准：
npx docmd@latest init docs-site cd docs-site npm install npm run dev有些版本可以直接用开发模式启动：
npx docmd@latest dev --host 127.0.0.1 --port 5173启动后你应当能看到本地地址，通常是http://127.0.0.1:5173或 CLI 输出的其他端口。此时只证明 Markdown 渲染和静态站服务正常，不代表 AI 助手已经可用。一个推荐的项目结构如下：
docs-site/ docs/ index.md guide/ install.md ai-assistant.md .env.local .gitignore package.json docmd.config.ts.gitignore至少包含：
node_modules/ .env .env.local dist/ .docmd-cache/环境变量模板建议单独放.env.local，不要提交到 Git。下面这份模板覆盖 docmd AI 助手最常用的 OpenAI 兼容风格变量：
DOCMD_AI_PROVIDER=openai-compatible DOCMD_AI_BASE_URL=https://taotoken.net/api DOCMD_AI_API_KEY=YOUR_API_KEY DOCMD_AI_MODEL=YOUR_MODEL_ID DOCMD_AI_TEMPERATURE=0.2 DOCMD_AI_MAX_TOKENS=2048 DOCMD_MCP_ENABLED=true DOCMD_MCP_TRANSPORT=stdio如果你的 docmd 版本直接读取 OpenAI SDK 的通用变量，也可以额外准备一份映射：
OPENAI_BASE_URL=https://taotoken.net/api OPENAI_API_KEY=YOUR_API_KEY OPENAI_MODEL=YOUR_MODEL_ID注意，这里不是说 docmd 一定只认OPENAI_*，而是因为不少 Node 工具会优先读取 OpenAI 兼容变量。核心原则只有一个：Base URL写https://taotoken.net/api，Key 写你在 TaoToken 创建的 Key，模型 ID 写你实际要用的模型。不要把 Key 写进 Markdown，也不要让浏览器前端直接拿到 Key。
启动时加载环境变量：
set -a source .env.local set +a npm run devWindows PowerShell 可以这样临时注入当前进程：
Get-Content .env.local | ForEach-Object { if ($_ -match '^\s*([^#=]+)=(.*)$') { [Environment]::SetEnvironmentVariable($matches[1].Trim(), $matches[2].Trim(), 'Process') } } npm run dev如果启动失败，先分三层排查：Node 版本、docmd CLI 是否可执行、环境变量是否进入进程。不要一上来就改 Markdown 正文，因为 Markdown 只影响文档内容，不影响 AI 助手鉴权。
3. 把 docmd AI 助手切到 TaoToken：Base URL、Key 和模型 ID 三件套
docmd 的 AI 助手能不能回答，取决于它向后端模型服务发请求时带了什么。你需要把三个值对齐：
Base URL：https://taotoken.net/apiAPI Key：YOUR_API_KEY，实际填写你从 TaoToken 创建的 KeyModel ID：YOUR_MODEL_ID，实际填写你要使用的模型标识
先到 TaoToken 官网 的 API Keys 页面创建 Key，然后回到项目里写.env.local。如果你还没有确认模型 ID，可以从 TaoToken 官网 的模型对话入口查看当前可用模型，再把模型 ID 填到DOCMD_AI_MODEL。
如果 docmd 支持配置文件，配置示例可以写成下面这种结构。字段名请以你当前 docmd 版本为准，但核心值不要变：
import { defineConfig } from 'docmd'; export default defineConfig({ title: 'Node 开发文档站', description: 'Markdown 构建，AI 助手走 TaoToken', ai: { enabled: true, provider: 'openai-compatible', baseUrl: process.env.DOCMD_AI_BASE_URL || 'https://taotoken.net/api', apiKey: process.env.DOCMD_AI_API_KEY || 'YOUR_API_KEY', model: process.env.DOCMD_AI_MODEL || 'YOUR_MODEL_ID', temperature: 0.2, maxTokens: 2048 }, mcp: { enabled: true, transport: 'stdio', allowWrite: false } });这段配置的重点不是字段名完全照抄，而是让 docmd 的 AI 助手请求发往https://taotoken.net/api。如果你把 Base URL 写成别的地址，或者 Key 里多了空格、少了字符，AI 助手就会返回 401。如果你把模型 ID 写错，或者 Base URL 路径拼接不符合预期，就会返回 404 或model not found。
配置完成后，不要只看页面是否打开。先直接用 curl 验证 TaoToken 这条链路是否通：
curl -sS https://taotoken.net/api/chat/completions \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "YOUR_MODEL_ID", "messages": [ { "role": "user", "content": "只回复 ok" } ], "stream": false }'如果返回正常，说明 Key、Base URL、模型 ID 至少有一组可用。然后再回到 docmd 页面测试 AI 助手。如果 curl 正常而 docmd 报错，问题在 docmd 的环境变量注入或配置读取；如果 curl 也报 401，问题在 Key；如果 curl 报 404，重点检查模型 ID 和请求路径。
再给一个 Node 侧的最小验证脚本，方便确认fetch在 Node 环境里能否访问 TaoToken：
const baseUrl = process.env.DOCMD_AI_BASE_URL || 'https://taotoken.net/api'; const apiKey = process.env.DOCMD_AI_API_KEY || 'YOUR_API_KEY'; const model = process.env.DOCMD_AI_MODEL || 'YOUR_MODEL_ID'; const res = await fetch(`${baseUrl}/chat/completions`, { method: 'POST', headers: { 'Content-Type': 'application/json', Authorization: `Bearer ${apiKey}` }, body: JSON.stringify({ model, messages: [{ role: 'user', content: '只回复 ok' }], stream: false }) }); console.log(res.status); console.log(await res.text());用 Node 执行：
node --env-file=.env.local check-ai.mjs如果 Node 版本支持--env-file，这种方式比手工导出变量更干净。若你的 Node 版本不支持，就继续用前面的source或 PowerShell 注入方式。
4. docmd 的 MCP 与 AI 助手安全边界：只读文档，不直连生产库
docmd 自带 AI 助手和 MCP，这对文档站很有吸引力：AI 助手可以读取本地 Markdown、目录结构、搜索结果，然后基于文档回答问题。但边界必须提前画清楚。不要让 MCP 或 AI 助手直连生产数据库，也不要让 Agent 自动执行线上 SQL。需要查 SQL 时，由你在本地终端手动执行，再把必要结果粘贴回文档或对话上下文。MCP 的合理用途是只读访问文档目录、本地缓存和公开配置，而不是接管生产环境。
一个偏保守的 MCP 配置形态如下。若你的 docmd 版本没有对应子命令，就不要强行拼造；先确认 CLI 是否支持mcp，再决定是否启用：
{ "mcpServers": { "docmd-local-docs": { "command": "npx", "args": [ "docmd@latest", "mcp", "--docs", "./docs", "--readonly" ], "env": { "DOCMD_AI_BASE_URL": "https://taotoken.net/api", "DOCMD_AI_API_KEY": "YOUR_API_KEY", "DOCMD_AI_MODEL": "YOUR_MODEL_ID" } } } }安全清单建议至少满足：
- 只挂载
docs/、README.md、package.json等非敏感路径。 - MCP 默认只读，写操作必须本地人工确认。
- 不把
.env、私钥、数据库连接串暴露给 MCP。 - 不让 AI 助手生成并自动执行生产命令。
- 需要访问数据库时，只在本地开发库执行，生产库另走审批和审计。
- 文档站 AI 助手只回答文档问题，不承担运维执行器角色。
这样配置后，docmd AI 助手消耗的 Token 仍然从 TaoToken 出，但权限边界由你控制。MCP 负责“让助手看见文档”，TaoToken 负责“让助手有模型能力”，两者不要混成一条不受控的执行链。
5. Claude Code、Codex、CC Switch：同一把 TaoToken Key 的三种写法
很多 Node 开发者会同时使用 docmd、Claude Code、Codex 和 CC Switch。它们可以复用同一把 TaoToken Key，但配置文件不能混。尤其是 Claude Code 使用ANTHROPIC_*，Codex 使用config.toml，不要把这套ANTHROPIC_*套到 Codex 上，否则 Codex 不会按你预期读取。
Claude Code 的settings.json可以这样写：
{ "env": { "ANTHROPIC_BASE_URL": "https://taotoken.net/api", "ANTHROPIC_AUTH_TOKEN": "YOUR_API_KEY", "ANTHROPIC_MODEL": "YOUR_CLAUDE_MODEL_ID", "ANTHROPIC_SMALL_FAST_MODEL": "YOUR_FAST_MODEL_ID" } }如果你在 shell 里临时验证，也可以这样导出：
export ANTHROPIC_BASE_URL="https://taotoken.net/api" export ANTHROPIC_AUTH_TOKEN="YOUR_API_KEY" export ANTHROPIC_MODEL="YOUR_CLAUDE_MODEL_ID" claudeCodex 走config.toml，不要用ANTHROPIC_*。示例：
model = "YOUR_CODEX_MODEL_ID" model_provider = "taotoken" [model_providers.taotoken] name = "TaoToken" base_url = "https://taotoken.net/api" env_key = "TAOTOKEN_API_KEY" wire_api = "chat"对应环境变量：
export TAOTOKEN_API_KEY="YOUR_API_KEY" codexCC Switch 可以把多套配置收拢成“三件套”：
供应商名称：TaoToken Base URL：https://taotoken.net/api API Key：YOUR_API_KEY切换时只改这三项。不要在 CC Switch 里把 Claude Code 的ANTHROPIC_*复制到 Codex 配置，也不要把 Codex 的model_provider写进 Claude Code 的settings.json。docmd 的 AI 助手则继续使用DOCMD_AI_*或 OpenAI 兼容变量。四者共用同一把 Key，但变量命名空间分开，排障时才不会互相污染。
如果你还没有创建 Key，先回到 TaoToken 官网 创建；如果只是在模型选择上犹豫，可以先在模型对话页试一轮，再决定 docmd 默认模型。
6. 常见报错排查表：401、404、429、流式中断、Node ESM
下面按现象排查，不要盲目重装。
| 现象 | 常见原因 | 处理方式 |
|---|---|---|
401 invalid api key | Key 错误、多了空格、复制不完整 | 到 TaoToken 官网重新创建 Key，填YOUR_API_KEY，重启 docmd |
404 model not found | 模型 ID 写错，或 Base URL 拼接不对 | 确认 Base URL 为https://taotoken.net/api，模型 ID 从模型对话页确认 |
429 Too Many Requests | 并发过高或短时间请求过多 | 降低并发，增加退避重试，不要连续刷新 AI 助手 |
| 流式响应中断 | 网络抖动、超时、代理层缓冲 | 先用stream: false验证，再调超时，减少长上下文 |
ERR_REQUIRE_ESM | Node 版本或模块类型不匹配 | 切到 Node 20 LTS，检查package.json的type |
fetch is not defined | Node 版本过旧 | 升级到 Node 20.11+，或使用支持 fetch 的运行时 |
docmd: command not found | 未全局安装或 npx 缓存异常 | 用npx docmd@latest，必要时清理 npx 缓存 |
| AI 回答不引用文档 | MCP 未启用、索引未构建、docs 路径不对 | 检查DOCMD_MCP_ENABLED、./docs路径和只读权限 |
| 浏览器控制台 CORS | 前端直接请求模型服务 | 让 docmd 服务端代理请求，不要把 Key 暴露到浏览器 |
| 页面正常但 AI 无响应 | 环境变量未进入进程 | 在启动命令前加载.env.local，或使用node --env-file |
关于 401，最常见的是 Key 复制时带了换行或空格。建议重新生成后只复制一次，直接写入.env.local，然后完全重启 docmd。关于 404，先确认 Base URL 没有被你改成带路径的地址，例如多了/v1或少了/api。本文统一要求https://taotoken.net/api。关于 429，不要把它理解成配置错误，它通常说明链路已经通了，只是请求频率太高。关于流式中断，先用非流式请求确认最小闭环，再打开流式。
另外，不要把 Key 写进会被提交的文件。推荐：
echo ".env.local" >> .gitignore git status --short如果已经提交过 Key，立刻在 TaoToken 控制台作废并重新创建，不要只删文件内容。
7. 文末 CTA：从模型对话到 Claude Code 文档的落地顺序
到这里，docmd 在 Node 环境的链路应该已经清晰：Node 20 LTS 负责运行 CLI，docmd 把 Markdown 资料组织成文档站，AI 助手通过https://taotoken.net/api取 TaoToken 的模型能力，MCP 只读访问本地文档，Claude Code、Codex、CC Switch 各自使用独立配置。接下来按顺序落地即可：
先去模型对话页验证模型是否可用：
https://taotoken.net/models/detail/chat?utm_source=taotoken_aicg_blog_end&utm_content=docmd_node_chat如果你准备长期在编码工具里使用，查看 Coding Plan：
https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_content=docmd_node_coding创建或重新生成 API Key，填入
YOUR_API_KEY：
https://taotoken.net/console/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=docmd_node_keys需要配置 Claude Code 时，对照 Claude Code 文档里的
settings.json和ANTHROPIC_*写法：
https://taotoken.net/doc/ClaudeCodeAnthropic?utm_source=taotoken_aicg_blog_end&utm_content=docmd_node_claude
最后检查一遍你的项目：.env.local里只有YOUR_API_KEY占位、Base URL 是https://taotoken.net/api、模型 ID 来自实际可用列表、MCP 没有暴露生产库、Codex 没有误用ANTHROPIC_*。完成这些后，再启动npm run dev或npx docmd@latest dev，docmd 的 AI 助手就会按预期工作。