企业官网建设流程全解析

1. RuoYi-Cloud-Plus 微服务项目里 AI 助手为什么总“接不上”

RuoYi-Cloud-Plus 是 Dromara 社区维护的一套企业级微服务脚手架，后端基于 Java 17、Spring Boot 3.5.9、Spring Cloud 2025.0.1、Apache Dubbo 3.3.6、Nacos 2.5.1、Seata 2.5.0、MyBatis-Plus 3.5.16、Sa-Token 1.44.0，前端是 Vue 3.5 + Element Plus 2.11 + TypeScript + Pinia。模块拆得细，ruoyi-gateway、ruoyi-auth、ruoyi-modules 下 system/gen/job/resource/workflow 各自独立，ruoyi-common 有 34 个公共模块，ruoyi-api 放 Dubbo 远程接口定义。这种结构对人是清晰的，对 AI 编程助手却是个挑战：模型不知道你的 Dubbo 服务怎么暴露、Sa-Token 鉴权链路怎么走、Seata 的 @GlobalTransactional 该加在哪一层。

我一开始用 Claude Code 直接开在项目根目录，问它“帮我加一个部门数据权限”，它给出来的代码用的是 Feign 调用，而项目里实际走的是 Dubbo；问它“Gateway 鉴权怎么配”，它把 Sa-Token 的拦截器写到了业务模块里。问题不在模型能力，而在于它缺少这个项目的“上下文知识库”。Codex 那边也一样，OpenAI Codex CLI 默认读的是通用工程习惯，对 RuoYi-Cloud-Plus 的 BO/VO 分离、构造注入、MapStructUtils 这些约定并不了解。

另一个更现实的卡点是鉴权入口。Claude Code 和 Codex 是两套独立的 CLI，各自有自己的配置目录和鉴权方式。如果分别去申请、分别去配，Key 管理会变成一团乱麻，团队里几个人共用一台开发机时更麻烦。我试过把两套引擎的调用通道统一到一个 Key 上，用 TaoToken 作为统一的 API 入口，这样 Claude Code 走 Anthropic 协议、Codex 走 OpenAI 协议，但底层鉴权和计费是同一套。下面就把这套配置完整拆开，包括 settings.json、auth.json 的可复制片段，以及 41+ 专业技能在微服务模块里怎么触发验证。

这套方案适合谁：正在用 RuoYi-Cloud-Plus 做企业级微服务开发、想让 AI 助手真正理解 Dubbo + Sa-Token + Seata 技术栈、并且希望用一套 Key 同时驱动 Claude Code 和 Codex 的开发者。不需要你改项目业务代码，只需要在项目根目录放两个配置目录。

2. TaoToken 统一 Key 的前置准备与双引擎通道关系

在动手改配置之前，先把“一套 Key 跑通双引擎”这件事的逻辑理清楚。Claude Code 默认走的是 Anthropic 的 Messages API 协议，请求路径和鉴权头是x-api-key；OpenAI Codex CLI 走的是 OpenAI 的 Chat Completions / Responses 协议，鉴权头是Authorization: Bearer。两者协议不同，但都可以指向同一个兼容网关。TaoToken 提供的就是这样一个统一入口：你拿到一个 Key，在 Claude Code 的 settings.json 里配 Anthropic 兼容的 Base URL，在 Codex 的 auth.json 里配 OpenAI 兼容的 Base URL，两个引擎各自用自己的协议发请求，网关侧统一鉴权。

前置准备分三步。第一步是拿到 Key。访问 TaoToken 控制台创建 API Key，建议按项目或按人建多个 Key，方便后面排查是哪个引擎在消耗额度。控制台地址是 https://taotoken.net/console ，创建 Key 的页面在 https://taotoken.net/api-keys 。拿到形如sk-xxxxxxxx的字符串后先存好，后面两个配置文件都要用。

第二步是确认模型 ID。Claude Code 侧需要 Anthropic 系列的模型 ID，Codex 侧需要 OpenAI 系列的模型 ID。具体可用模型列表在文档里查：https://taotoken.net/doc 。不要凭记忆写模型名，写错了会直接报 model not found。我一般会在文档里把要用的两个模型 ID 复制到记事本，配置时直接粘贴。

