企业官网建设流程全解析

1. AGENTS.md 的 Token 开销与 TaoToken Key 分配

仓库根目录放一份 AGENTS.md，编码助手每一轮对话读取它都会消耗 Token，规则写得越冗长，固定开销和输出噪声一起上涨。要让这套流程稳定运行，先在 https://taotoken.net/?utm_source=taotoken_aicg_blog_end&utm_content=agents_md_key 获取 TaoToken 的 Key，再把 Base URL 设置为 https://taotoken.net/api，Claude Code、Codex、CC Switch 可以共用同一个接口地址。

这份文件承担的任务很具体：约束编码模型维护后端仓库时的行为，减少过度工程，减少含糊不清的表述。实际项目里经常出现的状况是，模型读完一份五百行的规则文件，仍然会在一个接口改动里塞进三层抽象，仍然会用 try/except 把错误吞掉，仍然会在回答末尾补一段没有信息量的概括。规则写进文件只是起点，规则能否在每一轮对话中被稳定执行，取决于文件是否简短、是否可检查、是否覆盖了真正会出问题的地方。

编码模型读取 AGENTS.md 是一个重复动作。会话开始读取一次，子任务开始时可能再读一次，模型在长上下文里还会反复回看。假设一份规则文件有两千个 Token，一个下午开二十次会话，光规则本身的读取就产生四万 Token 的固定消耗。这个数字在单机开发里看起来不大，放到多人协作的仓库里，再叠加每次改动附带的文件读取与推理，账单会变得难以预估。先把规则文件压缩到必要内容，再分配一把专用 Key，是成本可控的两个前提。

2. 把规则写成可判定的条目：精简版 AGENTS.md 片段

规则的写法决定它能否被模型执行。“写代码要优雅”这类要求没有判定标准，模型只能自行解释。“依赖直接 import，禁止用 try/except 包裹 import”有明确边界，模型读到之后可以直接对照当前改动检查。

下面是一份可以直接放进仓库根目录的 AGENTS.md 片段，覆盖后端开发者使用编码助手时最容易出问题的几个方面。

# 仓库编码约定 ## 执行强度 本文件每一条规则都强制生效。临时改动、一次性命令、命令行里的快捷操作同样受约束。 ## 语言要求 - 使用两个汉字及以上的完整词语，禁止单字缩写。 - 回答里不出现总起段落与概括段落。 - 没有要求对比时不做对比。 - 不使用含义模糊、只有特定行业才懂的词汇。 - 描述操作时写完整的动宾结构，写清动作和对象。 ## 方案设计 - 每个任务给出一个完整方案，一次讲清楚。 - 不写“先做简易版本，后续再补充”这类措辞。 - 多个方案并列时，每个方案都必须独立成立。 ## 代码行为 - 需要的依赖直接 import，禁止在 import 外层套 try/except。 - 未经明确要求，禁止进入计划模式。 - 禁止使用 `git reset`、`git restore`、`git checkout --` 还原代码。 需要恢复时手动编辑文件，把内容改回上一个状态。 - 禁止读写 `/tmp`。中间结果写入 `./.scratch/`，并把该目录加入 `.gitignore`。 - 错误处理采用 fast-fail，在出错位置直接抛出异常，禁止兜底返回值。 - 禁止 mock、伪造数据、只为通过测试的绕过手段。 - 禁止手动解析二进制格式，使用成熟的第三方库完成解析。 - 禁止输出 ASCII 图形，需要图示时使用 mermaid。 - 引用网页链接前，先读取链接里的完整内容。 ## 协作节奏 - 我撤回或修改你的改动后，重新读取文件，在当前内容基础上继续。 - 实现完成后必须运行测试，测试通过才算结束。 - 任务进行中我插入其他问题，先回答，然后回来继续原任务。

这份文件大约一百二十行，展开之后不到两千个汉字。相比把每一条规则的来龙去脉都写进去的版本，它省掉了大段解释，只保留可检查的约束。模型读到“禁止使用git reset”时可以直接判断，读到“错误处理采用 fast-fail”时也知道该往哪个方向写。

