npm - @dingtalk-real-ai/dingtalk-connector - Versions diffs - 0.8.14-beta.7 → 0.8.14 - Mend

@dingtalk-real-ai/dingtalk-connector 0.8.14-beta.7 → 0.8.14

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (8) hide show

package/CHANGELOG.md +41 -0
package/README.en.md +59 -490
package/README.md +60 -434
package/bin/dingtalk-connector.js +23 -8
package/docs/RELEASE_NOTES_V0.8.14.md +86 -0
package/docs/TROUBLESHOOTING.md +122 -0
package/openclaw.plugin.json +2 -6
package/package.json +28 -11

package/CHANGELOG.md CHANGED Viewed

@@ -5,6 +5,47 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+## [0.8.14] - 2026-04-15
+### 新增 / Added
+- ✨ **一键扫码安装** - 新增 `npx -y @dingtalk-real-ai/dingtalk-connector install` 命令，通过钉钉扫码一键完成机器人创建、凭证获取、插件安装和配置写入，零手动配置
+  **One-click QR install** - Added `npx` CLI command for one-click DingTalk bot setup via QR scan: creates bot, obtains credentials, installs plugin, and writes config automatically
+- ✨ **Device Authorization Flow** - 新增 `device-auth.ts` 和 `device-auth-config.ts` 模块，实现钉钉 Device Flow 授权（init → begin → poll），支持 QR 码终端渲染、指数退避轮询、2 分钟瞬时错误重试窗口
+  **Device Authorization Flow** - Added `device-auth.ts` and `device-auth-config.ts` implementing DingTalk Device Flow (init → begin → poll) with terminal QR rendering, exponential backoff polling, and 2-minute transient error retry window
+- ✨ **Onboarding 扫码授权集成** - `onboarding.ts` 配置向导新增扫码授权路径，首选一键扫码，失败时自动降级为手动输入 Client ID / Client Secret
+  **Onboarding QR auth integration** - Setup wizard now prefers one-click QR authorization, with automatic fallback to manual credential input on failure
+- ✨ **CLI 凭证暂存与恢复** - 当插件安装失败时，凭证保存到独立的 staging 文件（`.dingtalk-staging.json`），避免污染 `openclaw.json`；下次安装成功后自动恢复
+  **CLI credential staging & recovery** - Credentials saved to separate staging file on plugin install failure, auto-recovered on next successful install
+- ✨ **CLI 安装前自动清理** - 安装前自动删除旧版插件目录，清理 `openclaw.json` 中的过期 channel/plugin/allow 配置，避免验证错误
+  **CLI pre-install cleanup** - Auto-removes old plugin directory and stale config entries before install to prevent validation errors
+- ✨ **CLI 429 限流重试** - 插件安装遇到 ClawHub 429 限流时，使用 `Atomics.wait` 同步等待（15s/30s）后重试，最多 3 次
+  **CLI 429 rate limit retry** - Plugin install retries up to 3 times with synchronous backoff (15s/30s) on ClawHub 429 rate limiting
+### 改进 / Improvements
+- ✅ **Prerelease 版本自动识别** - CLI `install` 命令自动检测当前 package 是否为 prerelease 版本（alpha/beta/rc/canary），若是则传递精确版本号给 `openclaw plugins install`，确保安装正确版本
+  **Prerelease version auto-detection** - CLI auto-detects prerelease versions and passes exact version spec to `openclaw plugins install`
+- ✅ **手动配置文档拆分** - 将手动创建机器人和手动配置流程从 README 拆分到独立的 `docs/DINGTALK_MANUAL_SETUP.md`，README 精简为快速入门
+  **Manual setup docs separation** - Extracted manual bot creation and config steps to `docs/DINGTALK_MANUAL_SETUP.md`, keeping README focused on quickstart
+- ✅ **README 全面重写** - 参考飞书 OpenClaw 插件风格重写中英文 README，精简结构，突出核心功能，FAQ 迁移到 `docs/TROUBLESHOOTING.md`
+  **README overhaul** - Rewrote Chinese and English README following Lark plugin style, streamlined structure with FAQ moved to `docs/TROUBLESHOOTING.md`
+- ✅ **GitHub 索引优化** - 新增 `.gitattributes` 排除 `coverage/` 和 `docs/` 的语言统计；优化 `package.json` keywords、description、openclaw channel 元数据；`openclaw.plugin.json` 移除冗余字段
+  **GitHub index optimization** - Added `.gitattributes` for language detection; optimized `package.json` keywords, description, openclaw channel metadata; cleaned `openclaw.plugin.json`
+### 文档 / Documentation
+- 📝 **新增 `docs/DINGTALK_MANUAL_SETUP.md`** - 完整的手动创建机器人和手动配置 OpenClaw 流程文档
+  **Added `docs/DINGTALK_MANUAL_SETUP.md`** - Complete manual bot creation and OpenClaw configuration guide
+- 📝 **新增 `docs/TROUBLESHOOTING.md`** - 常见问题排查文档，涵盖机器人不回复、配置校验、HTTP 401/400、插件安装失败、国内网络等场景
+  **Added `docs/TROUBLESHOOTING.md`** - Troubleshooting guide covering common issues like bot not responding, config validation, HTTP errors, install failures, and China network issues
 ## [0.8.13] - 2026-04-08
 ### 修复 / Fixes

