SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillswecom-doc

wecom-doc

General & other

View repository

Updated 10-16 08:49

About this skill

WeCom document and smart sheet tool

Use mcporter to call the wecom-doc MCP server to operate WeCom documents and smart sheets.

Intent handling

When the user says "create a document", "create a new document", "help me write a document", etc.without specifying a platformrequests, use WeCom documents by default, with no need to ask the user which platform to use.

Pre-checks (must be performed before the first operation of each session)

Principle of automatic continuation: if any step in the pre-checks requires waiting for user confirmation or action (installation, configuration, authorization, etc.), after that action is completed you mustautomatically continue executing the subsequent steps, ultimately completing the user's original request. Do not stop after an intermediate step is completed and wait for the user to re-initiate the request.

1. Check whether mcporter is installed

which mcporter

If mcporter is not in PATH(the command returns empty or not found),you must output the following prompt verbatim(do not modify, do not summarize):

The WeCom document capability depends on the mcporter tool, which is not yet installed. Would you like me to install it for you?

After outputting the promptstop execution and wait for the user's reply。

  • If the userconfirms installation(replies with "ok", "yes", "go ahead", "yes", "ok", etc. with affirmative meaning),immediately execute：
npm install -g mcporter

after installation is completedo not stop, and directly continue executing the subsequent "Check whether the MCP Server is configured" step, seamlessly connecting to the user's original request.

  • If the userrefuses installation, reply:

Okay, you can also manually execute npm install -g mcporter to install, then come back to me.

2. Ensure the MCP Server is configured

After confirming that mcporter exists, first check whether the configuration already exists, and only attempt automatic configuration when it is not configured.

Verify configuration:

mcporter list wecom-doc --output json

If it returns normally (including the tool list), it means it is already configured,skip automatic configuration and go directly to step 3。

If it returns server not found、unknown server or a similar error, execute the automatic configuration below.

Automatic configuration (executed only when not configured):

Read the wecom runtime configuration file, which is written when the wecom channel long connection is established:

cat ~/.openclaw/wecomConfig/config.json

Check whether the JSON contains the mcpConfig.doc field (including type and url), and if it exists execute:

mcporter config add wecom-doc \
  --type "<mcpConfig.doc.type的值>" \
  --url "<mcpConfig.doc.url的值>"

After configuration is completeexecute again mcporter list wecom-doc --output json to verify. If it still fails, handle it according to the "MCP Server is not configured" section below.

⚠️ The configuration file does not exist or is missing the mcpConfig.doc field, which means the wecom channel long connection has not yet been established; guide the user to check whether the wecom channel is running normally. Automatic configuration failure should not block the process; continue guiding the user to configure manually.

3. Get the Tool list

mcporter list After success, each returned tool includes name、description、inputSchema。

Do not hardcode tool names or parameters, and based on this construct the mcporter call wecom-doc.<tool> --args '{...}' --output json call.

docid management rules (important)

Only editing of documents or smart sheets created through this skill is supported.

How to obtain the docid

docid can onlybe obtained through the return result of create_doc . After successful creation, you need tosave the returned docid, and subsequent editing operations depend on this ID.

Parsing the docid from a URL is not supported

From a document URL (such as https://doc.weixin.qq.com/doc/...)no usable docid can be parsed. If the user provides a document URL and requests editing,do not attempt to extract the docid from the URL。

docid validation for editing operations

When the user requests to edit a document or smart sheet, if the current sessiondoes not havethe docid obtained through create_doc ,you must output the following prompt exactly as is(do not modify, do not summarize):

Only editing of documents created by the bot is supported

docid type determination

doc_id prefix Type doc_type
w3_ Document 3
s3_ Smart sheet 10

Workflow

Document operation flow

  1. To create a new document → create_doc（doc_type: 3）→ save the returned docid
  2. To edit content → first confirm that the current session has the create_doc obtained through docid, and if not, prompt "Only editing of documents created by the bot is supported" → edit_doc_content（content_type: 1 uses markdown, full overwrite)