规则文件里不要放项目背景介绍、架构演进历史、过往故障复盘。这些内容属于 README 或者设计文档，放进 AGENTS.md 只会抬高每一轮对话的固定开销。

3. Key 分配：按用途拆开，避免一把钥匙到处贴

TaoToken 控制台里创建 Key 的位置是 https://taotoken.net/console/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=api_keys 。打开之后建立三把 Key，分别用于不同场景。

第一把给 Claude Code。这把 Key 的特点是调用频率高，会话长度大，需要单独观察用量。第二把给 Codex，用于命令行里的代码补全与批量改写。第三把留给脚本与临时验证，比如用 curl 探测接口是否连通，或者在其他工具里做一次性测试。

三把 Key 分开的好处很直接。某一把 Key 的用量异常时，可以立刻判断是哪一类调用出了问题。某个工具不再使用，直接删除对应 Key，其他工具的配置不受影响。

创建完成之后，把 Key 写进 shell 的环境变量文件，不要写进仓库里的任何文件。以 zsh 为例：

# ~/.zshrc export TAOTOKEN_CLAUDE_KEY="YOUR_API_KEY" export TAOTOKEN_CODEX_KEY="YOUR_API_KEY" export TAOTOKEN_SCRIPT_KEY="YOUR_API_KEY"

修改之后重新加载配置：

source ~/.zshrc

检查变量是否生效，同时确认输出里没有把真实 Key 打印到终端历史里：

print -r -- "${TAOTOKEN_CLAUDE_KEY:0:8}"

仓库里的.env.example只写变量名称与占位符，真实值放在本地.env，并且把.env加入.gitignore。这条规则也应当写进 AGENTS.md，避免模型在某次“顺手补充配置”时把密钥写进示例文件。

4. Claude Code 接入：settings.json 与环境变量

Claude Code 读取的配置文件位于用户目录下的~/.claude/settings.json。用 TaoToken 作为供应方时，把接口地址与密钥写进env字段。

{ "env": { "ANTHROPIC_BASE_URL": "https://taotoken.net/api", "ANTHROPIC_AUTH_TOKEN": "YOUR_API_KEY" }, "permissions": { "allow": [ "Read", "Edit", "Bash(git status)", "Bash(git diff)" ], "deny": [ "Bash(git reset --hard)", "Bash(git checkout -- *)", "Bash(rm -rf /tmp/*)" ] } }

ANTHROPIC_BASE_URL指向 TaoToken 的接口地址，ANTHROPIC_AUTH_TOKEN填入刚才创建的第一把 Key。部分版本的 Claude Code 会读取ANTHROPIC_API_KEY，如果启动后提示没有凭据，把ANTHROPIC_API_KEY也设为同一个值即可。两个变量同时存在不会引起冲突，后者只是前者的兼容形式。

permissions.deny这一段和 AGENTS.md 里的规则是互补关系。AGENTS.md 用自然语言告诉模型“不要用 git reset 还原代码”，permissions.deny从工具调用层面直接拦截这条命令。规则文件管的是模型的判断，权限配置管的是实际执行。两者都配置，模型在受限操作上被拦下来的概率会明显提高。

配置写完之后进入仓库验证：

cd ~/projects/order-service claude

在会话里输入一条检查提示词：

读取 AGENTS.md，然后列出本次改动涉及的文件路径，不要输出其他内容。

如果 Claude Code 返回的路径与当前仓库结构一致，说明 Key、Base URL、规则文件读取三条链路都通了。

5. Codex 接入：config.toml 与 OpenAI 兼容协议

Codex 使用~/.codex/config.toml保存配置。它走的是 OpenAI 兼容协议，环境变量名称与 Claude Code 完全不同，不要把ANTHROPIC_*写进 Codex 配置里。

model = "gpt-5-codex" model_provider = "taotoken" [model_providers.taotoken] name = "TaoToken" base_url = "https://taotoken.net/api/v1" env_key = "TAOTOKEN_CODEX_KEY" wire_api = "chat"

env_key填的是环境变量名称，不是密钥本身。config.toml 会被提交到点文件仓库或者被同步到其他机器，把密钥明文写在里面等于公开。