第三步是确认项目目录结构。RuoYi-Cloud-Plus 的根目录下应该有 ruoyi-gateway、ruoyi-auth、ruoyi-modules、ruoyi-common、ruoyi-api、plus-ui 这些目录。Claude Code 的配置放在.claude/目录，Codex 的配置放在.codex/目录，两个目录都和业务模块平级。如果你是从配置包复制过来的，.claude/里会有 settings.json、hooks/、commands/、skills/ 四个子项，.codex/里会有 codex.md 和对应的技能镜像。这里要注意：配置目录必须放在项目根目录，不能放在某个子模块里，否则 Claude Code 启动时找不到 CLAUDE.md 主指令文件。

关于通道关系，可以用一个表格对照：

两套配置共享同一个 Key，但 Base URL 的写法略有差异，下一节给完整片段。这里先提醒一个容易踩的坑：不要把 Key 硬编码到 CLAUDE.md 或 codex.md 里，那两个文件是给模型读的指令文件，Key 写在里面既不安全也容易被模型在输出里带出来。Key 只放在 settings.json 和 auth.json 这两个鉴权文件里。

3. 可复制的 settings.json 与 auth.json 配置片段

这一节是全文最核心的部分，两个配置文件都给完整可复制片段。先看 Claude Code 侧。在项目根目录的.claude/settings.json里写入以下内容：

{ "env": { "ANTHROPIC_BASE_URL": "https://taotoken.net/api", "ANTHROPIC_API_KEY": "sk-你的TaoToken密钥", "ANTHROPIC_MODEL": "claude-sonnet-4-20250514" }, "permissions": { "allow": [ "Read", "Write", "Edit", "Bash(mvn:*)", "Bash(git:*)", "Bash(npm:*)" ], "deny": [ "Read(./**/application.yml)", "Read(./**/bootstrap.yml)", "Read(./**/*.pem)", "Read(./**/*.key)" ] }, "hooks": { "PreToolUse": [ { "matcher": "Write|Edit", "hooks": [ { "type": "command", "command": "bash .claude/hooks/pre-tool-use.sh" } ] } ] } }

这里有几个点要说明。ANTHROPIC_BASE_URL填的是 TaoToken 的 API 地址，注意不要带末尾斜杠，带了有些版本会拼出双斜杠导致 404。ANTHROPIC_MODEL填你在文档里查到的模型 ID，上面这个只是示例，以文档为准。permissions.deny里把 application.yml、bootstrap.yml、密钥文件都挡掉，这是配合 pre-tool-use 钩子做安全检查，防止 AI 误改 Nacos 和 Seata 的核心配置。hooks.PreToolUse指向.claude/hooks/pre-tool-use.sh，这个脚本在配置包里已经带好，不用自己写。

再看 Codex 侧。在项目根目录的.codex/auth.json里写入：

{ "OPENAI_API_KEY": "sk-你的TaoToken密钥", "OPENAI_BASE_URL": "https://taotoken.net/api", "OPENAI_MODEL": "gpt-5-codex", "tokens": { "access_token": "sk-你的TaoToken密钥", "refresh_token": "" } }

Codex 的 auth.json 结构在不同版本里略有差异，有的版本读OPENAI_API_KEY，有的版本读tokens.access_token，所以上面两个都填上同一个 Key，兼容性最好。OPENAI_BASE_URL同样不带末尾斜杠。模型 ID 以文档为准，gpt-5-codex只是占位示例。

如果你用的是 Codex 的 TOML 配置方式（部分版本支持~/.codex/config.toml），对应片段是：

[model_providers.taotoken] name = "TaoToken" base_url = "https://taotoken.net/api" env_key = "TAOTOKEN_API_KEY" [profiles.ruoyi] model = "gpt-5-codex" model_provider = "taotoken"

然后在 shell 里 exportTAOTOKEN_API_KEY=sk-你的密钥。这种方式的好处是 Key 不落在项目文件里，适合团队共用开发机。

配置放好后，项目根目录结构应该是这样：

your-ruoyi-cloud-plus-project/ ├── .claude/ │ ├── settings.json │ ├── hooks/pre-tool-use.sh │ ├── commands/ │ └── skills/ ├── .codex/ │ ├── auth.json │ └── codex.md ├── CLAUDE.md ├── ruoyi-gateway/ ├── ruoyi-auth/ ├── ruoyi-modules/ ├── ruoyi-common/ ├── ruoyi-api/ └── plus-ui/

