Contributing

简体中文

This repository is the community-maintained distribution of Tencent/openclaw-weixin. Contributions should preserve the openclaw-weixin plugin/channel id and its existing config and state paths unless a separately planned breaking migration is approved.

Prerequisites

• Node.js 24.16.0
• npm

Use the Node.js version in .nvmrc for the recommended development environment. The published package supports Node.js >=22.22.3, including Node.js 24 and 26. CI validates the exact Node.js 22.22.3 floor, the recommended Node.js 24.16.0 environment, and a current Node.js 26 runtime.

OpenClaw compatibility matrix

The minimum supported host remains 2026.6.1; the lockfile SDK and build metadata are pinned to 2026.9.4. CI covers the following explicit combinations rather than every host, Node.js version, and operating system combination:

OpenClaw target	Node.js	Runner	Validation
2026.6.1 (minimum)	24.15.0	Ubuntu	Compatibility
2026.7.1 (previous host)	22.22.3	Ubuntu	Compatibility
2026.8.2 (previous SDK)	24.15.0	Ubuntu, Windows	Compatibility
2026.9.1 (first September stable)	24.15.0	Ubuntu	Compatibility
2026.9.2 (previous SDK / Node.js 22 floor)	22.22.3	Ubuntu	Compatibility
2026.9.4 (lockfile SDK)	24.16.0	Ubuntu, Windows	Full
2026.9.4 (current runtime)	26	Ubuntu	Compatibility
beta (moving npm dist-tag)	24 (current patch)	Ubuntu	Compatibility

Full runs npm run check; the Ubuntu job also runs npm run pack:check and npm run audit:all. Compatibility installs the selected host without changing the lockfile, asserts the exact installed version for fixed targets, then runs npm run typecheck and npm run build against that host.

Dependency installation uses Node.js 24.16.0 (the current 24.x patch for beta) before switching to the runtime listed in the matrix. OpenClaw 2026.9.4 requires Node.js >=24.16.0 <25 || >=26.1.0, so Node.js 22 jobs retain older hosts. The plugin's own Node.js 22.22.3 floor is unchanged.

Both modes run node scripts/check-host-compatibility.mjs in a fresh process against the newly built plugin: real SDK imports, plugin/channel registration, typing callbacks, config mutation, and channel ID/alias resolution. The separate node scripts/check-plugin-install-update.mjs check exercises registry-published packages, not the current source checkout.

The beta job follows the current Node.js 24 patch because newer hosts can raise their runtime floor. Only this job enables setup-node's check-latest lookup instead of accepting an older runner-cached patch; fixed-host jobs retain their explicit Node.js versions.

CI records the exact version resolved by beta. That tag can point to a stable release or an older version than the latest stable, so it does not replace the fixed 2026.9.1, 2026.9.2, and 2026.9.4 jobs. This matrix describes CI coverage, not a claim that every future 2026.9.x release or unlisted platform combination has been validated. It does not replace human-run whole-system validation.

Choose a contribution path

Report a bug

Search existing issues before opening a Bug Report. Include the affected plugin, OpenClaw, Node.js, and platform versions; the last known working combination (or Unknown / never worked); minimal reproduction steps; expected and actual results; and sanitized key diagnostics.

Keep useful diagnostic metadata such as event names, allowlisted error or status codes, counts, sizes, timings, retry counts, and versions. Before submission, remove tokens, context tokens, account or user identifiers, message bodies, QR data, URL query parameters, raw filesystem paths, arbitrary error text, and stack traces. Automated clients must apply the same schema and redaction locally; never attach raw logs, configuration, or state files.

Report a suspected vulnerability through GitHub private vulnerability reporting, not through a public issue.

Fix a bug

Prefer a triaged issue with an observable test oracle. Repository-delegated bug fixes require agent:ready; maintainer-only work must not be delegated. Follow AGENTS.md and the architecture guide, reproduce the original failure, and add both a focused regression test and a counterexample.

For a compatibility fix, retain test cases for the previous supported behavior and the current behavior. When an OpenClaw API boundary is affected, cover the minimum supported host, the lockfile/current host, and the moving beta when relevant. State-format changes must separately cover legacy migration and current-format writes. Do not delete or weaken an old-version test to make a new version pass.