环境变量在 shell 里设置：

export TAOTOKEN_CODEX_KEY="YOUR_API_KEY"

base_url这里写成https://taotoken.net/api/v1，原因是 OpenAI 兼容客户端通常会在路径后面拼接/chat/completions。如果当前 Codex 版本要求不带/v1，把这一行改成https://taotoken.net/api即可，两种写法的区别只在路径拼接方式。

验证方式是在仓库目录里执行一条无交互指令：

codex exec "读取 AGENTS.md，说明当前仓库禁止使用的三个 Git 命令"

返回结果里出现git reset、git restore、git checkout --三条，说明 Codex 已经正确读取规则文件。没有出现，先检查 Codex 的工作目录是否在仓库根目录，再检查AGENTS.md的文件名大小写是否正确。

6. CC Switch 三件套：供应方、密钥、默认模型

同时在多个项目里切换供应方时，反复修改settings.json和config.toml容易出错。CC Switch 这类切换工具把配置拆成三件套管理：供应方信息、密钥、默认模型。

第一项是供应方信息，填写名称TaoToken和接口地址https://taotoken.net/api。第二项是密钥，填YOUR_API_KEY，指向 TaoToken 控制台里创建的那把 Key。第三项是默认模型，填写当前账号可用的模型名称。

模型名称可以在模型对话页面确认，地址是 https://taotoken.net/models/detail/chat?utm_source=taotoken_aicg_blog_end&utm_content=model_chat 。在页面里发一条测试消息，返回正常说明 Key 与模型都可用。把页面上列出的模型名称填进 CC Switch 的默认模型字段，避免在配置里写入不存在的名称，导致请求返回模型不匹配的错误。

三件套配置完成之后，切换供应方只需要在工具界面里点一次。切换动作会同步更新 Claude Code 与 Codex 读取的配置，不需要手工改两个文件。切换完成后仍然要执行一次验证命令：

claude -p "列出当前工作目录下的前五个文件和目录"

输出内容与ls的结果吻合，说明切换生效。

7. 终端问答对照：约束生效前后的输出差异

规则文件是否起作用，最直观的检验方式是拿同一条提示词跑两次，对比输出。下面用一条真实场景里的提示词做对照，任务是修改订单服务的重试次数。

把 order_service 里的重试次数从 3 改成 5。

没有规则约束时，编码助手容易给出这样的输出：

好的，我来分析一下这个问题。当前实现使用了固定重试次数， 这个做法存在改进空间。建议引入一个可配置的 RetryPolicy 抽象层， 支持指数退避、熔断、降级三种策略，同时把重试次数外置到配置文件， 再补充一套重试指标上报…… （后续展开四十行，涉及四个新文件）

有 AGENTS.md 约束时，输出会收敛到改动本身：

修改 order_service/retry.py 第 18 行： RETRY_TIMES = 3 改为 RETRY_TIMES = 5 未新增文件，未改动调用方。

第二种输出可以直接对照 diff 检查，第一种输出需要花时间判断哪些改动是任务要求的、哪些是额外添加的。规则文件里的“每个任务给出一个完整方案，一次讲清楚”和“不写先做简易版本这类措辞”，针对的就是第一种输出。

再换一条提示词，检查语言层面的约束：

解释一下这段代码里为什么用读写锁。

约束生效的输出应该是直接说明读写锁适用于读多写少的场景，说明当前代码里读操作的调用频率高于写操作，因此选择读写锁可以减少读读之间的等待。约束生效不够彻底的输出会在结尾追加“综上所述，读写锁是一种非常重要的并发控制手段”，这类句子没有传递新信息，属于规则文件里明确禁止的概括段落。

8. 规则分层与 Token 控制：降低长仓库的读取开销

仓库变大之后，把所有规则塞进根目录的 AGENTS.md 会让每一轮对话都承担完整开销。合理的做法是分层。

根目录的 AGENTS.md 只放全局规则：语言要求、Git 操作限制、临时目录位置、错误处理方式。这些规则在任何子目录里都适用。

