diff --git a/CLAUDE.md b/CLAUDE.md
index ee40aa3f..961d758e 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -34,8 +34,8 @@ npm run test:coverage     # Jest with coverage
 npm run test:update       # Update test snapshots
 # Run a single test: npx jest src/pages/user/login/login.test.tsx
 
-# Code Generation
-npm run openapi    # Regenerate services from config/oneapi.json (overwrites src/services/)
+# Code Generation (OpenAPI — disabled by default, see below)
+# npm run openapi    # Regenerate services from config/oneapi.json (overwrites src/services/)
 
 # Other
 npm run simple     # Irreversible: removes most page blocks for minimal version
@@ -69,7 +69,7 @@ Umi Max (`@umijs/max`) is the meta-framework. It wraps the build pipeline and pr
 
 ### API & Request Layer
 
-- **Auto-generated services** in `src/services/ant-design-pro/` — do NOT edit manually; regenerate with `npm run openapi`
+- **Auto-generated services** in `src/services/ant-design-pro/` — do NOT edit manually; regenerate with `npm run openapi` (openapi plugin disabled by default — see Gotchas below)
 - **Per-page services**: many pages have co-located `service.ts` files
 - **Request config**: centralized in `src/requestErrorConfig.ts` (error handler, interceptors, base URL). The `request` export in `app.tsx` sets global `RequestConfig`
 - Built-in `request` function from `@umijs/max` — no manual axios wrapping needed
@@ -157,5 +157,6 @@ The CLI also supports MCP server mode: `npx antd mcp` (for IDE integrations).
 - **Mock not updating**: Umi usually auto-discovers `mock/` and `src/pages/**/_mock.ts` changes. If a new file isn't recognized, try restarting the dev server
 - **Biome + antd lint**: Both must pass before committing. `npm run lint` runs Biome + tsc; `npx antd lint ./src` runs separately. Do not install ESLint or Prettier — this project uses Biome only
 - **`src/services/` is auto-generated**: Never edit manually. Run `npm run openapi` to regenerate
+- **OpenAPI plugin disabled by default**: To re-enable, uncomment `@umijs/max-plugin-openapi` in `plugins` and the `openAPI` config in `config/config.ts`, uncomment the OpenAPI link in `src/app.tsx`, install `swagger-ui-dist`, then run `npm run openapi`
 - **`npm run simple` is irreversible**: Always commit or branch before running it
 - **Lock file**: Uses `package-lock.json`. If deps break, delete `node_modules` and reinstall
diff --git a/config/config.ts b/config/config.ts
index c0ba6394..b88f68c1 100644
--- a/config/config.ts
+++ b/config/config.ts
@@ -191,22 +191,25 @@ export default defineConfig({
   ],
 
   //================ pro 插件配置 =================
-  plugins: ['@umijs/max-plugin-openapi', '@umijs/request-record'],
+  plugins: ['@umijs/request-record'],
 
   /**
    * @name openAPI 插件的配置
    * @description 基于 openapi 的规范生成serve 和mock，能减少很多样板代码
+   * 如需启用，请取消下方注释，并在 plugins 中添加 '@umijs/max-plugin-openapi'，
+   * 安装 swagger-ui-dist 依赖，然后运行 npm run openapi 生成服务代码
    * @doc https://pro.ant.design/zh-cn/docs/openapi/
    */
-  openAPI: [
-    {
-      requestLibPath: "import { request } from '@umijs/max'",
-      // 或者使用在线的版本
-      // schemaPath: "https://gw.alipayobjects.com/os/antfincdn/M%24jrzTTYJN/oneapi.json"
-      schemaPath: join(__dirname, 'oneapi.json'),
-      mock: false,
-    },
-  ],
+  // plugins: ['@umijs/max-plugin-openapi'],
+  // openAPI: [
+  //   {
+  //     requestLibPath: "import { request } from '@umijs/max'",
+  //     // 或者使用在线的版本
+  //     // schemaPath: "https://gw.alipayobjects.com/os/antfincdn/M%24jrzTTYJN/oneapi.json"
+  //     schemaPath: join(__dirname, 'oneapi.json'),
+  //     mock: false,
+  //   },
+  // ],
 
   mock: {
     include: ['src/pages/**/_mock.ts'],
diff --git a/src/app.tsx b/src/app.tsx
index de16ba25..86ffed76 100644
--- a/src/app.tsx
+++ b/src/app.tsx
@@ -1,4 +1,3 @@
-import { LinkOutlined } from '@ant-design/icons';
 import type { Settings as LayoutSettings } from '@ant-design/pro-components';
 import { SettingDrawer } from '@ant-design/pro-components';
 import type { RequestConfig, RunTimeLayoutConfig } from '@umijs/max';
@@ -133,14 +132,15 @@ export const layout: RunTimeLayoutConfig = ({
         width: '331px',
       },
     ],
-    links: isDev
-      ? [
-          <Link key="openapi" to="/umi/plugin/openapi" target="_blank">
-            <LinkOutlined />
-            <span>OpenAPI 文档</span>
-          </Link>,
-        ]
-      : [],
+    // 启用 openapi 插件后可取消注释以下链接
+    // links: isDev
+    //   ? [
+    //       <Link key="openapi" to="/umi/plugin/openapi" target="_blank">
+    //         <LinkOutlined />
+    //         <span>OpenAPI 文档</span>
+    //       </Link>,
+    //     ]
+    //   : [],
     // Replace ProLayout's default ErrorBoundary with our offline-aware version,
     // so chunk load errors show friendly messages instead of "Something went wrong."
     ErrorBoundary,