@jeik/dingtalk-connector 0.8.21-fix1

package/dist/session-DJ4jYqPv.mjs

@@ -0,0 +1,114 @@
+//#region src/utils/constants.ts
+/**
+* 常量定义模块
+*/
+/** 新会话触发命令 */
+const NEW_SESSION_COMMANDS = [
+	"/new",
+	"/reset",
+	"/clear",
+	"新会话",
+	"重新开始",
+	"清空对话"
+];
+/**
+* 媒体类消息类型集合。
+*
+* 这些消息类型需要通过钉钉原生消息 API 发送，不支持 AI Card 形式，
+* 在 sendProactiveInternal 中会强制跳过 AI Card 路径。
+*/
+const MEDIA_MSG_TYPES = new Set([
+	"image",
+	"voice",
+	"file",
+	"video"
+]);
+/**
+* 队列繁忙时的即时 ACK 回复短语。
+*
+* 当消息入队时检测到上一条消息仍在处理中，立即从此列表中随机选取一条回复，
+* 告知用户消息已收到并排队，避免用户以为 Bot 没有响应。
+* 参考 delivery.rs 中 DINGTALK_ACK_PHRASES_BUSY_ZH_CN 的设计。
+*/
+const QUEUE_BUSY_ACK_PHRASES = [
+	"上一条还没结束，这条我已经记下，稍后按顺序继续处理。",
+	"当前还在忙，你的新消息已经排队，上一条完成后我马上继续。",
+	"我这边还在处理上一条，这条已加入队列，完成后继续处理。"
+];
+//#endregion
+//#region src/utils/session.ts
+/**
+* 会话管理模块
+* 构建 OpenClaw 标准会话上下文
+*/
+/**
+* 构建 OpenClaw 标准会话上下文
+* 遵循 OpenClaw session.dmScope 机制，让 Gateway 根据配置自动处理会话隔离
+* 
+* @param sharedMemoryAcrossConversations - 是否在不同会话间共享记忆（默认 false）
+*   - true: 所有会话共享记忆，使用 accountId 作为记忆标识
+*   - false: 不同会话独立记忆，使用完整的 sessionContext 作为记忆标识
+*/
+function buildSessionContext(params) {
+	const { accountId, senderId, senderName, conversationType, conversationId, groupSubject, separateSessionByConversation, groupSessionScope, sharedMemoryAcrossConversations } = params;
+	const isDirect = conversationType === "1";
+	const peerId = isDirect ? senderId : conversationId || senderId;
+	if (sharedMemoryAcrossConversations === true) return {
+		channel: "dingtalk-connector",
+		accountId,
+		chatType: isDirect ? "direct" : "group",
+		peerId,
+		sessionPeerId: accountId,
+		conversationId: isDirect ? void 0 : conversationId,
+		senderName,
+		groupSubject: isDirect ? void 0 : groupSubject
+	};
+	if (separateSessionByConversation === false) return {
+		channel: "dingtalk-connector",
+		accountId,
+		chatType: isDirect ? "direct" : "group",
+		peerId,
+		sessionPeerId: senderId,
+		conversationId: isDirect ? void 0 : conversationId,
+		senderName,
+		groupSubject: isDirect ? void 0 : groupSubject
+	};
+	if (isDirect) return {
+		channel: "dingtalk-connector",
+		accountId,
+		chatType: "direct",
+		peerId,
+		sessionPeerId: senderId,
+		senderName
+	};
+	if (groupSessionScope === "group_sender") return {
+		channel: "dingtalk-connector",
+		accountId,
+		chatType: "group",
+		peerId,
+		sessionPeerId: `${conversationId}:${senderId}`,
+		conversationId,
+		senderName,
+		groupSubject
+	};
+	return {
+		channel: "dingtalk-connector",
+		accountId,
+		chatType: "group",
+		peerId,
+		sessionPeerId: conversationId || senderId,
+		conversationId,
+		senderName,
+		groupSubject
+	};
+}
+/**
+* 检查消息是否是新会话命令
+*/
+function normalizeSlashCommand(text) {
+	const lower = text.trim().toLowerCase();
+	if (NEW_SESSION_COMMANDS.some((cmd) => lower === cmd.toLowerCase())) return "/new";
+	return text;
+}
+//#endregion
+export { QUEUE_BUSY_ACK_PHRASES as a, NEW_SESSION_COMMANDS as i, normalizeSlashCommand as n, MEDIA_MSG_TYPES as r, buildSessionContext as t };