package/README.en.md CHANGED Viewed

@@ -1,550 +1,119 @@
 <div align="center">
   <img alt="DingTalk" src="https://raw.githubusercontent.com/DingTalk-Real-AI/dingtalk-openclaw-connector/main/docs/images/dingtalk.svg" width="72" height="72" />
-  <h1>Official DingTalk OpenClaw Connector</h1>
-  <p>Connect DingTalk bots to OpenClaw Gateway with AI Card streaming and session management</p>
+  <h1>OpenClaw DingTalk Plugin</h1>
+  <p>Official DingTalk channel plugin for OpenClaw, developed and maintained by the DingTalk team.<br/>It seamlessly connects your OpenClaw Agent to DingTalk, enabling it to directly send/receive messages, manage docs, calendars, tasks, and more.</p>
+  <p>
+    <a href="https://www.npmjs.com/package/@dingtalk-real-ai/dingtalk-connector"><img src="https://img.shields.io/npm/v/@dingtalk-real-ai/dingtalk-connector.svg?style=flat&colorA=18181B&colorB=28CF8D" alt="npm version" /></a>
+    <a href="https://www.npmjs.com/package/@dingtalk-real-ai/dingtalk-connector"><img src="https://img.shields.io/npm/dm/@dingtalk-real-ai/dingtalk-connector.svg?style=flat&colorA=18181B&colorB=28CF8D" alt="npm downloads" /></a>
+    <a href="https://github.com/DingTalk-Real-AI/dingtalk-openclaw-connector/blob/main/LICENSE"><img src="https://img.shields.io/github/license/DingTalk-Real-AI/dingtalk-openclaw-connector.svg?style=flat&colorA=18181B&colorB=28CF8D" alt="license" /></a>
+  </p>
   <p>
     <a href="README.md">简体中文</a> •
-    <a href="CHANGELOG.md">Changelog</a>
+    <a href="CHANGELOG.md">Changelog</a> •
+    <a href="https://openclaw.ai/">OpenClaw Website</a>
   </p>
 </div>
 ---
