diff --git a/content/docs/zh/apps/agent.mdx b/content/docs/zh/apps/agent.mdx
new file mode 100644
index 00000000..3b849e9a
--- /dev/null
+++ b/content/docs/zh/apps/agent.mdx
@@ -0,0 +1,34 @@
+---
+title: Agent 接入教程
+description: OpenClaw、HermesAgents、Claude、WorkBuddy、Cherry Studio、OpenCode、Codex++ 与 CC Switch 接入指南。
+---
+
+import { Card, Cards } from 'fumadocs-ui/components/card';
+import { Bot, Code2, Monitor, Settings, Terminal, Wrench } from 'lucide-react';
+
+## 统一参数
+
+| 配置项 | 填写内容 |
+| --- | --- |
+| API Base URL | `https://apihub.agnes-ai.com/v1` |
+| API Key | `YOUR_API_KEY` |
+| 推荐模型 | `agnes-2.0-flash` |
+| 协议 | OpenAI Chat Completions |
+
+<Callout type="warn" title="不要公开 API Key">
+  截图和示例统一使用 `YOUR_API_KEY`。请勿把真实密钥提交到代码仓库或发送到公开聊天中。
+</Callout>
+
+## 选择应用
+
+<Cards>
+  <Card icon={<Bot />} title="OpenClaw" description="自托管 Agent 自定义 Provider。" href="/zh/docs/apps/openclaw" />
+  <Card icon={<Terminal />} title="HermesAgents" description="使用 CLI 写入提供商配置。" href="/zh/docs/apps/hermes-agents" />
+  <Card icon={<Terminal />} title="Claude CLI" description="通过 CC Switch 完成模型映射。" href="/zh/docs/apps/claude-code" />
+  <Card icon={<Monitor />} title="Claude Desktop" description="桌面客户端兼容路由配置。" href="/zh/docs/apps/claude-desktop" />
+  <Card icon={<Bot />} title="WorkBuddy" description="添加 Custom 模型提供商。" href="/zh/docs/apps/workbuddy" />
+  <Card icon={<Settings />} title="Cherry Studio" description="添加 OpenAI 兼容模型服务。" href="/zh/docs/apps/cherry-studio" />
+  <Card icon={<Code2 />} title="OpenCode" description="CLI JSON 与 Desktop 配置。" href="/zh/docs/apps/opencode" />
+  <Card icon={<Code2 />} title="Codex++" description="添加 API Only Provider。" href="/zh/docs/apps/codex-plus-plus" />
+  <Card icon={<Wrench />} title="CC Switch" description="一键导入 Claude、Codex、Gemini。" href="/zh/docs/apps/cc-switch" />
+</Cards>
diff --git a/content/docs/zh/apps/cc-switch.mdx b/content/docs/zh/apps/cc-switch.mdx
index 448123fb..7a5ae44a 100644
--- a/content/docs/zh/apps/cc-switch.mdx
+++ b/content/docs/zh/apps/cc-switch.mdx
@@ -3,6 +3,28 @@ title: CC Switch - AI CLI 统一管理工具
 description: CC Switch 教程 — 跨平台 AI CLI 管理工具，统一管理 Claude Code、Codex、Gemini CLI 的 Provider 配置、MCP 服务器与系统提示词。对接 New API 一键填入。
 ---
 
+<AgentStepGuide
+  app="CC Switch"
+  steps={[
+    {
+      title: '从令牌页打开导入',
+      description: '先打开应用或配置入口。',
+      image: '/assets/agent-integrations/cc-switch-step-1.png',
+    },
+    {
+      title: '选择客户端与模型',
+      description: '按照页面字段填写统一接口参数。',
+      image: '/assets/agent-integrations/cc-switch-step-2.png',
+    },
+    {
+      title: '确认导入并启用',
+      description: '完成配置后发送测试消息确认模型响应。',
+      image: '/assets/agent-integrations/cc-switch-step-3.png',
+    }
+  ]}
+/>
+
+
 <Callout type="info" title="聊天设置选项">
   在 New API 控制台的系统设置->聊天设置中，可添加如下快捷选项，便于在令牌管理页一键填充到 CC Switch：
 </Callout>