CLAUDE.md 是项目主指令文件，里面写的是 RuoYi-Cloud-Plus 的技术栈约定、模块职责、编码规范，模型每次启动都会读它。这个文件不要塞 Key，只放项目知识。Codex 侧的 codex.md 是镜像技能说明，49 个镜像技能 + 6 命令技能 + 3 管理技能都在里面。

配置完成后，在项目根目录分别启动两个引擎验证：

# Claude Code claude # OpenAI Codex codex

启动后先别急着写业务代码，下一节用具体请求验证两个引擎是否真的通了。

4. 验证请求与 41+ 专业技能在微服务模块中的触发结果

配置写完不等于通了，得用真实请求验证。先验证 Claude Code 侧。在项目根目录启动claude，进入交互界面后输入一个能触发技能评估的问题，比如“帮我在 ruoyi-modules/ruoyi-system 下新增一个部门数据权限的 Dubbo 服务方法”。正常情况下，skill-forced-eval 钩子会先列出匹配到的技能，你会看到类似这样的输出：

[skill-forced-eval] 匹配技能： - data-permission（触发词：数据权限、部门权限、DubboDataPermission） - dubbo-rpc（触发词：Dubbo、@DubboService、@DubboReference） - crud-development（触发词：业务模块、Service） 激活技能中...

然后模型才会开始生成代码。如果它直接开始写代码、没有技能评估这一段，说明钩子没生效，回去检查 settings.json 里 hooks 的路径和 pre-tool-use.sh 的执行权限。技能激活率从约 25% 提升到 90% 以上，靠的就是这个强制评估环节。

验证 Codex 侧。启动codex后输入“用 Easy-ES 给 ruoyi-modules 加一个全文检索接口”，观察它是否调用了 elasticsearch 技能。Codex 侧是 49 个镜像技能，触发逻辑和 Claude Code 一致，但输出格式略有不同。如果 Codex 报 401，先看下一节的排查表。

再验证一个跨模块的复杂请求，比如“ruoyi-gateway 的 Sa-Token 鉴权链路是怎么走的，我要在网关加一个限流过滤器”。这个问题会同时触发 api-gateway、security-auth、microservice-architecture 三个技能。Claude Code 应该能准确说出 Gateway 在 8080 端口、Sa-Token 拦截器在网关层、限流用哪种过滤器，而不是把鉴权写到业务模块。这就是技能知识库起作用的地方——它把 RuoYi-Cloud-Plus 的架构约定喂给了模型。

验证 41+ 技能是否完整加载，可以在 Claude Code 里输入/progress或/next这类快捷命令。6 大快捷命令里，/dev是全栈代码生成，/crud是基于已有表快速生成，/check是代码规范检查，/progress是进度报告，/next是下一步建议，/start是项目快速启动。输入/check后，模型会按 RuoYi-Cloud-Plus 规范检查构造注入、BO/VO 分离这些点。如果命令没反应，检查.claude/commands/目录是否完整。

一个实测下来比较有用的验证方式是让它解释 Dubbo 和 Feign 在这个项目里的选择。正确回答应该指出项目用 Apache Dubbo 3.3.6 做 RPC，接口定义在 ruoyi-api 模块，用 @DubboService 暴露、@DubboReference 引用，而不是 Feign。如果模型答成 Feign，说明 dubbo-rpc 技能没激活，回去检查技能目录里的触发词配置。

验证通过后，日常开发就可以正常用了。写 CRUD 时它会自动带出 Entity/BO/VO/Mapper/Service/Controller 全套；写分布式事务时会提醒你 @GlobalTransactional 加在 Service 层、Seata 2.5.0 的协调服务在 8091 端口；写定时任务时会用 SnailJob 而不是 Quartz。这些细节靠通用模型是给不出来的，必须靠技能库。

5. 本篇常见报错排查：401、local proxy failed、reading choices、OAuth

配置过程中最容易撞上的几类报错，逐个拆。