-## 📋 Table of Contents
-- [Prerequisites](#prerequisites)
-- [Quick Start](#quick-start)
-- [Features](#features)
-- [Configuration](#configuration)
-- [Troubleshooting](#troubleshooting)
-- [Advanced Topics](#advanced-topics)
-- [DingTalk DEAP Agent Integration](docs/DEAP_AGENT_GUIDE.en.md)
-- [License](#license)
----
-## Prerequisites
-Before you begin, ensure you have:
-> This connector is used as an OpenClaw Gateway plugin, and you usually don't need to install or manage Node.js runtime by yourself.
-### 1. OpenClaw Gateway
-- **Official Website**: https://openclaw.ai/
-- **Installation**: Follow the official guide to install OpenClaw
-- **Verify installation**:
-  ```bash
-  openclaw gateway status
-  ```
-  Expected output: `✓ Gateway is running on http://127.0.0.1:18789`
-### ⚠️ Version Compatibility
-**Important**: dingtalk-connector v0.8.4+ requires **OpenClaw SDK v2026.3.22 or later**.
-| dingtalk-connector Version | Minimum OpenClaw SDK Version | Notes |
-|---------------------------|------------------------------|-------|
-| v0.8.4+ | v2026.3.22+ | Uses new SDK API with improved routing and session management |
-| v0.8.3 and below | v2026.3.x | Compatible with legacy SDK |
+## Features
-**How to check versions**:
-```bash
-# Check OpenClaw version
-openclaw --version
+This plugin provides comprehensive DingTalk integration for OpenClaw:
-# Check plugin version
-openclaw plugins list
-```
-**How to upgrade**:
-```bash
-# Upgrade OpenClaw to the latest version
-npm install -g openclaw@latest
+| Category | Capabilities |
+|----------|-------------|
+| 💬 Messaging | Receive group/DM messages, auto-reply, send text/Markdown, @mentions |
-# Or use yarn
-yarn global add openclaw@latest
-```
+Additionally, the plugin supports:
-**What happens when versions are incompatible**:
-- The plugin displays a detailed error message during loading
-- The message includes upgrade and downgrade instructions
-- The plugin stops loading automatically without affecting other plugins
+- 🌊 **AI Card Streaming**: Typewriter-style live streaming responses within message cards
+- 📱 **Interactive Cards**: Real-time status updates (Thinking/Generating/Complete), confirmation buttons for sensitive operations
+- 🔒 **Permission Policies**: Flexible access control policies for DMs and group chats
+- ⚙️ **Multi-Agent Routing**: Connect multiple bots to different Agents for specialized services
+- 🖼️ **Rich Media**: Receive images/audio/file attachments, auto-upload local images
+- 🔄 **Session Management**: Multi-turn conversation context, isolated sessions for DMs/groups
-### 2. DingTalk Enterprise Account
+> 🚧 **Coming Soon** — The following business capabilities are under active development and launching soon! 🎉
-- You need a DingTalk enterprise account to create internal applications
-- Official Website: https://www.dingtalk.com/
+| Category | Capabilities |
+|----------|-------------|
+| 📄 Docs | Create, append, search, and list DingTalk documents |
+| 📅 Calendar | Create/query events, auto-attach DingTalk meeting links, DING reminders, free/busy queries |
+| 📊 AI Sheets | Create sheets, read/write rows, conditional queries |
+| ✅ Tasks | Create personal/group tasks, check status, set deadlines |
+| 📝 Reports | Submit daily/weekly reports, query history |
+| 📁 Drive | Upload/download files to DingTalk Drive |
+| 🔔 DING | Send urgent DING reminders to users/groups |
 ---
-## Quick Start
-> 💡 **Goal**: Get your DingTalk bot working in ~5 minutes
-### Operating System Support
-- macOS / Linux: Use the default shell (zsh, bash, etc.).
-- Windows:
-  - Recommended: **PowerShell** or **Windows Terminal**.
-  - OpenClaw config file path (default): `C:\Users\<YourUserName>\.openclaw\openclaw.json`.
-Whenever you see `~/.openclaw/openclaw.json` below, it is equivalent to the above path on Windows.
-### Step 1: Install the Plugin
-#### Method A: One-Click Install + QR Auth (Recommended)
-```bash
-npx -y @dingtalk-real-ai/dingtalk-connector install
-```
-This command will automatically: install the plugin -> display DingTalk authorization QR code -> wait for scan -> save credentials to config file.
-During installation, the terminal will display:
-- DingTalk authorization QR code (ASCII)
-- `Authorization URL` (open directly if the QR code cannot be displayed)
-When you see `Success! Bot configured. (机器人配置成功!)`, the authorization is complete. After authorization, please manually restart the Gateway to apply the configuration:
-```bash
-openclaw gateway restart
-```
+## Security & Risk Warnings (Read Before Use)
-> 💡 **Windows QR Code Tip**: If scanning fails on Windows, the QR code may not render correctly due to terminal resolution. Try switching to [Cmder](https://cmder.app/) and retry.
->
-> 💡 **Scan Failure Does Not Affect Installation**: Even if the QR flow fails (auth error / timeout / QR code display failure), plugin dependencies will still be downloaded and installed. After installation, follow the manual setup guide: [`docs/DINGTALK_MANUAL_SETUP.md`](docs/DINGTALK_MANUAL_SETUP.md)
+This plugin integrates with OpenClaw AI automation capabilities and carries inherent risks such as model hallucinations, unpredictable execution, and prompt injection. After you authorize DingTalk permissions, OpenClaw will act under your user identity within the authorized scope, which may lead to high-risk consequences such as leakage of sensitive data or unauthorized operations. Please use with caution.
-#### Method B: Install from Local Source (Development)
+To reduce these risks, the plugin enables default security protections at multiple layers. However, these risks still exist. **We strongly recommend that you do not proactively modify any default security settings**; once relevant restrictions are relaxed, the risks will increase significantly, and you will bear the consequences.
-If you want to develop or modify the plugin, clone the repository first:
-```bash
-# 1. Clone the plugin repository
-git clone https://github.com/DingTalk-Real-AI/dingtalk-openclaw-connector.git
-cd dingtalk-openclaw-connector
+We recommend using the DingTalk bot connected to OpenClaw as a **personal conversational assistant**. Avoid deploying it directly in enterprise production environments. If you plan to use it with a company account, please comply with your company's information security policies.
-# 2. Install dependencies (required)
-npm install
-# 3. Install in link mode (changes take effect immediately)
-openclaw plugins install -l .
-# 4. Trigger QR authorization
-node bin/dingtalk-connector.js install --local
-```
-#### Method C: Manual Installation
-1. Download or copy this repository to `~/.openclaw/extensions/dingtalk-connector`.
-2. Make sure it contains `index.ts`, `openclaw.plugin.json`, and `package.json`.
-3. Run `npm install` in that directory to install dependencies.
-#### Method D: China Mainland Installation (npm Mirror)
-If `openclaw plugins install` gets stuck at `Installing plugin dependencies...` or fails with `npm install failed` due to network issues in China, you can specify a mirror registry for that install:
-```bash
-NPM_CONFIG_REGISTRY=https://registry.npmmirror.com openclaw plugins install @dingtalk-real-ai/dingtalk-connector
-```
-If the plugin is in a partially installed state (e.g., the extension directory exists but dependencies are incomplete), you can manually reinstall dependencies:
-```bash
-cd ~/.openclaw/extensions/dingtalk-connector
-rm -rf node_modules package-lock.json
-NPM_CONFIG_REGISTRY=https://registry.npmmirror.com npm install
-```
-To make the mirror permanent, set the default npm registry:
-```bash
-npm config set registry https://registry.npmmirror.com
-```
-Or add to `~/.npmrc`:
-```
-registry=https://registry.npmmirror.com
-```
-**Verify installation**:
-```bash
-openclaw plugins list
-```
-You should see output similar to `✓ DingTalk Channel (vX.X.X) - loaded`.
-> ⚠️ **If you don't see `loaded`**, resolve the plugin loading issue before proceeding to Step 3. Otherwise, DingTalk will not appear in `openclaw channels add`.
+> By using this plugin, you are deemed to have fully understood and voluntarily assumed all related risks and responsibilities.
 ---
-### Step 2: Create a DingTalk Bot
-#### 2.1 Create Application
-1. Go to [DingTalk Open Platform](https://open-dev.dingtalk.com/)
-2. Click **"Application Development"**
-![Create Application](https://raw.githubusercontent.com/DingTalk-Real-AI/dingtalk-openclaw-connector/main/docs/images/image-1.png)
-#### 2.2 Add Bot Capability
-1. On the application details page, use the “one-click OpenClaw bot app” flow
-![Create OpenClaw bot app](https://raw.githubusercontent.com/DingTalk-Real-AI/dingtalk-openclaw-connector/main/docs/images/image-2.png)
-#### 2.3 Get Credentials
-1. Finish creation and open **"Credentials & Basic Info"**
-2. Copy your **AppKey** (Client ID)
-3. Copy your **AppSecret** (Client Secret)
-![Finish creation](https://raw.githubusercontent.com/DingTalk-Real-AI/dingtalk-openclaw-connector/main/docs/images/image-3.png)
-![Get credentials](https://raw.githubusercontent.com/DingTalk-Real-AI/dingtalk-openclaw-connector/main/docs/images/image-4.png)
-> ⚠️ **Important**: Client ID and Client Secret are your bot’s unique credentials. Store them safely.
----
+## Requirements & Installation
-### Step 3: Configure OpenClaw
+Before you start, make sure you have:
-You have three options to configure the connector:
+- **OpenClaw**: Installed and running properly. Visit the [OpenClaw website](https://openclaw.ai/) for details.
+- **Version**: OpenClaw ≥ **2026.4.9**. Check with `openclaw -v`.
-#### Option A: Re-run QR Authorization
+> If below this version, upgrade with: `npm install -g openclaw`
-> Credentials are automatically configured during plugin installation (Step 1, Method A). If you need to re-run the QR authorization:
+### One-Click Install + QR Auth (Recommended)
 ```bash
-npx -y @dingtalk-real-ai/dingtalk-connector install
+npx -y @dingtalk-real-ai/dingtalk-connector@beta install
 ```
-> 💡 **Note**: `openclaw channels add` only lists built-in channels. DingTalk is a third-party plugin — use the `npx` command above instead.
+During installation, the terminal will display a DingTalk authorization QR code. Scan it with the **DingTalk mobile app** and tap "Create Bot" to complete authorization.
-#### Option B: Edit Configuration File
-Edit the configuration file:
-- macOS / Linux: `~/.openclaw/openclaw.json`
-- Windows: `C:\Users\<YourUserName>\.openclaw\openclaw.json`
-```json
-{
-  "channels": {
-    "dingtalk-connector": {
-      "enabled": true,
-      "clientId": "dingxxxxxxxxx",
-      "clientSecret": "your_app_secret"
-    }
-  }
-}
-```
-> 💡 **Tip**: If the file already has content, add the `dingtalk-connector` section under the `channels` node.
----
-### Step 4: Restart and Test
+When you see `Success! Bot configured.`, the authorization is complete. Then restart the Gateway:
 ```bash
-# Restart OpenClaw Gateway
 openclaw gateway restart
-# Watch logs in real-time
-openclaw logs --follow
-```
-**Test your bot**:
-1. Open DingTalk app
-2. Find your bot in the contact list
-3. Send a message: `Hello`
-4. You should receive a response within 10 seconds
----
-## Features
-### ✅ Core Features
-- **AI Card Streaming** - Typewriter-like replies with real-time streaming
-- **Session Management** - Multi-turn conversations with context preservation
-- **Session Isolation** - Separate sessions for DMs, groups, and different groups
-- **Auto Session Reset** - Automatic new session after 30 minutes of inactivity
-- **Manual Session Reset** - Send `/new` or `新会话` to clear conversation history
-- **Image Auto-Upload** - Local image paths automatically uploaded to DingTalk
-- **Proactive Messaging** - Send messages to users or groups programmatically
-- **Rich Media Reception** - Receive and process JPEG/PNG images, pass to vision models
-- **File Attachment Extraction** - Parse .docx, .pdf, text files, and binary files
-- **Audio Message Support** - Send audio messages in multiple formats (mp3, wav, amr, ogg)
-- **DingTalk Docs API** - Create, append, search, and list DingTalk documents
-- **Multi-Agent Routing** - Connect multiple bots to different agents for specialized services
-- **Markdown Table Conversion** - Auto-convert Markdown tables to DingTalk-compatible format
-- **Async Mode** - Immediate acknowledgment with background processing (optional)
----
-## Configuration
-### Basic Configuration
-| Option | Environment Variable | Description |
-|--------|---------------------|-------------|
-| `clientId` | — | DingTalk AppKey |
-| `clientSecret` | — | DingTalk AppSecret |
-### Session Management
-| Option | Default | Description |
-|--------|---------|-------------|
-| `separateSessionByConversation` | `true` | Separate sessions for DMs/groups |
-| `groupSessionScope` | `group` | Group session scope: `group` (shared) or `group_sender` (per-user) |
-| `sharedMemoryAcrossConversations` | `false` | Share memory across different conversations |
-### Session routing policies (`pmpolicy` / `groupPolicy`)
-Both session routing/message policy options (including `pmpolicy` and `groupPolicy`) are supported now, so you **do not need to remove** them from existing configurations.
-> Note: field names may vary across versions/upstream; on the connector side, related policies are supported and applied (for example, `dmPolicy`/`groupPolicy` default to `open`).
-### Async Mode
-| Option | Default | Description |
-|--------|---------|-------------|
-| `asyncMode` | `false` | Enable async mode for long-running tasks |
-| `ackText` | `🫡 任务已接收，处理中...` | Acknowledgment message text |
----
-## Troubleshooting
-### Bot Not Responding
-**Symptoms**: Bot doesn't reply to messages
-**Solutions**:
-1. Check plugin status: `openclaw plugins list`
-2. Check gateway status: `openclaw gateway status`
-3. Check logs: `openclaw logs --follow`
-4. Verify the app is published/enabled in DingTalk Open Platform
----
-### Invalid Config: additional properties
-**Symptoms**:
 ```
-Problem:
-  - channels.dingtalk-connector: invalid config: must NOT have additional properties
-```
-**Cause**: Your config file contains deprecated or renamed fields that are no longer recognized.
-**Solution**: Open `openclaw.config.yaml` and remove any unsupported fields under `channels.dingtalk-connector`. Known fields to remove:
-| Old Field | Notes |
-|-----------|-------|
-| `gatewayPassword` | Deprecated legacy field |
-| `gatewayToken` | Deprecated legacy field |
-| `dmHistoryLimit` | Removed in v0.8.9 (never implemented) |
-The error message will indicate the exact field name. Remove it and restart.
----
-### HTTP 401 Error
-**Symptoms**: Error message shows "401 Unauthorized"
-**Solution**: Upgrade to the latest version.
----
-### Stream Connection 400 Error
-**Symptoms**: Logs show "Request failed with status code 400"
-**Common Causes**:
-| Cause | Solution |
-|-------|----------|
-| App not published | DingTalk Open Platform → Version Management → Publish |
-| Invalid credentials | Check `clientId`/`clientSecret` for typos or extra spaces |
-| Not Stream mode | Verify bot is configured for Stream mode (not Webhook) |
-| IP whitelist | Check if the app has IP whitelist restrictions |
-**Verification Steps**:
-1. Check app status in [DingTalk Open Platform](https://open-dev.dingtalk.com/)
-2. After any configuration change, click **Save** → **Publish**
+> 💡 **Scan failure does not affect installation**: Even if the QR flow fails, plugin dependencies will still be installed. See [Manual Setup Guide](docs/DINGTALK_MANUAL_SETUP.md) to complete configuration.
 ---
-## Advanced Topics
-### Multi-Agent Configuration
-Configure multiple bots connected to different agents:
-```json5
-{
-  "agents": {
-    "list": [
-      {
-        "id": "ding-bot1",
-        "name": "Customer Service Bot",
-        "model": "your-model-config",
-        "workspace": "~/.openclaw/workspace-bot1",
-        "identity": {
-          "name": "Service Assistant",
-          "theme": "customer service",
-          "emoji": "🤝"
-        }
-        // Other agent configurations...
-      },
-      {
-        "id": "ding-bot2",
-        "name": "Technical Support Bot",
-        "model": "your-model-config",
-        "workspace": "~/.openclaw/workspace-bot2",
-        "identity": {
-          "name": "Tech Expert",
-          "theme": "technical support",
-          "emoji": "🔧"
-        }
-        // Other agent configurations...
-      }
-    ]
-  },
-  "channels": {
-    "dingtalk-connector": {
-      "enabled": true,
-      "accounts": {
-        "bot1": {
-          "enabled": true,
-          "clientId": "ding_bot1_app_key",
-          "clientSecret": "bot1_secret"
-        },
-        "bot2": {
-          "enabled": true,
-          "clientId": "ding_bot2_app_key",
-          "clientSecret": "bot2_secret"
-        }
-      }
-    }
-  },
-  "bindings": [
-    {
-      "agentId": "ding-bot1",
-      "match": {
-        "channel": "dingtalk-connector",
-        "accountId": "bot1"
-      }
-    },
-    {
-      "agentId": "ding-bot2",
-      "match": {
-        "channel": "dingtalk-connector",
-        "accountId": "bot2"
-      }
-    }
-  ]
-}
-```
+## Usage Guide
-For more details, see [OpenClaw Multi-Agent Configuration Guide](https://gist.github.com/smallnest/c5c13482740fd179e40070e620f66a52).
+[OpenClaw DingTalk Plugin User Guide](https://alidocs.dingtalk.com/i/nodes/2Amq4vjg89GEno0zfPqoPGqdV3kdP0wQ?utm_scene=team_space)
 ---
-### Session Commands
-Users can send the following commands to start a fresh session:
+## Advanced Documentation
-- `/new`, `/reset`, `/clear`
-- `新会话`, `重新开始`, `清空对话`
+- [Manual Setup Guide](docs/DINGTALK_MANUAL_SETUP.md) — Configure credentials manually
+- [DingTalk DEAP Agent Integration](docs/DEAP_AGENT_GUIDE.en.md) — Local device operation capabilities
+- [Multi-Agent Routing](https://gist.github.com/smallnest/c5c13482740fd179e40070e620f66a52) — Bind multiple bots to different Agents
+- [Troubleshooting](docs/TROUBLESHOOTING.md) — Installation and usage issue resolution
 ---
-### DingTalk Docs via MCP (`docs.*`)
-DingTalk Docs capabilities (`docs.*`, including `docs.create` / `docs.append` / `docs.search` / `docs.list` / `docs.read`) require MCP (Model Context Protocol) to provide the underlying tools. To enable `docs.*`, install and enable the corresponding MCP Server/Tool in the OpenClaw Gateway/Agent.
-- **Where to get MCP Server/Tool**: via the [DingTalk MCP Marketplace](https://mcp.dingtalk.com/) (or your team’s internal MCP marketplace). You can also use a third-party marketplace to source an equivalent “DingTalk Docs Read / DingTalk Docs Reader” capability and connect it to OpenClaw.
-- **Where to configure**: usually at the **Gateway or Agent tool configuration** level (not in this connector).
-- **How it takes effect**: restart the Gateway and ensure the tool is exposed to the target agent.
-References (OpenClaw configuration docs):
-- `https://docs.openclaw.ai/configuration`
-- `https://docs.openclaw.ai/gateway/configuration-reference`
-Create and manage DingTalk documents from your agent:
-```javascript
-// Create document
-dingtalk-connector.docs.create({
-  spaceId: "your-space-id",
-  title: "Test Document",
-  content: "# Test Content"
-})
-// Append content
-dingtalk-connector.docs.append({
-  docId: "your-doc-id",
-  markdownContent: "\n## Appended Content"
-})
-// Search documents
-dingtalk-connector.docs.search({
-  keyword: "search keyword"
-})
-// List documents
-dingtalk-connector.docs.list({
-  spaceId: "your-space-id"
-})
-```
----
-## Project Structure
-```
-dingtalk-openclaw-connector/
-├── src/
-│   ├── core/           # Core connector logic
-│   ├── services/       # DingTalk API services
-│   ├── utils/          # Utility functions
-│   └── types/          # TypeScript type definitions
-├── docs/
-│   └── images/         # Documentation images
-├── openclaw.plugin.json # Plugin manifest
-├── package.json        # npm dependencies
-└── LICENSE
-```
----
-## Dependencies
-| Package | Purpose |
-|---------|---------|
-| `dingtalk-stream` | DingTalk Stream protocol client |
-| `axios` | HTTP client |
-| `mammoth` | Word document (.docx) parsing |
-| `pdf-parse` | PDF document parsing |
----
+## Contributing
-## DingTalk DEAP Agent Integration
+Community contributions are welcome! If you find a bug or have feature suggestions, please submit an [Issue](https://github.com/DingTalk-Real-AI/dingtalk-openclaw-connector/issues) or Pull Request.
-Connect DingTalk DEAP Agent with OpenClaw Gateway to enable natural language-driven local device operations. See **[DingTalk DEAP Agent Integration Guide](docs/DEAP_AGENT_GUIDE.en.md)** for details.
+For major changes, we recommend discussing with us first via an Issue.
 ---
 ## License
-[MIT](LICENSE)
+This project is licensed under the [MIT](LICENSE) License.
 ---