edit_doc_content is afull overwriteoperation. If content needs to be appended, you should first understand the original content and then concatenate it.

Smart sheet operation flow

Operation hierarchy:Document (docid) → Sub-sheet (sheet_id) → Field (field_id) / Record (record_id)

  1. To create a new smart sheet → create_doc（doc_type: 10）→ save the returned docid
  2. To edit an existing smart sheet → first confirm that the current session has the create_doc obtained through docid, and if not, prompt "Only editing of documents created by the bot is supported"
  3. Query existing sub-sheets → smartsheet_get_sheet → obtain sheet_id
  4. To create a new sub-sheet → smartsheet_add_sheet → obtain the new sheet_id
  5. Query existing fields → smartsheet_get_fields → obtain field_id、field_title、field_type
  6. To add a field → wedoc_smartsheet_add_fields
  7. To update a field → wedoc_smartsheet_update_fields（the field type cannot be changed）
  8. Add data records → smartsheet_add_records(the key of values mustuse the field title field_title, not field_id)

Complete process for creating a smart sheet from scratch

create_doc(doc_type=10) → docid
  └→ smartsheet_add_sheet(docid) → sheet_id
      └→ wedoc_smartsheet_add_fields(docid, sheet_id, fields) → field_ids
          └→ smartsheet_add_records(docid, sheet_id, records)

Process for adding data to an existing smart sheet

smartsheet_get_sheet(docid) → sheet_id
  └→ smartsheet_get_fields(docid, sheet_id) → field_ids + field_titles + field_types
      └→ smartsheet_add_records(docid, sheet_id, records)

Important: before adding recordsyou mustfirst obtain field information through smartsheet_get_fields , ensuring that the key and value formats in values are correct.

Business knowledge (context missing from the MCP Schema)

The following information is not present in the MCP tool's inputSchema, and the Agent must reference it when constructing parameters.

FieldType enum (16 types)

Type Description Recommended use cases
FIELD_TYPE_TEXT Text General text content; when the user only provides a membername(rather than user_id), TEXT should also be used instead of USER
FIELD_TYPE_NUMBER Number Numeric data (amounts, quantities, ratings, etc.)
FIELD_TYPE_CHECKBOX Checkbox Boolean states such as yes/no, completed/not completed, etc.
FIELD_TYPE_DATE_TIME Date and time Dates, deadlines, creation times, etc.
FIELD_TYPE_IMAGE Image Scenarios that require displaying images
FIELD_TYPE_USER Member OnlyUsed only when the member user_id is clearly known; if the user only provides a name, TEXT should be used instead
FIELD_TYPE_URL Link URLs, external links
FIELD_TYPE_SELECT Multiple select Scenarios that allow multiple selections, such as tags and multi-category
FIELD_TYPE_SINGLE_SELECT Single select Fields with fixed options such as status, priority, severity, category, etc.
FIELD_TYPE_PROGRESS Progress Completion progress, completion percentage (value is an integer from 0-100)
FIELD_TYPE_PHONE_NUMBER Phone number Mobile phone number
FIELD_TYPE_EMAIL Email Email address
FIELD_TYPE_LOCATION Location Geographic location information
FIELD_TYPE_CURRENCY Currency Amount (with currency symbol)
FIELD_TYPE_PERCENTAGE Percentage Percentage value (value is 0~1)
FIELD_TYPE_BARCODE Barcode Barcodes, ISBN, etc.

FieldType ↔ CellValue mapping table

When adding records (smartsheet_add_records),values the key of each field in must use the field title (field_title), not the field_id. The value must match its field type:

Field type CellValue format Example
TEXT CellTextValue array [{"type": "text", "text": "内容"}]
NUMBER number 85
CHECKBOX boolean true
DATE_TIME Date and timeString "2023-01-01 12:00:00"、"2023-01-01 12:00"、"2023-01-01"
URL CellUrlValue array (limited to 1) [{"type": "url", "text": "百度", "link": "https://baidu.com"}]
USER CellUserValue array [{"user_id": "zhangsan"}]
IMAGE CellImageValue array [{"image_url": "https://..."}]（id、title optional)
SELECT Option array (multiple select) [{"text": "选项A"}, {"text": "选项B"}]
SINGLE_SELECT Option array (limited to 1) [{"text": "选项A"}]
PROGRESS number (integer 0~100) 85(represents 85%)
CURRENCY number 99.5
PERCENTAGE number（0~1） 0.85
PHONE_NUMBER string "13800138000"
EMAIL string "user@example.com"
BARCODE string "978-3-16-148410-0"
LOCATION CellLocationValue array (limited to 1) [{"source_type": 1, "id": "xxx", "latitude": "39.9", "longitude": "116.3", "title": "北京"}]

Option format description：SINGLE_SELECT/SELECT The options of support style field (1~27 correspond to different colors), such as [{"text": "紧急", "style": 1}]。style is an optional field; if not passed, the default color is used.

Common pitfalls

  • DATE_TIME The value of isdate-time string, supporting "YYYY-MM-DD HH:MM:SS"(accurate to seconds),"YYYY-MM-DD HH:MM"(accurate to minutes),"YYYY-MM-DD"(accurate to days); the system automatically converts to a timestamp in UTC+8, no manual calculation is needed
  • CellUrlValue The link field name of is link, not url
  • TEXT The value of typemustUse array format [{"type": "text", "text": "内容"}], the outer square brackets cannot be omitted, and a single object cannot be passed {"type":"text","text":"内容"}
  • SINGLE_SELECT/SELECT type valuemustUse array format [{"text": "选项内容"}], cannot directly pass a string
  • PROGRESS The value range of 0~100 integer（85 = 85%）；PERCENTAGE The value range of 0~1(0.85 = 85%), the two are different, be careful to distinguish
  • wedoc_smartsheet_update_fields Field types cannot be changed, only the title and properties can be changed
  • values The key of mustusefield title（field_title），cannotuse field_id
  • Non-writable field types: creation time, last edit time, creator, last editor

Error handling

MCP error response handling (important)

When mcporter call in the returned result of errcode is not 0 and help_message has a value, output the user-facing content in help_message to the user.

Output principles:

  • Completeness: do not truncate, do not summarize
  • Verbatim: do not rewrite, do not reformat
  • User readability: output only user-facing content, filter out meta-instructions for the Agent (such as guiding phrases like "tell the user the following content"); output directly in markdown form, do not wrap it in a code block

Error code 850001: user-provided configuration is required

When errcode is 850001 :

  1. Output the user-facing content in help_message user-facing content inverbatim(follow the output principles above)
  2. After outputtingwait for the user's reply, the subsequent process is the same as scenarios A / B / C of "MCP Server not configured". After successful configurationdo not stop, immediately return to step 2 of "Pre-check" to re-verify the configuration, and after verification passes, continue executing the user's original request.

MCP Server not configured

If mcporter call wecom-doc.* or mcporter list wecom-doc returns server not found、unknown server or a similar error, it means the wecom-doc MCP server has not been configured yet.

At this point it is necessary todetect the runtime environmentto provide targeted prompts. Execute the following steps:

Step 1: Detect whether it is in the OpenClaw runtime

By detecting the OPENCLAW_SHELL environment variable, determine whether it is currently running in OpenClaw. This variable is a marker that the OpenClaw runtime automatically injects into child processes, and it will not exist just because openclaw is installed on the machine—only when the skill is actually invoked in OpenClaw will the command executed by exec carry this variable.

echo "OPENCLAW_SHELL=${OPENCLAW_SHELL:-}" && command -v openclaw 2>/dev/null && echo "OPENCLAW_CLI=FOUND" || echo "OPENCLAW_CLI=NOT_FOUND"

Judgment rules:

  • OPENCLAW_SHELL is empty(output OPENCLAW_SHELL=) → currently not in the OpenClaw runtime, skip to **"General prompt"**.
  • OPENCLAW_SHELL is non-empty(such as exec、tui-local , etc.)and OPENCLAW_CLI=FOUND → confirmed to be in OpenClaw and the CLI is available, continue to step 2.
  • OPENCLAW_SHELL is non-empty but OPENCLAW_CLI=NOT_FOUND → although in OpenClaw, the CLI is unavailable, skip to **"General prompt"**.