子目录的 AGENTS.md 放局部规则：某个服务的接口约定、某个模块的测试命令、某类文件的命名方式。Codex 会读取当前工作目录以及上层目录里的 AGENTS.md，进入子目录工作时自动加载对应规则。

Claude Code 读取的文件名是CLAUDE.md。在仓库根目录建立一份CLAUDE.md，内容只有一行：

@AGENTS.md

这样两份工具共用同一份规则内容，修改时只需要改 AGENTS.md，不需要在两个文件之间同步。

检查规则文件的体积：

wc -l AGENTS.md CLAUDE.md find . -name "AGENTS.md" -not -path "./node_modules/*" | xargs wc -l

根目录文件超过两百行时，考虑把其中一部分内容拆到子目录。判断标准是这条规则是否只在特定目录里生效。全局生效的留下，局部生效的下移。

另一个容易忽略的开销来源是把规则文件内容粘贴进对话。每次粘贴都会在上下文里重复一份完整文本，开销比文件读取更高。正确的做法是让工具自己读取文件，在提示词里只写文件名和检查目标。

9. 常见接入故障排查

接入过程中出现频率较高的几类问题，处理方式如下。

返回 401 或提示缺少凭据，先检查环境变量是否在当前的 shell 会话里生效。新开的终端窗口不会自动继承另一个窗口里临时 export 的变量，需要写进~/.zshrc或者~/.bashrc。检查方式是打印变量前八个字符，确认输出非空。

返回 404，通常来自 Base URL 的路径拼接。Claude Code 使用https://taotoken.net/api，Codex 使用https://taotoken.net/api/v1，两者不要互相替换。把 Anthropic 协议的地址填进 Codex，请求路径会拼成不存在的组合。

提示模型名称不存在，检查配置文件里的模型名称是否与控制台里列出的名称完全一致。名称里的连字符、版本号后缀都要对上。

Claude Code 没有读取到规则文件，先确认工作目录。CLAUDE.md需要在仓库根目录，子目录里的规则通过@语法引入。启动会话之后可以用一条提示词确认：

复述 AGENTS.md 里关于临时目录的规则，只输出这一条。

输出内容为空，说明文件没有被读取。检查文件名大小写，检查文件编码，检查是否存在同名但扩展名不同的文件。

Codex 返回协议错误，检查wire_api字段。使用聊天补全接口时填chat，这条字段与 Base URL 的路径形式需要匹配。

把上面几条排查命令整理成一个脚本放进仓库，命名为scripts/check-provider.sh，执行时依次打印环境变量、接口连通性、规则文件行数。脚本内容写进仓库，执行权限在本地设置，密钥从环境变量读取。

10. 接入路径与后续步骤

在 TaoToken 官网 https://taotoken.net/?utm_source=taotoken_aicg_blog_end&utm_content=agents_md_flow 完成账号注册之后，按下面的顺序走一遍，整套配置可以在半小时内跑通。

先在模型对话页面 https://taotoken.net/models/detail/chat?utm_source=taotoken_aicg_blog_end&utm_content=model_chat 发一条测试消息，确认账号可以正常调用模型。这一步不涉及任何本地配置，用来排除账号层面的问题。

接着查看 Coding Plan https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_content=coding_plan ，根据每天的编码会话数量选择合适的方案。编码助手的特点是调用频繁、单次上下文长，按会话次数估算用量比按单次请求估算更接近实际。

然后进入控制台创建 Key，地址是 https://taotoken.net/console/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=api_keys 。按照前面第 3 节的分配方式建立三把 Key，分别写入 shell 环境变量。

最后打开 Claude Code 文档 https://taotoken.net/doc/ClaudeCodeAnthropic?utm_source=taotoken_aicg_blog_end&utm_content=claude_code_doc ，对照文档核对settings.json的字段名称与当前版本的要求。文档里会列出当前支持的模型名称，把名称填进配置文件的对应字段。

配置完成之后回到仓库，把第 2 节的 AGENTS.md 片段放进根目录，建立指向它的CLAUDE.md，然后执行第 7 节的对照提示词。输出收敛到具体文件和具体行号，说明规则文件、接口地址、密钥三条链路都已经正常工作。