diff --git a/content/docs/zh/apps/cherry-studio.mdx b/content/docs/zh/apps/cherry-studio.mdx
index e1ebf8f0..0bf7fc8d 100644
--- a/content/docs/zh/apps/cherry-studio.mdx
+++ b/content/docs/zh/apps/cherry-studio.mdx
@@ -3,6 +3,28 @@ title: Cherry Studio - 桌面 AI 客户端
 description: Cherry Studio 教程 — 将桌面 AI 客户端对接 New API，一键填入 API Key。内置 30+ 专业 AI 助手，覆盖多种工作场景。
 ---
 
+<AgentStepGuide
+  app="Cherry Studio"
+  steps={[
+    {
+      title: '进入模型服务',
+      description: '先打开应用或配置入口。',
+      image: '/assets/agent-integrations/cherry-studio-step-1.png',
+    },
+    {
+      title: '添加 OpenAI 兼容服务',
+      description: '按照页面字段填写统一接口参数。',
+      image: '/assets/agent-integrations/cherry-studio-step-2.png',
+    },
+    {
+      title: '测试并启用',
+      description: '完成配置后发送测试消息确认模型响应。',
+      image: '/assets/agent-integrations/cherry-studio-step-3.png',
+    }
+  ]}
+/>
+
+
 <Callout type="info" title="聊天设置选项">
   在 New API
   控制台的系统设置->聊天设置中，可添加如下快捷选项，便于在令牌管理页一键填充到
diff --git a/content/docs/zh/apps/claude-code.mdx b/content/docs/zh/apps/claude-code.mdx
index 9f2cd3fd..0ab3d3e4 100644
--- a/content/docs/zh/apps/claude-code.mdx
+++ b/content/docs/zh/apps/claude-code.mdx
@@ -3,6 +3,28 @@ title: Claude Code
 description: Claude Code 教程 — 将 Anthropic 的终端编程助手对接 New API。支持代码理解、多文件编辑，集成 VS Code 与 JetBrains IDE。
 ---
 
+<AgentStepGuide
+  app="Claude CLI"
+  steps={[
+    {
+      title: '选择 Claude 应用',
+      description: '先打开应用或配置入口。',
+      image: '/assets/agent-integrations/claude-cli-step-1.png',
+    },
+    {
+      title: '完成模型映射',
+      description: '按照页面字段填写统一接口参数。',
+      image: '/assets/agent-integrations/claude-cli-step-2.png',
+    },
+    {
+      title: '启用并重启',
+      description: '完成配置后发送测试消息确认模型响应。',
+      image: '/assets/agent-integrations/claude-cli-step-3.png',
+    }
+  ]}
+/>
+
+
 <Callout type="info" title="项目介绍">
   直接在你的终端中释放 Claude
   的强大能力。瞬间搜索百万行代码库。将耗时数小时的工作流程化为一条命令。你的工具，你的工作流，你的代码库，以思维速度进化。