package/dist/utils-Bjh4r_qS.mjs

@@ -0,0 +1,4 @@
+import "./logger-mZ9OSbmD.mjs";
+import { r as getAccessToken, t as DINGTALK_API } from "./utils-CIfI_3Jh.mjs";
+import "./session-DJ4jYqPv.mjs";
+export { DINGTALK_API, getAccessToken };

package/dist/utils-CIfI_3Jh.mjs

@@ -0,0 +1,63 @@
+import { n as dingtalkOapiHttp, t as dingtalkHttp } from "./http-client-DFWZgO1n.mjs";
+//#region src/utils/token.ts
+const DINGTALK_API = "https://api.dingtalk.com";
+const DINGTALK_OAPI = "https://oapi.dingtalk.com";
+/**
+* 按 clientId 分桶缓存，避免多账号串 token。
+*/
+const apiTokenCache = /* @__PURE__ */ new Map();
+const oapiTokenCache = /* @__PURE__ */ new Map();
+function cacheKey(config) {
+	const clientId = String(config?.clientId ?? "").trim();
+	if (!clientId) throw new Error("Invalid DingtalkConfig: clientId is required for token caching. Please ensure your configuration includes a valid clientId.");
+	return clientId;
+}
+/**
+* 获取钉钉 Access Token（新版 API）
+*/
+async function getAccessToken(config) {
+	const now = Date.now();
+	const key = cacheKey(config);
+	const cached = apiTokenCache.get(key);
+	if (cached && cached.expiryMs > now + 6e4) return cached.token;
+	const response = await dingtalkHttp.post(`${DINGTALK_API}/v1.0/oauth2/accessToken`, {
+		appKey: config.clientId,
+		appSecret: config.clientSecret
+	});
+	const token = response.data.accessToken;
+	const expireInSec = Number(response.data.expireIn ?? 0);
+	apiTokenCache.set(key, {
+		token,
+		expiryMs: now + expireInSec * 1e3
+	});
+	return token;
+}
+/**
+* 获取钉钉 OAPI Access Token（旧版 API，用于媒体上传等）
+*/
+async function getOapiAccessToken(config) {
+	try {
+		const now = Date.now();
+		const key = cacheKey(config);
+		const cached = oapiTokenCache.get(key);
+		if (cached && cached.expiryMs > now + 6e4) return cached.token;
+		const resp = await dingtalkOapiHttp.get(`${DINGTALK_OAPI}/gettoken`, { params: {
+			appkey: config.clientId,
+			appsecret: config.clientSecret
+		} });
+		if (resp.data?.errcode === 0 && resp.data?.access_token) {
+			const token = String(resp.data.access_token);
+			const expiresInSec = Number(resp.data.expires_in ?? 7200);
+			oapiTokenCache.set(key, {
+				token,
+				expiryMs: now + expiresInSec * 1e3
+			});
+			return token;
+		}
+		return null;
+	} catch {
+		return null;
+	}
+}
+//#endregion
+export { getOapiAccessToken as i, DINGTALK_OAPI as n, getAccessToken as r, DINGTALK_API as t };

package/dist/utils-legacy-CALCPP1t.mjs