401 Unauthorized。两个引擎都可能报。Claude Code 侧报 401，先确认 settings.json 里ANTHROPIC_API_KEY是不是完整的sk-开头字符串，有没有多余空格或换行。然后确认ANTHROPIC_BASE_URL是https://taotoken.net/api，不要写成带/v1的路径，也不要带末尾斜杠。Codex 侧报 401，检查 auth.json 里OPENAI_API_KEY和tokens.access_token是否都填了同一个 Key。如果用的是 TOML 方式，确认 shell 里TAOTOKEN_API_KEY已经 export 且当前终端能echo $TAOTOKEN_API_KEY出来。还有一种情况是 Key 被控制台禁用或额度耗尽，去 https://taotoken.net/api-keys 看一眼状态。

local proxy failed。这个报错通常出现在 Claude Code 启动阶段，提示本地代理连接失败。原因是 settings.json 里配了HTTP_PROXY或HTTPS_PROXY之类的环境变量，但本地并没有对应的代理服务在跑。解决办法是把 settings.json 的 env 里所有 proxy 相关变量删掉，只保留ANTHROPIC_BASE_URL和ANTHROPIC_API_KEY。TaoToken 的 API 地址是直连的，不需要额外代理配置。如果系统级环境变量里有 proxy，用unset HTTP_PROXY HTTPS_PROXY清掉再启动。

reading choices 相关报错。这个一般出现在 Codex 侧，报错信息里带reading choices或choices字段解析失败。原因是 Codex 用的模型 ID 和实际返回的响应格式不匹配，比如你填了一个只支持 Responses 协议的模型，但 Codex 按 Chat Completions 解析。解决办法是去文档 https://taotoken.net/doc 确认该模型 ID 支持的协议，换成兼容的模型。另外确认OPENAI_BASE_URL没有多写路径段。

OAuth 相关报错。Codex 某些版本启动时会尝试走 OAuth 登录流程，报OAuth或login required。这是因为 auth.json 没被正确读取，CLI 回退到了交互式登录。确认 auth.json 放在.codex/目录下且文件名正确，JSON 格式没有语法错误（可以用python -m json.tool .codex/auth.json校验）。如果还是走 OAuth，检查 Codex 版本，部分版本需要codex --config .codex/auth.json显式指定配置路径。

技能不激活。不是报错但比报错更隐蔽。表现是模型直接写代码，没有 skill-forced-eval 的评估输出。检查.claude/hooks/pre-tool-use.sh是否有执行权限（chmod +x），检查 settings.json 里 hooks 的 matcher 是否写对。Codex 侧检查 codex.md 是否在.codex/目录下且被正确引用。

模型 ID 写错。报model not found或invalid model。这个没有捷径，去文档里复制准确的模型 ID。Claude Code 和 Codex 用的模型 ID 不一样，不要混用。

排查顺序建议：先看 Key 和 Base URL，再看配置文件路径和格式，最后看模型 ID 和协议匹配。大部分问题出在前两步。

6. 一套 Key 跑通双引擎后的日常使用与入口

配置跑通之后，日常开发就是在项目根目录启动claude或codex，按场景切换。写后端微服务模块、调 Dubbo 接口、配 Seata 事务，用 Claude Code，它的技能系统 + 钩子系统支持最完整；做前端原型、快速验证一个想法，用 Codex，49 个镜像技能覆盖前端和命令场景。两个引擎共享同一套技能知识库，切换成本很低。

Key 的管理建议按人分配。团队里每个人在控制台建自己的 Key，填到各自的 settings.json 和 auth.json 里。这样出问题时能快速定位是谁的调用、哪个引擎在消耗额度。控制台入口在 https://taotoken.net/console ，Key 管理在 https://taotoken.net/api-keys 。

如果你需要长期跑编码任务、或者想让 Agent 持续工作，可以了解 Coding Plan，入口在 https://taotoken.net/coding-plan 。模型对话类的快速验证用 https://taotoken.net/models 。接入文档和模型列表都在 https://taotoken.net/doc ，配置过程中遇到协议或模型 ID 问题优先查这里。

最后说一个实际经验：配置文件和技能库是两回事，配置文件决定“能不能通”，技能库决定“通得好不好”。很多人卡在 401 就放弃了，其实通完之后技能激活才是真正提升效率的地方。RuoYi-Cloud-Plus 这种模块多、约定细的项目，AI 助手有没有技能库，产出代码的可用性差距很大。先把 Key 和 Base URL 配对，再用一个 Dubbo 相关的请求验证技能激活，两步都过了，这套双引擎配置就算真正落地了。