diff --git a/content/docs/zh/apps/claude-desktop.mdx b/content/docs/zh/apps/claude-desktop.mdx
new file mode 100644
index 00000000..e47b2934
--- /dev/null
+++ b/content/docs/zh/apps/claude-desktop.mdx
@@ -0,0 +1,42 @@
+---
+title: Claude Desktop 接入指南
+description: 通过 CC Switch 或兼容路由工具为 Claude Desktop 添加自定义模型。
+---
+
+<AgentStepGuide
+  app="Claude Desktop"
+  steps={[
+    {
+      title: '选择桌面客户端',
+      description: '在路由管理工具中选择 Claude Desktop。',
+      image: '/assets/agent-integrations/claude-desktop-step-1.png',
+    },
+    {
+      title: '添加兼容提供商',
+      description: '填写 Base URL、API Key，并完成 Sonnet、Opus、Haiku 模型映射。',
+      image: '/assets/agent-integrations/claude-desktop-step-2.png',
+    },
+    {
+      title: '保存并重启',
+      description: '启用提供商并完全退出后重新打开 Claude Desktop。',
+      image: '/assets/agent-integrations/claude-desktop-step-3.png',
+    }
+  ]}
+/>
+
+## 统一接入参数
+
+| 配置项 | 填写内容 |
+| --- | --- |
+| API Base URL | `https://apihub.agnes-ai.com/v1` |
+| API Key | `YOUR_API_KEY` |
+| 模型 | `agnes-2.0-flash` |
+| 协议 | OpenAI Chat Completions |
+
+## 配置说明
+
+协议选择 `OpenAI Chat Completions`，三个 Claude 模型均可映射到 `agnes-2.0-flash`。
+
+## 验证与排查
+
+配置完成后发送一条测试消息。认证失败时重新复制 API Key；模型不存在时检查模型权限；连接失败时确认 Base URL 只填写到 `/v1`。
diff --git a/content/docs/zh/apps/codex-plus-plus.mdx b/content/docs/zh/apps/codex-plus-plus.mdx
new file mode 100644
index 00000000..4c20878e
--- /dev/null
+++ b/content/docs/zh/apps/codex-plus-plus.mdx
@@ -0,0 +1,42 @@
+---
+title: Codex++ 接入指南
+description: 在 Codex++ 管理工具中添加 API Only 提供商。
+---
+
+<AgentStepGuide
+  app="Codex++"
+  steps={[
+    {
+      title: '打开提供商管理',
+      description: '进入 Provider Configuration 并点击 Add Provider。',
+      image: '/assets/agent-integrations/codex-plus-plus-step-1.png',
+    },
+    {
+      title: '填写 API Only 配置',
+      description: '选择 Chat Completions，填写接口、密钥和测试模型。',
+      image: '/assets/agent-integrations/codex-plus-plus-step-2.png',
+    },
+    {
+      title: '启用并启动',
+      description: '切换到 Agnes 提供商，然后启动或重启 Codex++。',
+      image: '/assets/agent-integrations/codex-plus-plus-step-3.png',
+    }
+  ]}
+/>
+
+## 统一接入参数
+
+| 配置项 | 填写内容 |
+| --- | --- |
+| API Base URL | `https://apihub.agnes-ai.com/v1` |
+| API Key | `YOUR_API_KEY` |
+| 模型 | `agnes-2.0-flash` |
+| 协议 | OpenAI Chat Completions |
+
+## 配置说明
+
+Access Mode 选择 `API Only`，Upstream Protocol 选择 `Chat Completions`。
+
+## 验证与排查
+
+配置完成后发送一条测试消息。认证失败时重新复制 API Key；模型不存在时检查模型权限；连接失败时确认 Base URL 只填写到 `/v1`。
diff --git a/content/docs/zh/apps/hermes-agents.mdx b/content/docs/zh/apps/hermes-agents.mdx
new file mode 100644
index 00000000..01bc80ce
--- /dev/null
+++ b/content/docs/zh/apps/hermes-agents.mdx
@@ -0,0 +1,47 @@
+---
+title: HermesAgents 接入指南
+description: 通过 HermesAgents CLI 配置自定义 OpenAI 兼容模型。
+---
+
+<AgentStepGuide
+  app="HermesAgents"
+  steps={[
+    {
+      title: '选择自定义提供商',
+      description: '将 model.provider 设置为 custom。',
+      image: '/assets/agent-integrations/hermes-agents-step-1.png',
+    },
+    {
+      title: '写入接口与密钥',
+      description: '配置 Base URL 和 API Key，不要重复添加 Bearer。',
+      image: '/assets/agent-integrations/hermes-agents-step-2.png',
+    },
+    {
+      title: '设置默认模型',
+      description: '将默认模型设为 agnes-2.0-flash，然后启动任务验证。',
+      image: '/assets/agent-integrations/hermes-agents-step-3.png',
+    }
+  ]}
+/>
+
+## 统一接入参数
+
+| 配置项 | 填写内容 |
+| --- | --- |
+| API Base URL | `https://apihub.agnes-ai.com/v1` |
+| API Key | `YOUR_API_KEY` |
+| 模型 | `agnes-2.0-flash` |
+| 协议 | OpenAI Chat Completions |
+
+## 配置说明
+
+```bash
+hermes config set model.provider custom
+hermes config set model.base_url https://apihub.agnes-ai.com/v1
+hermes config set model.api_key YOUR_API_KEY
+hermes config set model.default agnes-2.0-flash
+```
+
+## 验证与排查
+
+配置完成后发送一条测试消息。认证失败时重新复制 API Key；模型不存在时检查模型权限；连接失败时确认 Base URL 只填写到 `/v1`。
diff --git a/content/docs/zh/apps/index.mdx b/content/docs/zh/apps/index.mdx
index d8adacd5..051cf0fd 100644
--- a/content/docs/zh/apps/index.mdx
+++ b/content/docs/zh/apps/index.mdx
@@ -22,6 +22,12 @@ New API 兼容多种流行的 AI 应用和工具。以下是已验证支持的
 ## 支持的应用
 
 <Cards>
