diff --git a/README.md b/README.md
index 9d24f3a7..4c003f43 100644
--- a/README.md
+++ b/README.md
@@ -276,6 +276,52 @@ curl -fsSL https://raw.githubusercontent.com/DingTalk-Real-AI/dingtalk-workspace
## Features
+
+Raw API Access — call any DingTalk OpenAPI directly
+
+`dws api` lets you call any DingTalk OpenAPI without an SDK. Tokens are automatically acquired and refreshed.
+
+> **Prerequisite**: Must login with your own app credentials (see [Custom App mode](#getting-started)). Encrypted tokens from MCP default-credential login are not supported for raw API calls.
+
+```bash
+# Login (first time only)
+dws auth login --client-id --client-secret
+
+# === api.dingtalk.com ===
+
+# Get current user info
+dws api GET /v1.0/contact/users/me
+
+# Search users (POST + JSON body)
+dws api POST /v1.0/contact/users/search \
+ --data '{"queryWord":"engineering","offset":0,"size":10}'
+
+# === oapi.dingtalk.com ===
+
+# Get user details (use --base-url to specify domain)
+dws api POST /topapi/v2/user/get \
+ --base-url https://oapi.dingtalk.com \
+ --data '{"userid":"manager123"}'
+
+# Or use the full URL directly
+dws api POST https://oapi.dingtalk.com/topapi/v2/user/get \
+ --data '{"userid":"manager123"}'
+
+# === General ===
+dws api GET /v1.0/attendance/groups --page-all # auto-paginate
+dws api GET /v1.0/contact/users/me --dry-run # preview request
+dws api GET /v1.0/contact/users/me --jq '.nick' # jq filtering
+```
+
+| Feature | Details |
+|---------|----------|
+| Dual-form auto-detection | Automatically selects api.dingtalk.com (header auth) or oapi.dingtalk.com (query-param auth) based on URL |
+| Automatic token management | App-level accessToken is fetched on first call, cached while valid, auto-refreshed on expiry |
+| Domain allowlist | Only `api.dingtalk.com` and `oapi.dingtalk.com` permitted — prevents token leakage |
+| Auto-pagination | `--page-all` iterates all pages; `--page-limit` caps the maximum |
+
+
+
Smart Input Correction — auto-corrects common AI model parameter mistakes
@@ -367,8 +413,9 @@ dws chat message send-by-bot --robot-code BOT_CODE --group GROUP_ID \
| Drive | `drive` | 6 | `list` `info` `download` `mkdir` `upload-info` `commit` | DingTalk drive file ops: list, info, download, create folders, two-phase upload |
| Minutes | `minutes` | 19 | `list` `get` `update` `mind-graph` `speaker` `hot-word` `upload` | List AI meeting notes (mine / shared), details (info / summary / keywords / transcription / todos / batch), title/summary updates, mind map, speaker replace, hot-word, upload session |
| DevDoc | `devdoc` | 1 | `article` | Search the DingTalk Open Platform documentation |
+| Raw API | `api` | 1 | — | Call any DingTalk OpenAPI directly (api / oapi dual-form), with automatic app-level token management |
-> **159 commands across 13 products.** Full listing with descriptions and usage scenarios: [`docs/command-index.md`](./docs/command-index.md). Run `dws --help` for the top-level tree, or `dws --help` for subcommands.
+> **160 commands across 13 products.** Full listing with descriptions and usage scenarios: [`docs/command-index.md`](./docs/command-index.md). Run `dws --help` for the top-level tree, or `dws --help` for subcommands.
> **Note on `chat bot`**: bot capabilities (`send-by-bot` / `recall-by-bot` / `add-bot` / `send-by-webhook` / bot search) are merged into the relevant `chat` subtrees (e.g. `dws chat message send-by-bot`, `dws chat group members add-bot`) so the agent-facing command surface stays flat and discoverable. There is no longer a separate top-level `bot` product.
diff --git a/README_zh.md b/README_zh.md
index 81facb79..03fc62f4 100644
--- a/README_zh.md
+++ b/README_zh.md
@@ -276,6 +276,52 @@ curl -fsSL https://raw.githubusercontent.com/DingTalk-Real-AI/dingtalk-workspace
## 功能特性
+
+Raw API 调用 — 直接调用钉钉 OpenAPI
+
+`dws api` 让你直接调用任意钉钉 OpenAPI，无需 SDK，Token 自动获取和刷新。
+
+> **前置条件**：必须使用自有应用凭证登录（见[自建应用模式](#开始使用)）。通过 MCP 默认凭证登录的加密 token 不支持 raw API 调用。
+
+```bash
+# 登录（仅首次）
+dws auth login --client-id --client-secret
+
+# === api.dingtalk.com ===
+
+# 获取当前用户信息
+dws api GET /v1.0/contact/users/me
+
+# 搜索用户 (POST + JSON body)
+dws api POST /v1.0/contact/users/search \
+ --data '{"queryWord":"张三","offset":0,"size":10}'
+
+# === oapi.dingtalk.com ===
+
+# 获取用户详情（使用 --base-url 指定域名）
+dws api POST /topapi/v2/user/get \
+ --base-url https://oapi.dingtalk.com \
+ --data '{"userid":"manager123"}'
+
+# 也可以直接使用完整 URL
+dws api POST https://oapi.dingtalk.com/topapi/v2/user/get \
+ --data '{"userid":"manager123"}'
+
+# === 通用功能 ===
+dws api GET /v1.0/attendance/groups --page-all # 自动翻页
+dws api GET /v1.0/contact/users/me --dry-run # 预览请求
+dws api GET /v1.0/contact/users/me --jq '.nick' # jq 过滤
+```
+
+| 特性 | 说明 |
+|------|------|
+| 双形态自动识别 | 根据 URL 自动选择 api.dingtalk.com（Header 认证）或 oapi.dingtalk.com（Query 参数认证） |
+| Token 自动管理 | 首次调用自动获取应用级 accessToken，有效期内缓存，过期自动刷新 |
+| 域名白名单 | 仅允许 `api.dingtalk.com` 和 `oapi.dingtalk.com`，防止 Token 泄露 |
+| 自动分页 | `--page-all` 自动遍历所有分页，`--page-limit` 控制上限 |
+
+
+
智能输入纠错 — 自动修正 AI 模型常见的参数错误
@@ -367,8 +413,9 @@ dws chat message send-by-bot --robot-code BOT_CODE --group GROUP_ID \
| 钉盘 | `drive` | 6 | `list` `info` `download` `mkdir` `upload-info` `commit` | 钉盘文件操作：列表、详情、下载、创建文件夹、两阶段上传 |
| AI 听记 | `minutes` | 19 | `list` `get` `update` `mind-graph` `speaker` `hot-word` `upload` | 听记列表（我创建 / 共享给我）、详情（info / summary / keywords / transcription / todos / batch）、标题/摘要更新、思维导图、发言人替换、热词、上传会话 |
| 开发者文档 | `devdoc` | 1 | `article` | 搜索钉钉开放平台文档 |
+| Raw API | `api` | 1 | — | 直接调用任意钉钉 OpenAPI（api / oapi 双形态），自动管理应用级 Token |
-> **13 个产品，159 条命令。** 完整命令清单（带描述与使用场景）：[`docs/command-index.md`](./docs/command-index.md)。运行 `dws --help` 查看顶层命令树，或 `dws --help` 查看子命令。
+> **13 个产品，160 条命令。** 完整命令清单（带描述与使用场景）：[`docs/command-index.md`](./docs/command-index.md)。运行 `dws --help` 查看顶层命令树，或 `dws --help` 查看子命令。
> **关于 `chat bot`**：机器人能力（`send-by-bot` / `recall-by-bot` / `add-bot` / `send-by-webhook` / bot 搜索）已合并到对应的 `chat` 子树下（例如 `dws chat message send-by-bot`、`dws chat group members add-bot`），保持 agent 视角下的命令面扁平易发现。不再有独立的顶层 `bot` 产品。