@@ -0,0 +1,230 @@
+//#region src/utils/utils-legacy.ts
+/** 钉钉 API 常量 */
+const DINGTALK_API = "https://api.dingtalk.com";
+const DINGTALK_OAPI = "https://oapi.dingtalk.com";
+const apiTokenCache = /* @__PURE__ */ new Map();
+const oapiTokenCache = /* @__PURE__ */ new Map();
+function cacheKey(config) {
+	const clientId = String(config?.clientId ?? "").trim();
+	if (!clientId) throw new Error("Invalid DingtalkConfig: clientId is required for token caching. Please ensure your configuration includes a valid clientId.");
+	return clientId;
+}
+/**
+* 获取钉钉 Access Token（新版 API）
+*/
+async function getAccessToken(config) {
+	const now = Date.now();
+	const key = cacheKey(config);
+	const cached = apiTokenCache.get(key);
+	if (cached && cached.expiryMs > now + 6e4) return cached.token;
+	const { dingtalkHttp } = await import("./http-client-CpnJHB89.mjs");
+	const response = await dingtalkHttp.post(`${DINGTALK_API}/v1.0/oauth2/accessToken`, {
+		appKey: config.clientId,
+		appSecret: config.clientSecret
+	});
+	const token = response.data.accessToken;
+	const expireInSec = Number(response.data.expireIn ?? 0);
+	apiTokenCache.set(key, {
+		token,
+		expiryMs: now + expireInSec * 1e3
+	});
+	return token;
+}
+/**
+* 获取钉钉 OAPI Access Token（旧版 API，用于媒体上传等）
+*/
+async function getOapiAccessToken(config) {
+	try {
+		const now = Date.now();
+		const key = cacheKey(config);
+		const cached = oapiTokenCache.get(key);
+		if (cached && cached.expiryMs > now + 6e4) return cached.token;
+		const { dingtalkOapiHttp } = await import("./http-client-CpnJHB89.mjs");
+		const resp = await dingtalkOapiHttp.get(`${DINGTALK_OAPI}/gettoken`, { params: {
+			appkey: config.clientId,
+			appsecret: config.clientSecret
+		} });
+		if (resp.data?.errcode === 0 && resp.data?.access_token) {
+			const token = String(resp.data.access_token);
+			const expiresInSec = Number(resp.data.expires_in ?? 7200);
+			oapiTokenCache.set(key, {
+				token,
+				expiryMs: now + expiresInSec * 1e3
+			});
+			return token;
+		}
+		return null;
+	} catch {
+		return null;
+	}
+}
+/** staffId → unionId 缓存（带过期时间的 LRU 缓存） */
+const MAX_UNION_ID_CACHE_SIZE = 1e3;
+const UNION_ID_CACHE_TTL = 1440 * 60 * 1e3;
+const unionIdCache = /* @__PURE__ */ new Map();
+/**
+* 通过 oapi 旧版接口将 staffId 转换为 unionId
+*/
+async function getUnionId(staffId, config, log) {
+	const cached = unionIdCache.get(staffId);
+	if (cached && Date.now() - cached.timestamp < UNION_ID_CACHE_TTL) return cached.unionId;
+	try {
+		const token = await getOapiAccessToken(config);
+		if (!token) {
+			log?.error?.("[DingTalk] getUnionId: 无法获取 oapi access_token");
+			return null;
+		}
+		const { dingtalkOapiHttp } = await import("./http-client-CpnJHB89.mjs");
+		const resp = await dingtalkOapiHttp.get(`${DINGTALK_OAPI}/user/get`, {
+			params: {
+				access_token: token,
+				userid: staffId
+			},
+			timeout: 1e4
+		});
+		const unionId = resp.data?.unionid;
+		if (unionId) {
+			if (unionIdCache.size >= MAX_UNION_ID_CACHE_SIZE) {
+				let oldestKey = null;
+				let oldestTime = Date.now();
+				for (const [key, entry] of unionIdCache.entries()) if (entry.timestamp < oldestTime) {
+					oldestTime = entry.timestamp;
+					oldestKey = key;
+				}
+				if (oldestKey) unionIdCache.delete(oldestKey);
+			}
+			unionIdCache.set(staffId, {
+				unionId,
+				timestamp: Date.now()
+			});
+			log?.info?.(`[DingTalk] getUnionId: ${staffId} → ${unionId}`);
+			return unionId;
+		}
+		log?.error?.(`[DingTalk] getUnionId: 响应中无 unionid 字段: ${JSON.stringify(resp.data)}`);
+		return null;
+	} catch (err) {
+		log?.error?.(`[DingTalk] getUnionId 失败: ${err.message}`);
+		return null;
+	}
+}
+/** 消息去重缓存 Map<messageId, timestamp> - 防止同一消息被重复处理 */
+const processedMessages = /* @__PURE__ */ new Map();
+/** 消息去重缓存过期时间（5分钟） */
+const MESSAGE_DEDUP_TTL = 300 * 1e3;
+/**
+* 清理过期的消息去重缓存
+*/
+function cleanupProcessedMessages() {
+	const now = Date.now();
+	for (const [msgId, timestamp] of processedMessages.entries()) if (now - timestamp > MESSAGE_DEDUP_TTL) processedMessages.delete(msgId);
+}
+/**
+* 检查消息是否已处理过（去重）
+*/
+function isMessageProcessed(messageId) {
+	if (!messageId) return false;
+	return processedMessages.has(messageId);
+}
+/**
+* 标记消息为已处理
+*/
+function markMessageProcessed(messageId) {
+	if (!messageId) return;
+	processedMessages.set(messageId, Date.now());
+	if (processedMessages.size >= 100) cleanupProcessedMessages();
+}
+/**
+* 对钉钉 Stream 消息做双层去重检查，并在首次处理时标记。
+*
+* 背景：钉钉 Stream 模式存在两套消息 ID：
+*   - headers.messageId：WebSocket 协议层的投递 ID，每次重发都会生成新值
+*   - data.msgId：业务层的用户消息 ID，重发时保持不变
+*
+* 因此必须同时检查两个 ID，才能可靠地拦截钉钉服务端的重发消息：
+*   1. 协议层去重（headers.messageId）：拦截同一次投递的重复回调
+*   2. 业务层去重（data.msgId）：拦截 ~60 秒后服务端因未收到业务回复而触发的重发
+*
+* 重要：key 必须带 accountId 前缀，避免多账号（多机器人）场景下，
+* 同一条群消息 @多个机器人时，不同机器人收到相同 msgId 导致误判为重复消息。
+*
+* @param accountId         - 当前账号 ID（用于命名空间隔离，防止多账号误判）
+* @param protocolMessageId - res.headers.messageId（WebSocket 协议层投递 ID）
+* @param businessMsgId     - data.msgId（钉钉业务层消息 ID，来自 JSON.parse(res.data).msgId）
+* @returns true 表示消息已处理过（应跳过），false 表示首次处理（已标记为已处理）
+*/
+function checkAndMarkDingtalkMessage(accountId, protocolMessageId, businessMsgId) {
+	const scopedProtocolId = protocolMessageId ? `${accountId}:${protocolMessageId}` : void 0;
+	const scopedBusinessId = businessMsgId ? `${accountId}:${businessMsgId}` : void 0;
+	const isProtocolDuplicate = scopedProtocolId ? isMessageProcessed(scopedProtocolId) : false;
+	const isBusinessDuplicate = scopedBusinessId ? isMessageProcessed(scopedBusinessId) : false;
+	if (isProtocolDuplicate || isBusinessDuplicate) return true;
+	if (scopedProtocolId) markMessageProcessed(scopedProtocolId);
+	if (scopedBusinessId) markMessageProcessed(scopedBusinessId);
+	return false;
+}
+/**
+* 在用户消息上贴 🤔思考中 表情，表示正在处理
+*/
+async function addEmotionReply(config, data, log) {
+	if (!data.msgId || !data.conversationId) return;
+	try {
+		const token = await getAccessToken(config);
+		const { dingtalkHttp } = await import("./http-client-CpnJHB89.mjs");
+		await dingtalkHttp.post(`${DINGTALK_API}/v1.0/robot/emotion/reply`, {
+			robotCode: data.robotCode ?? config.clientId,
+			openMsgId: data.msgId,
+			openConversationId: data.conversationId,
+			emotionType: 2,
+			emotionName: "🤔思考中",
+			textEmotion: {
+				emotionId: "2659900",
+				emotionName: "🤔思考中",
+				text: "🤔思考中",
+				backgroundId: "im_bg_1"
+			}
+		}, {
+			headers: {
+				"x-acs-dingtalk-access-token": token,
+				"Content-Type": "application/json"
+			},
+			timeout: 5e3
+		});
+		log?.info?.(`[DingTalk][Emotion] 贴表情成功: msgId=${data.msgId}`);
+	} catch (err) {
+		log?.warn?.(`[DingTalk][Emotion] 贴表情失败（不影响主流程）: ${err.message}`);
+	}
+}
+/**
+* 撤回用户消息上的 🤔思考中 表情
+*/
+async function recallEmotionReply(config, data, log) {
+	if (!data.msgId || !data.conversationId) return;
+	try {
+		const token = await getAccessToken(config);
+		const { dingtalkHttp } = await import("./http-client-CpnJHB89.mjs");
+		await dingtalkHttp.post(`${DINGTALK_API}/v1.0/robot/emotion/recall`, {
+			robotCode: data.robotCode ?? config.clientId,
+			openMsgId: data.msgId,
+			openConversationId: data.conversationId,
+			emotionType: 2,
+			emotionName: "🤔思考中",
+			textEmotion: {
+				emotionId: "2659900",
+				emotionName: "🤔思考中",
+				text: "🤔思考中",
+				backgroundId: "im_bg_1"
+			}
+		}, {
+			headers: {
+				"x-acs-dingtalk-access-token": token,
+				"Content-Type": "application/json"
+			},
+			timeout: 5e3
+		});
+		log?.info?.(`[DingTalk][Emotion] 撤回表情成功: msgId=${data.msgId}`);
+	} catch (err) {
+		log?.warn?.(`[DingTalk][Emotion] 撤回表情失败（不影响主流程）: ${err.message}`);
+	}
+}
+//#endregion
+export { cleanupProcessedMessages as a, getUnionId as c, recallEmotionReply as d, checkAndMarkDingtalkMessage as i, isMessageProcessed as l, DINGTALK_OAPI as n, getAccessToken as o, addEmotionReply as r, getOapiAccessToken as s, DINGTALK_API as t, markMessageProcessed as u };