+  <Card
+    icon={<Bot />}
+    title="Agent 接入教程"
+    description="OpenClaw、Claude、WorkBuddy、OpenCode、Codex++、CC Switch 等 9 个项目的配置步骤。"
+    href="/zh/docs/apps/agent"
+  />
   <Card
     icon={<Sparkles />}
     title="AionUi"
diff --git a/content/docs/zh/apps/meta.json b/content/docs/zh/apps/meta.json
index d35ac0b5..102fc853 100644
--- a/content/docs/zh/apps/meta.json
+++ b/content/docs/zh/apps/meta.json
@@ -5,6 +5,7 @@
   "root": true,
   "pages": [
     "index",
+    "agent",
     "aionui",
     "cc-switch",
     "cherry-studio",
diff --git a/content/docs/zh/apps/openclaw.mdx b/content/docs/zh/apps/openclaw.mdx
index 765ab280..e33a843c 100644
--- a/content/docs/zh/apps/openclaw.mdx
+++ b/content/docs/zh/apps/openclaw.mdx
@@ -3,6 +3,28 @@ title: OpenClaw - 自托管 AI 智能助手平台
 description: OpenClaw 教程 — 安装 OpenClaw、对接 New API，快速搭建自托管 AI 助手。开源项目，支持 Telegram、Discord、WhatsApp 等多渠道集成。
 ---
 
+<AgentStepGuide
+  app="OpenClaw"
+  steps={[
+    {
+      title: '打开配置向导',
+      description: '先打开应用或配置入口。',
+      image: '/assets/agent-integrations/openclaw-step-1.png',
+    },
+    {
+      title: '填写 Custom Provider',
+      description: '按照页面字段填写统一接口参数。',
+      image: '/assets/agent-integrations/openclaw-step-2.png',
+    },
+    {
+      title: '保存并验证',
+      description: '完成配置后发送测试消息确认模型响应。',
+      image: '/assets/agent-integrations/openclaw-step-3.png',
+    }
+  ]}
+/>
+
+
 <Callout type="info" title="项目介绍">
   OpenClaw 是一个开源、自托管的个人 AI
   助手平台，将消息应用连接到运行在你自己硬件上的 AI
diff --git a/content/docs/zh/apps/opencode.mdx b/content/docs/zh/apps/opencode.mdx
new file mode 100644
index 00000000..1431f9fb
--- /dev/null
+++ b/content/docs/zh/apps/opencode.mdx
@@ -0,0 +1,63 @@
+---
+title: OpenCode 接入指南
+description: 通过 @ai-sdk/openai-compatible 将 OpenCode CLI 或 Desktop 接入自定义接口。
+---
+
+<AgentStepGuide
+  app="OpenCode"
+  steps={[
+    {
+      title: '添加 Provider',
+      description: '在配置文件的 provider 中新增 agnes。',
+      image: '/assets/agent-integrations/opencode-step-1.png',
+    },
+    {
+      title: '设置环境变量',
+      description: '通过 AGNES_API_KEY 保存密钥，避免写入代码仓库。',
+      image: '/assets/agent-integrations/opencode-step-2.png',
+    },
+    {
+      title: '选择模型验证',
+      description: '启动 OpenCode，使用 /models 选择 agnes-2.0-flash。',
+      image: '/assets/agent-integrations/opencode-step-3.png',
+    }
+  ]}
+/>
+
+## 统一接入参数
+
+| 配置项 | 填写内容 |
+| --- | --- |
+| API Base URL | `https://apihub.agnes-ai.com/v1` |
+| API Key | `YOUR_API_KEY` |
+| 模型 | `agnes-2.0-flash` |
+| 协议 | OpenAI Chat Completions |
+
+## 配置说明
+
+```json
+{
+  "model": "agnes/agnes-2.0-flash",
+  "provider": {
+    "agnes": {
+      "npm": "@ai-sdk/openai-compatible",
+      "name": "Agnes",
+      "options": {
+        "baseURL": "https://apihub.agnes-ai.com/v1",
+        "apiKey": "{env:AGNES_API_KEY}"
+      },
+      "models": {
+        "agnes-2.0-flash": { "name": "Agnes 2.0 Flash" }
+      }
+    }
+  }
+}
+```
+
+```bash
+export AGNES_API_KEY="YOUR_API_KEY"
+```
+
+## 验证与排查
+
+配置完成后发送一条测试消息。认证失败时重新复制 API Key；模型不存在时检查模型权限；连接失败时确认 Base URL 只填写到 `/v1`。
diff --git a/content/docs/zh/apps/workbuddy.mdx b/content/docs/zh/apps/workbuddy.mdx
new file mode 100644
index 00000000..b42c690b
--- /dev/null
+++ b/content/docs/zh/apps/workbuddy.mdx
@@ -0,0 +1,42 @@
+---
+title: WorkBuddy 接入指南
+description: 在 WorkBuddy 中添加自定义 OpenAI 兼容提供商。
+---
+
+<AgentStepGuide
+  app="WorkBuddy"
+  steps={[
+    {
+      title: '进入模型设置',
+      description: '打开 WorkBuddy 的模型或提供商管理页面。',
+      image: '/assets/agent-integrations/workbuddy-step-1.png',
+    },
+    {
+      title: '添加 Custom 提供商',
+      description: '选择 Other 或 Custom，并填写统一接口参数。',
+      image: '/assets/agent-integrations/workbuddy-step-2.png',
+    },
+    {
+      title: '设为当前模型',
+      description: '选择 agnes-2.0-flash，创建会话验证响应。',
+      image: '/assets/agent-integrations/workbuddy-step-3.png',
+    }
+  ]}
+/>
+
+## 统一接入参数
+
+| 配置项 | 填写内容 |
+| --- | --- |
+| API Base URL | `https://apihub.agnes-ai.com/v1` |
+| API Key | `YOUR_API_KEY` |
+| 模型 | `agnes-2.0-flash` |
+| 协议 | OpenAI Chat Completions |
+
+## 配置说明
+
+不同版本的入口名称可能显示为 `Other`、`Custom` 或“自定义提供商”。
+
+## 验证与排查
+
+配置完成后发送一条测试消息。认证失败时重新复制 API Key；模型不存在时检查模型权限；连接失败时确认 Base URL 只填写到 `/v1`。
diff --git a/public/assets/agent-integrations/cc-switch-step-1.png b/public/assets/agent-integrations/cc-switch-step-1.png
new file mode 100644
index 00000000..0e9f0fb6
Binary files /dev/null and b/public/assets/agent-integrations/cc-switch-step-1.png differ
diff --git a/public/assets/agent-integrations/cc-switch-step-2.png b/public/assets/agent-integrations/cc-switch-step-2.png
new file mode 100644
index 00000000..089f6941
Binary files /dev/null and b/public/assets/agent-integrations/cc-switch-step-2.png differ
diff --git a/public/assets/agent-integrations/cc-switch-step-3.png b/public/assets/agent-integrations/cc-switch-step-3.png
new file mode 100644
index 00000000..8fc58727
Binary files /dev/null and b/public/assets/agent-integrations/cc-switch-step-3.png differ
diff --git a/public/assets/agent-integrations/cherry-studio-step-1.png b/public/assets/agent-integrations/cherry-studio-step-1.png
new file mode 100644
index 00000000..7f58173e
Binary files /dev/null and b/public/assets/agent-integrations/cherry-studio-step-1.png differ
diff --git a/public/assets/agent-integrations/cherry-studio-step-2.png b/public/assets/agent-integrations/cherry-studio-step-2.png
new file mode 100644
index 00000000..58a2679f
Binary files /dev/null and b/public/assets/agent-integrations/cherry-studio-step-2.png differ
diff --git a/public/assets/agent-integrations/cherry-studio-step-3.png b/public/assets/agent-integrations/cherry-studio-step-3.png
new file mode 100644
index 00000000..8fb626c3
Binary files /dev/null and b/public/assets/agent-integrations/cherry-studio-step-3.png differ
diff --git a/public/assets/agent-integrations/claude-cli-step-1.png b/public/assets/agent-integrations/claude-cli-step-1.png
new file mode 100644
index 00000000..321762cd
Binary files /dev/null and b/public/assets/agent-integrations/claude-cli-step-1.png differ
diff --git a/public/assets/agent-integrations/claude-cli-step-2.png b/public/assets/agent-integrations/claude-cli-step-2.png
new file mode 100644
index 00000000..2b3230ec
Binary files /dev/null and b/public/assets/agent-integrations/claude-cli-step-2.png differ
diff --git a/public/assets/agent-integrations/claude-cli-step-3.png b/public/assets/agent-integrations/claude-cli-step-3.png
new file mode 100644
index 00000000..970b0993
Binary files /dev/null and b/public/assets/agent-integrations/claude-cli-step-3.png differ
diff --git a/public/assets/agent-integrations/claude-desktop-step-1.png b/public/assets/agent-integrations/claude-desktop-step-1.png
new file mode 100644
index 00000000..905ace61
Binary files /dev/null and b/public/assets/agent-integrations/claude-desktop-step-1.png differ
diff --git a/public/assets/agent-integrations/claude-desktop-step-2.png b/public/assets/agent-integrations/claude-desktop-step-2.png
new file mode 100644
index 00000000..fb3226e0
Binary files /dev/null and b/public/assets/agent-integrations/claude-desktop-step-2.png differ
diff --git a/public/assets/agent-integrations/claude-desktop-step-3.png b/public/assets/agent-integrations/claude-desktop-step-3.png
new file mode 100644
index 00000000..41419113
Binary files /dev/null and b/public/assets/agent-integrations/claude-desktop-step-3.png differ
diff --git a/public/assets/agent-integrations/codex-plus-plus-step-1.png b/public/assets/agent-integrations/codex-plus-plus-step-1.png
new file mode 100644
index 00000000..6296c7c5
Binary files /dev/null and b/public/assets/agent-integrations/codex-plus-plus-step-1.png differ
diff --git a/public/assets/agent-integrations/codex-plus-plus-step-2.png b/public/assets/agent-integrations/codex-plus-plus-step-2.png
new file mode 100644
index 00000000..84ac7e75
Binary files /dev/null and b/public/assets/agent-integrations/codex-plus-plus-step-2.png differ
diff --git a/public/assets/agent-integrations/codex-plus-plus-step-3.png b/public/assets/agent-integrations/codex-plus-plus-step-3.png
new file mode 100644
index 00000000..8ed7ea06
Binary files /dev/null and b/public/assets/agent-integrations/codex-plus-plus-step-3.png differ
diff --git a/public/assets/agent-integrations/hermes-agents-step-1.png b/public/assets/agent-integrations/hermes-agents-step-1.png
new file mode 100644
index 00000000..a787bb98
Binary files /dev/null and b/public/assets/agent-integrations/hermes-agents-step-1.png differ
diff --git a/public/assets/agent-integrations/hermes-agents-step-2.png b/public/assets/agent-integrations/hermes-agents-step-2.png
new file mode 100644
index 00000000..71c49131
Binary files /dev/null and b/public/assets/agent-integrations/hermes-agents-step-2.png differ
diff --git a/public/assets/agent-integrations/hermes-agents-step-3.png b/public/assets/agent-integrations/hermes-agents-step-3.png
new file mode 100644
index 00000000..5703536f
Binary files /dev/null and b/public/assets/agent-integrations/hermes-agents-step-3.png differ
diff --git a/public/assets/agent-integrations/openclaw-step-1.png b/public/assets/agent-integrations/openclaw-step-1.png
new file mode 100644
index 00000000..d1f2bd4e
Binary files /dev/null and b/public/assets/agent-integrations/openclaw-step-1.png differ
diff --git a/public/assets/agent-integrations/openclaw-step-2.png b/public/assets/agent-integrations/openclaw-step-2.png
new file mode 100644
index 00000000..c77b7520
Binary files /dev/null and b/public/assets/agent-integrations/openclaw-step-2.png differ
diff --git a/public/assets/agent-integrations/openclaw-step-3.png b/public/assets/agent-integrations/openclaw-step-3.png
new file mode 100644
index 00000000..bf85c9ad
Binary files /dev/null and b/public/assets/agent-integrations/openclaw-step-3.png differ
diff --git a/public/assets/agent-integrations/opencode-step-1.png b/public/assets/agent-integrations/opencode-step-1.png
new file mode 100644
index 00000000..edec414f
Binary files /dev/null and b/public/assets/agent-integrations/opencode-step-1.png differ
diff --git a/public/assets/agent-integrations/opencode-step-2.png b/public/assets/agent-integrations/opencode-step-2.png
new file mode 100644
index 00000000..49c98dc4
Binary files /dev/null and b/public/assets/agent-integrations/opencode-step-2.png differ
diff --git a/public/assets/agent-integrations/opencode-step-3.png b/public/assets/agent-integrations/opencode-step-3.png
new file mode 100644
index 00000000..15f37902
Binary files /dev/null and b/public/assets/agent-integrations/opencode-step-3.png differ
diff --git a/public/assets/agent-integrations/workbuddy-step-1.png b/public/assets/agent-integrations/workbuddy-step-1.png
new file mode 100644
index 00000000..77ba2a6c
Binary files /dev/null and b/public/assets/agent-integrations/workbuddy-step-1.png differ
diff --git a/public/assets/agent-integrations/workbuddy-step-2.png b/public/assets/agent-integrations/workbuddy-step-2.png
new file mode 100644
index 00000000..004a1072
Binary files /dev/null and b/public/assets/agent-integrations/workbuddy-step-2.png differ
diff --git a/public/assets/agent-integrations/workbuddy-step-3.png b/public/assets/agent-integrations/workbuddy-step-3.png
new file mode 100644
index 00000000..3abcc51b
Binary files /dev/null and b/public/assets/agent-integrations/workbuddy-step-3.png differ
diff --git a/src/components/agent-step-guide.tsx b/src/components/agent-step-guide.tsx
new file mode 100644
index 00000000..04b38c08
--- /dev/null
+++ b/src/components/agent-step-guide.tsx
@@ -0,0 +1,74 @@
+'use client';
+
+import Image from 'next/image';
+import { useEffect, useRef, useState } from 'react';
+
+export type AgentGuideStep = {
+  title: string;
+  description: string;
+  image: string;
+};
+
+type AgentStepGuideProps = {
+  app: string;
+  steps: AgentGuideStep[];
+};
+
+export function AgentStepGuide({ app, steps }: AgentStepGuideProps) {
+  const containerRef = useRef<HTMLDivElement>(null);
+  const [visible, setVisible] = useState(false);
+
+  useEffect(() => {
+    const element = containerRef.current;
+    if (!element) return;
+
+    const observer = new IntersectionObserver(
+      ([entry]) => {
+        if (!entry.isIntersecting) return;
+        setVisible(true);
+        observer.disconnect();
+      },
+      { rootMargin: '0px 0px -10% 0px', threshold: 0.12 }
+    );
+
+    observer.observe(element);
+    return () => observer.disconnect();
+  }, []);
+
+  return (
+    <div ref={containerRef} className="not-prose my-8 grid gap-5">
+      {steps.map((step, index) => (
+        <section
+          key={step.title}
+          className={`border-fd-border bg-fd-card grid overflow-hidden rounded-2xl border shadow-sm transition-all duration-700 motion-reduce:translate-y-0 motion-reduce:opacity-100 motion-reduce:transition-none lg:grid-cols-[minmax(0,0.8fr)_minmax(28rem,1.2fr)] ${
+            visible ? 'translate-y-0 opacity-100' : 'translate-y-8 opacity-0'
+          }`}
+          style={{ transitionDelay: `${index * 120}ms` }}
+        >
+          <div className="flex gap-4 p-6 lg:items-center">
+            <span className="flex size-12 shrink-0 items-center justify-center rounded-xl bg-gradient-to-br from-pink-500 to-violet-500 text-sm font-bold tracking-wider text-white shadow-lg shadow-pink-500/20">
+              {String(index + 1).padStart(2, '0')}
+            </span>
+            <div>
+              <h3 className="text-fd-foreground m-0 text-lg font-semibold">
+                {step.title}
+              </h3>
+              <p className="text-fd-muted-foreground mt-2 mb-0 text-sm leading-6">
+                {step.description}
+              </p>
+            </div>
+          </div>
+          <div className="border-fd-border relative min-h-56 overflow-hidden border-t bg-slate-100 lg:border-t-0 lg:border-l dark:bg-slate-950">
+            <Image
+              src={step.image}
+              alt={`${app} 第 ${index + 1} 步配置截图`}
+              width={1200}
+              height={620}
+              className="h-full w-full object-cover transition-transform duration-500 hover:scale-[1.015] motion-reduce:transform-none"
+            />
+          </div>
+        </section>
+      ))}
+    </div>
+  );
+}
diff --git a/src/mdx-components.tsx b/src/mdx-components.tsx
index e6057b86..922b9a49 100644
--- a/src/mdx-components.tsx
+++ b/src/mdx-components.tsx
@@ -3,12 +3,14 @@ import type { MDXComponents } from 'mdx/types';
 import { QQGroupQuiz } from '@/components/qq-group-quiz';
 import { APIPage } from '@/components/api-page';
 import { ImageZoom } from 'fumadocs-ui/components/image-zoom';
+import { AgentStepGuide } from '@/components/agent-step-guide';
 
 export function getMDXComponents(components?: MDXComponents): MDXComponents {
   return {
     ...(defaultMdxComponents as MDXComponents),
     img: (props) => <ImageZoom {...(props as any)} />,
     QQGroupQuiz,
+    AgentStepGuide,
     // APIPage is an async server component, need type assertion to bypass MDX type check
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
     APIPage: APIPage as any,