Propose or implement a feature

A Feature Request is recommended, not required. A small, well-bounded feature may be submitted directly as a pull request when its use case, acceptance criteria, non-goals, and alternatives are clear. Discuss broad, high-risk, or compatibility-affecting changes with maintainers before implementation.

Development

Install the exact dependency versions recorded in the lockfile:

npm ci

Read AGENTS.md for repository invariants and the architecture guide for lifecycle and data flow. These rules apply whether a change is written manually or with coding-agent assistance.

Run one affected suite while iterating:

npm run test:unit -- src/path/to/file.test.ts

Run the fast type, style, and unit-test gate:

npm run check:fast

Run the same formatting, linting, type checking, coverage tests, and build used by CI:

npm run check

Audit the production dependencies shipped with the plugin at the same severity used by CI and releases. Development tools and the host-provided OpenClaw peer dependency are omitted:

npm run audit:deps

Apply repository formatting with:

npm run format

Inspect the npm package contents when changing entry points, build output, or package metadata:

npm pack --dry-run --ignore-scripts

The repository's stricter package contract check is:

npm run pack:check

Registry package checks

After npm run check and npm run pack:check, create one source tarball and derive both registry packages outside the repository:

npm pack --ignore-scripts --pack-destination <source-output>
node scripts/prepare-npm-package.mjs <source-output> <npm-output>
node scripts/prepare-clawhub-package.mjs <source-output> <clawhub-output>
mkdir <clawpack-root>
tar -xzf <clawhub-output>/openclaw-wechat-<version>.tgz -C <clawpack-root>

The source README files list ClawHub's direct command first. The npm converter changes only the direct-command order to npm-first. Every registry preserves the same installation prompt: update an existing installation from its current source to the latest version; prefer ClawHub with npm fallback for a new install. The ClawHub converter keeps the direct-command order, changes the staged title and package metadata to openclaw-wechat, and uses English as its primary README. Neither converter changes the openclaw-weixin plugin and channel id.

Run the pinned ClawHub validator with its report directory outside the checkout, then preview the publish without credentials:

npx --yes clawhub@0.23.3 package validate <clawpack-root>/package \
  --out <report-output> --openclaw-version 2026.9.4 --json
npx --yes clawhub@0.23.3 package publish \
  <clawhub-output>/openclaw-wechat-<version>.tgz \
  --family code-plugin --owner newfuture --display-name WeChat \
  --categories channels --topics wechat,weixin,messaging \
  --source-repo NewFuture/openclaw-weixin --source-commit <commit-sha> \
  --source-ref <git-ref> --dry-run --json

These commands validate the next prospective version; they do not publish or modify the existing public ClawHub release. .github/workflows/clawhub-publish.yml performs this credential-free validation for pull requests only. Production npmjs, ClawHub, and GitHub Packages publication starts in parallel from an exact release tag; GitHub Release finalization waits for all three jobs. npmjs and ClawHub use separate protected npm-publish and clawhub-publish jobs. When both targets are missing, wait for both environments to become Pending, select both in Review deployments, and click Approve and deploy once; the UI action is shared, but OIDC trust remains isolated. Successful publish responses, rather than immediate registry read-after-write checks, complete their respective jobs. Do not add production dispatch, id-token: write, or a long-lived registry credential to the pull-request workflow. Before the real ClawHub command can start, the release workflow persists a durable check run plus a tag-and-commit-specific 90-day Actions artifact. ClawHub uploads and stores its own ClawPack independently of npmjs; the explicit clawhub: installer downloads that artifact directly. A new ClawHub request after either boundary requires authoritative attempt evidence and explicit recovery authorization.

npmjs and GitHub Packages do not require gap-free publication history. Their release checks permit an unpublished intermediate repository version when the exact current target is absent and registry latest is lower. GitHub Packages also rechecks the exact target plus latest immediately before publishing. Never move an immutable skipped tag to fill a registry gap; prepare and publish the next version instead.

Build the documentation website into docs/site/dist/ (the same command GitHub Pages runs) after editing Markdown documents or the files in docs/site/. The site is a VitePress project that keeps its own dependencies so that the published package manifest stays untouched, and its tests run with Node.js instead of the root Vitest project:

npm ci --prefix docs/site
npm test --prefix docs/site
npm run build --prefix docs/site

Preview the site with hot reload using npm run dev --prefix docs/site, or serve docs/site/dist/ with any static file server. Both commands first copy the repository Markdown into docs/site/content/, so always edit the original documents. The generated content/ and dist/ directories are ignored by Git; only the sources in docs/site/ are committed.

Simplified Chinese is the site's default locale and is published at the site root; English is published under /en/. A document without a translation is still published in every locale, carrying the Markdown it does have plus an untranslated notice, so register new pages in docs/site/.vitepress/docs.mjs with whichever locale sources exist.

Agent-assisted work

For work that repository maintainers may delegate, use the AI-ready Implementation Task issue form with a bounded scope and observable test oracle. agent:ready means the task may be delegated; risk:privileged marks authentication, persistent state, workflows, release, security, or package/plugin metadata; maintainer-only forbids delegation. Pull requests produced from repository-delegated tasks must link the task and state the observable result, focused oracle, highest risk, and remaining uncertainty. Agents must not receive Weixin secrets or access the live backend.

.github/workflows/copilot-setup-steps.yml prepares the standard Node.js 24.16.0 environment with npm ci. It does not replace focused tests or npm run check.

Maintenance report preview

.github/workflows/maintenance-report.md defines a manual gh-aw report for main, using Copilot CLI to summarize the last seven days of default-branch changes and merged pull requests in Chinese. Outputs are staged in the Actions step summary: the workflow does not create issues or PRs, change labels, rerun workflows, or publish releases. It does not read raw CI logs or user state. Its explicit GitHub tool allowlist permits only commit reads, file reads, commit listing, and PR search; comment, repository-search, and star APIs are not authorized for the agent.

Before the first run, a maintainer must configure the repository Actions secret COPILOT_GITHUB_TOKEN with a personal fine-grained token granting account-level Copilot Requests: Read, from an account with Copilot inference access. Do not provide Weixin credentials or enable Actions PR creation for this report. Staged mode still consumes inference; the main agent has a 100 AIC budget, 20-turn limit and 10-minute execution-step timeout, with a separate 50 AIC threat-detection budget. These are usage guardrails, not a billing guarantee.

Use the pinned compiler and commit the source with its generated lock files:

gh extension install github/gh-aw --pin v0.88.2
gh aw compile maintenance-report --strict --validate

After the workflow files are merged into main, run it manually with gh aw run maintenance-report --ref main and inspect its Actions summary. gh aw disable maintenance-report disables it; also check for remaining queued or running jobs. There is no schedule or automatic implementation phase.

Whole-system validation

Automated tests must not call the live Weixin backend, perform QR login, or use a developer's OpenClaw state. A pull request that changes runtime behavior must separately record human-run whole-system validation in the pull request template:

• operating system and architecture, Node.js, OpenClaw, and plugin version or commit;
• installation method and each tested scenario;
• expected and actual results; and
• sanitized key diagnostics that follow the reporting rules above.

Use an isolated, non-production test account. Never put credentials, QR data, account identifiers, or private message content in the pull request. The result supports only the listed environment and scenarios and does not replace automated regression tests. An agent may open a draft pull request with this result marked Pending human validation, but the pull request is not ready to merge until a human records the result. For changes that do not affect runtime behavior, write Not applicable and explain why no runtime validation is needed.

Pull requests

• Keep changes focused and include tests for behavior changes.
• List the complete affected test matrix: the original failure, a counterexample, and every affected mutually exclusive branch, error exit, and persistence boundary.
• For compatibility fixes, retain both old-version and current-version test cases and record the compatibility combinations that were run.
• Include the whole-system validation result described above for runtime behavior changes.
• Update README.md and README_EN.md for user-facing documentation.
• Update both changelogs when a change affects users. Documentation-only changes need no changelog entry.
• Remove credentials, account identifiers, QR codes, and private message content from tests, logs, screenshots, and issue descriptions.
• Pull requests receive Copilot code review and require resolved review threads. The ruleset does not require human approval; maintainers remain responsible for the final merge decision.
• Run npm run check and every additional validation required by the affected area before the pull request is ready to merge.
• Review and take responsibility for all submitted changes, including AI-assisted changes.