package/dist/utils-legacy-CFYDBM4r.mjs

@@ -0,0 +1,3 @@
+import "./session-DJ4jYqPv.mjs";
+import { o as getAccessToken } from "./utils-legacy-CALCPP1t.mjs";
+export { getAccessToken };

package/docs/DEAP_AGENT_GUIDE.en.md

@@ -0,0 +1,115 @@
+# DingTalk DEAP Agent Integration
+
+> [中文版](DEAP_AGENT_GUIDE.md)
+
+Connect DingTalk [DEAP](https://deap.dingtalk.com) Agent with [OpenClaw](https://openclaw.ai) Gateway to enable natural language-driven local device operations.
+
+## Key Features
+
+- ✅ **Natural Language Interaction** - Users type natural language commands in the DingTalk chat (e.g., "Find PDF files on my desktop"), and the Agent automatically parses and executes the corresponding operations
+- ✅ **NAT Traversal** - Designed for local devices without public IPs, establishing a stable communication tunnel between local and cloud environments via the Connector client
+- ✅ **Cross-Platform Support** - Provides native binaries for Windows, macOS, and Linux, ensuring smooth operation across all platforms
+
+## System Architecture
+
+This solution uses a layered architecture with three core components:
+
+1. **OpenClaw Gateway** - Deployed on the local device, provides a standardized HTTP interface for receiving and processing operation commands from the cloud, leveraging the OpenClaw engine to execute tasks
+2. **DingTalk OpenClaw Connector** - Runs locally, building a communication tunnel between local and cloud environments to solve the problem of local devices without public IPs
+3. **DingTalk DEAP MCP** - An extension module for the DEAP Agent, responsible for forwarding user natural language requests to the OpenClaw Gateway via the cloud tunnel
+
+```mermaid
+graph LR
+    subgraph "DingTalk App"
+        A["User chats with Agent"] --> B["DEAP Agent"]
+    end
+
+    subgraph "Local Environment"
+        D["DingTalk OpenClaw Connector"] --> C["OpenClaw Gateway"]
+        C --> E["PC Operation Execution"]
+    end
+
+    B -.-> D
+```
+
+## Implementation Guide
+
+### Step 1: Set Up the Local Environment
+
+Ensure the OpenClaw Gateway is installed and running on your local device. The default address is `127.0.0.1:18789`:
+
+```bash
+openclaw gateway start
+```
+
+#### Configure Gateway Parameters
+
+1. Visit the [Configuration Page](http://127.0.0.1:18789/config)
+2. In the **Overview**, set the Gateway Token and save it securely:
+   ![alt text](images/image-5.png)
+3. Switch to **Infrastructure** and enable the `OpenAI Chat Completions Endpoint`:
+   ![alt text](images/image-6.png)
+
+4. Click the `Save` button in the top-right corner to save your configuration
+
+### Step 2: Obtain Required Parameters
+
+#### Get corpId
+
+Log in to the [DingTalk Developer Platform](https://open-dev.dingtalk.com) to find your enterprise CorpId:
+
+<img width="864" height="450" alt="Get corpId from DingTalk Developer Platform" src="https://github.com/user-attachments/assets/18ec9830-2d43-489a-a73f-530972685225" />
+
+#### Get apiKey
+
+Log in to the [DingTalk DEAP Platform](https://deap.dingtalk.com), navigate to **Security & Permissions** → **API-Key Management** to create a new API Key:
+
+<img width="1222" height="545" alt="DingTalk DEAP Platform API-Key Management" src="https://github.com/user-attachments/assets/dfe29984-4432-49c1-8226-0f9b60fbb5bc" />
+
+### Step 3: Start the Connector Client
+
+1. Download the installer for your operating system from the [Releases](https://github.com/hoskii/dingtalk-openclaw-connector/releases/tag/v0.0.1) page
+2. Extract and run the Connector in the corresponding directory (macOS example):
+
+   ```bash
+   unzip connector-mac.zip
+   ./connector-darwin -deapCorpId YOUR_CORP_ID -deapApiKey YOUR_API_KEY
+   ```
+   ![alt text](images/image-7.png)
+
+### Step 4: Configure the DEAP Agent
+
+1. Log in to the [DingTalk DEAP Platform](https://deap.dingtalk.com) and create a new agent:
+
+   <img width="2444" height="1486" alt="Create New Agent" src="https://github.com/user-attachments/assets/0b7f0855-f991-4aeb-b6e6-7576346b4477" />
+
+2. In the skill management page, search for and integrate the OpenClaw skill:
+
+   <img width="3430" height="1732" alt="Add OpenClaw Skill" src="https://github.com/user-attachments/assets/d44f0038-f863-4c1f-afa7-b774d875e4ba" />
+
+3. Configure skill parameters:
+
+   | Parameter    | Source     | Description                                                                            |
+   | ------------ | ---------- | -------------------------------------------------------------------------------------- |
+   | apikey       | From Step 2 | DEAP Platform API Key                                                                  |
+   | apihost      | Default     | Typically `127.0.0.1:18789`. On Windows, you may need to use `localhost:18789` instead |
+   | gatewayToken | From Step 1 | Gateway authentication token                                                           |
+
+   <img width="3426" height="1752" alt="Configure OpenClaw Skill Parameters" src="https://github.com/user-attachments/assets/bc725789-382f-41b5-bbdb-ba8f29923d5c" />
+
+Note that OpenClaw is an MCP, so you also need to configure its trigger rules. The MCP will only be invoked when the rules are satisfied:
+<img width="1088" height="526" alt="image" src="https://github.com/user-attachments/assets/8b0b6f6d-70ff-4edc-b674-7a24126aadfa" />
+
+4. Publish the Agent:
+
+   <img width="3416" height="1762" alt="Publish Agent" src="https://github.com/user-attachments/assets/3f8c3fdb-5f2b-4a4b-8896-35202e713bf3" />
+
+### Step 5: Start Using
+
+1. Search for and find your Agent in the DingTalk App:
+
+   <img width="1260" height="436" alt="Search for Agent" src="https://github.com/user-attachments/assets/30feff80-1b28-4274-830b-7045aed14980" />
+
+2. Start your natural language conversation:
+
+   <img width="1896" height="1240" alt="Chat with Agent" src="https://github.com/user-attachments/assets/2a80aab8-3fbf-4d18-beea-770577cb1a40" />

package/docs/DEAP_AGENT_GUIDE.md

@@ -0,0 +1,115 @@
+# 钉钉 DEAP Agent 集成
+
+> [English Version](DEAP_AGENT_GUIDE.en.md)
+
+通过将钉钉 [DEAP](https://deap.dingtalk.com) Agent 与 [OpenClaw](https://openclaw.ai) Gateway 连接，实现自然语言驱动的本地设备操作能力。
+
+## 核心功能
+
+- ✅ **自然语言交互** - 用户在钉钉对话框中输入自然语言指令（如"帮我查找桌面上的 PDF 文件"），Agent 将自动解析并执行相应操作
+- ✅ **内网穿透机制** - 专为本地设备无公网 IP 场景设计，通过 Connector 客户端建立稳定的内外网通信隧道
+- ✅ **跨平台兼容** - 提供 Windows、macOS 和 Linux 系统的原生二进制执行文件，确保各平台下的顺畅运行
+
+## 系统架构
+
+该方案采用分层架构模式，包含三个核心组件：
+
+1. **OpenClaw Gateway** - 部署于本地设备，提供标准化 HTTP 接口，负责接收并处理来自云端的操作指令，调动 OpenClaw 引擎执行具体任务
+2. **DingTalk OpenClaw Connector** - 运行于本地环境，构建本地与云端的通信隧道，解决内网设备无公网 IP 的问题
+3. **DingTalk DEAP MCP** - 作为 DEAP Agent 的扩展能力模块，负责将用户自然语言请求经由云端隧道转发至 OpenClaw Gateway
+
+```mermaid
+graph LR
+    subgraph "钉钉 App"
+        A["用户与 Agent 对话"] --> B["DEAP Agent"]
+    end
+
+    subgraph "本地环境"
+        D["DingTalk OpenClaw Connector"] --> C["OpenClaw Gateway"]
+        C --> E["PC 操作执行"]
+    end
+
+    B -.-> D
+```
+
+## 实施指南
+
+### 第一步：部署本地环境
+
+确认本地设备已成功安装并启动 OpenClaw Gateway，默认监听地址为 `127.0.0.1:18789`：
+
+```bash
+openclaw gateway start
+```
+
+#### 配置 Gateway 参数
+
+1. 访问 [配置页面](http://127.0.0.1:18789/config)
+2. 在 **概览** 中设置 Gateway Token 并妥善保存：
+   ![alt text](images/image-5.png)
+3. 切换至 **基础设施**，启用 `OpenAI Chat Completions Endpoint` 功能：
+   ![alt text](images/image-6.png)
+
+4. 点击右上角 `Save` 按钮完成配置保存
+
+### 第二步：获取必要参数
+
+#### 获取 corpId
+
+登录 [钉钉开发者平台](https://open-dev.dingtalk.com) 查看企业 CorpId：
+
+<img width="864" height="450" alt="钉钉开发者平台获取 corpId" src="https://github.com/user-attachments/assets/18ec9830-2d43-489a-a73f-530972685225" />
+
+#### 获取 apiKey
+
+登录 [钉钉 DEAP 平台](https://deap.dingtalk.com)，在 **安全与权限** → **API-Key 管理** 页面创建新的 API Key：
+
+<img width="1222" height="545" alt="钉钉 DEAP 平台 API-Key 管理" src="https://github.com/user-attachments/assets/dfe29984-4432-49c1-8226-0f9b60fbb5bc" />
+
+### 第三步：启动 Connector 客户端
+
+1. 从 [Releases](https://github.com/hoskii/dingtalk-openclaw-connector/releases/tag/v0.0.1) 页面下载适配您操作系统的安装包
+2. 解压后在对应目录运行 Connector（以 macOS 为例）：
+
+   ```bash
+   unzip connector-mac.zip
+   ./connector-darwin -deapCorpId YOUR_CORP_ID -deapApiKey YOUR_API_KEY
+   ```
+   ![alt text](images/image-7.png)
+
+### 第四步：配置 DEAP Agent
+
+1. 登录 [钉钉 DEAP 平台](https://deap.dingtalk.com)，创建新的智能体：
+
+   <img width="2444" height="1486" alt="新建智能体界面" src="https://github.com/user-attachments/assets/0b7f0855-f991-4aeb-b6e6-7576346b4477" />
+
+2. 在技能管理页面，搜索并集成 OpenClaw 技能：
+
+   <img width="3430" height="1732" alt="添加 OpenClaw 技能" src="https://github.com/user-attachments/assets/d44f0038-f863-4c1f-afa7-b774d875e4ba" />
+
+3. 配置技能参数：
+
+   | 参数         | 来源       | 说明                                                                                   |
+   | ------------ | ---------- | -------------------------------------------------------------------------------------- |
+   | apikey       | 第二步获取 | DEAP 平台 API Key                                                                      |
+   | apihost      | 默认值     | 通常为 `127.0.0.1:18789`，在Windows环境下可能需要配置为 `localhost:18789` 才能正常工作 |
+   | gatewayToken | 第一步获取 | Gateway 配置的认证令牌                                                                 |
+
+   <img width="3426" height="1752" alt="配置 OpenClaw 技能参数" src="https://github.com/user-attachments/assets/bc725789-382f-41b5-bbdb-ba8f29923d5c" />
+
+注意 OpenClaw 属于一个MCP，还需要配置他的触发规则，满足规则的情况下才会使用这个MCP:
+<img width="1088" height="526" alt="image" src="https://github.com/user-attachments/assets/8b0b6f6d-70ff-4edc-b674-7a24126aadfa" />
+
+4. 发布 Agent：
+
+   <img width="3416" height="1762" alt="发布 Agent" src="https://github.com/user-attachments/assets/3f8c3fdb-5f2b-4a4b-8896-35202e713bf3" />
+
+### 第五步：开始使用
+
+1. 在钉钉 App 中搜索并找到您创建的 Agent：
+
+   <img width="1260" height="436" alt="搜索 Agent" src="https://github.com/user-attachments/assets/30feff80-1b28-4274-830b-7045aed14980" />
+
+2. 开始自然语言对话体验：
+
+   <img width="1896" height="1240" alt="与 Agent 对话" src="https://github.com/user-attachments/assets/2a80aab8-3fbf-4d18-beea-770577cb1a40" />