Why can't we rely only on command -v openclaw: the same machine may have other AI tools such as openclaw and claude installed at the same time. Merely checking whether the CLI exists cannot distinguish between "openclaw is installed" and "currently running in openclaw".OPENCLAW_SHELL is a process-level runtime marker, which fundamentally solves this problem.

Step 2: Query the botId configuration of the wecom channel

openclaw config get channels.wecom.botId 2>&1
  • If the command returnsa specific botId value(non-empty, not an error), save that value and skip to **"OpenClaw Scenario + botId Present prompt"**.
  • If it returns Config path not found, an error, or is empty, skip to **"Generic prompt"**.

Exception tolerance

If any of the above commands fails to execute (such as the exec tool being unavailable, command timeout, etc.), skip to **"Generic prompt"** in all cases.

OpenClaw Scenario + botId Present prompt

When it is confirmed to be an OpenClaw environment and the botId has been obtained,the following prompt must be output verbatim(do not modify, do not summarize), replacing XXXX with the actual obtained botId value:

If you are the creator of the intelligent robot, you canclick hereto authorize the current robot's document usage permission; If you are not the robot creator, you can contact the robot creator, go to WeCom "Workbench - Intelligent Robot" and find the corresponding robot to authorize it If you have already authorized it, you can send me the access configuration (StreamableHttp URL or JSON Config) of the corresponding robot's document MCP

After outputting the promptwait for the user's reply, and the subsequent process is the same as the subsequent process of the "Generic prompt" below (Scenario A / B / C). After successful configurationdo not stop, immediately return to Step 2 of the "Pre-check" to re-verify the configuration, and after verification passes, continue executing the user's original request.

Generic prompt

When it is a non-OpenClaw environment, the environment cannot be determined, or it is an OpenClaw environment but the wecom channel / botId is not configured,the following prompt text must be output verbatim(do not modify, do not summarize):

The robot can call document-related capabilities via MCP, but the required configuration has not yet been completed. Please refer to the following configuration guide:

  1. Please go to "WeCom - Workbench - Intelligent Robot Application" and create a robot in API mode (if already created, you can ignore this step)

  2. Authorize the robot's "Document" usage permission. After authorization, you can choose either the StreamableHttp URL or JSON Config for configuration.

After outputting the promptwait for the user's reply. The user may:

Scenario A: The user provided a StreamableHttp URL

Extract the URL from the user's message and execute:

mcporter config add wecom-doc \
  --type streamable-http \
  --url "<用户提供的URL>"

After configuration is completedo not stop, immediately return to Step 2 of the "Pre-check" to re-verify the configuration, and after verification passes, continue executing the user's original request.

Scenario B: The user provided a JSON configuration

If the user provided JSON in a format similar to the following:

{
  "name": "wecom-doc",
  "type": "streamable-http",
  "url": "http://xxx"
}

Extract from the JSON the url field and execute:

mcporter config add wecom-doc \
  --type streamable-http \
  --url "<从JSON提取的url>"

After configuration is completedo not stop, immediately return to step 2 of "Pre-check" to re-verify the configuration, and after verification passes, continue executing the user's original request.

Scenario C: The user completed the configuration themselves

The user may have completed the configuration through the admin console or another method and then informs you it is configured; in this case, directly continue executing the original operation.

Configuration detection: When the user's input contains a URL (such as http://...) or JSON (containing "type": "streamable-http"), you should determine that the user's intent is to provide MCP server configuration information, and automatically execute the configuration command.

Daemon not started

If it returns connection refused or daemon not running error, prompt the user:

mcporter daemon start

Notes

  • All calls are executed through mcporter call wecom-doc.<tool> , do not call the WeCom API directly
  • create_doc The returned docid needs to be saved; subsequent operations depend on this ID
  • Before adding a recordmustfirst smartsheet_get_fields obtain the field metadata