weread.koplugin: reading WeRead on KOReader e-readers

What weread.koplugin solves, and for whom

WeRead is Tencent's reading service, and its client exists for phones, tablets and the web. Amazon Kindle and most Kobo devices do not run those clients. KOReader, the open source document reader, does run on both, but it has no built-in way to reach a WeRead library. This plugin is the bridge between the two.

The README states the scope plainly: it reads books and WeChat official account (公众号) articles from WeRead inside KOReader, syncs reading progress, reports and charts reading time, and lets you view reviews, highlights and thoughts. For locally stored books, it can fetch the highlights and thoughts that live on the WeRead side and show them against the local text. The target user is someone with a Kindle or Kobo, an existing KOReader setup, and a WeRead account they actually use on their phone.

That last point matters. The plugin is not a standalone reader and does not replace KOReader's own library. It adds a second source of content and a sync channel, which means it is only worth the setup cost if WeRead is already where your books live.

The mechanism: QR login, a Skill API Key, and a local cache

Authentication is the first constraint. The plugin supports only WeChat QR login. Before scanning, you must open the WeRead app on your phone, go to 我 → 设置 → 微信读书 Skill, and generate a personal API Key. Only then does 工具 → 微信读书 → 微信扫码登录 produce a code you confirm on the phone, and if the phone shows a four-digit verification code, you type it into KOReader.

Content arrives through downloads rather than streaming. The menu exposes multi-chapter download, whole-book download, and an optional pre-download of the next chapter. Downloaded books land in a cache directory that the settings menu can show and clear, and there is a scan step that associates local books with their WeRead counterparts. The 划线和想法管理 submenu is the most interesting part of the design: it matches a local book to a WeRead title, then downloads highlights and thoughts as a separate layer. The README is explicit that this does not modify the EPUB file or KOReader's own notes, which means annotations live in the plugin's storage and can be re-fetched by cleaning and re-matching.

Progress and time flow the other way. 进度管理 has two switches, both off by default: pull progress on open, and upload progress on close. Reading-time reporting runs in the background and can be limited to actual reading, with a target book either auto-associated or set by hand. None of this is automatic until you turn it on, which is a deliberate default given that it writes to your account.

Installing weread.koplugin and opening the first book

The README recommends KOReader 2026.03 or later, warning that older builds may fail to load the plugin, with the symptom being that 工具 → 微信读书 never appears. Installation is a file copy, not a package manager operation. Download the zip from GitHub Releases, extract it, and place the resulting folder where KOReader looks for plugins.

# after extracting weread.koplugin-vX.Y.Z.zip
koreader/plugins/weread.koplugin/

Restart KOReader and confirm the entry exists.

工具 → 微信读书

If the menu is there, open it and sign in. The account must have a Skill API Key first, generated in the phone app, and the login itself is a QR scan confirmed on the phone.

工具 → 微信读书 → 微信扫码登录

After login the bookshelf appears with 书籍 and 公众号 tabs. Open a book and the plugin downloads it into its cache; the README's screenshots show 下载全书 and multi-chapter selection for doing this ahead of time. Later updates do not require repeating the copy: 微信读书 → 设置 → 更新管理 updates the plugin online, and 关于 offers a manual check plus an optional daily automatic check.

Where the design gets in the way

The login model is the sharpest limitation. There is no password login, no token file you can seed from a script, and no headless path. Every device needs a phone in hand at setup. The settings include 立即续期 Cookie under 账号管理, which implies sessions expire and you will occasionally repeat the dance.

The README's own disclaimer is unusually blunt: the project is for personal study and technical research, not commercial use, and the author disclaims responsibility for account bans or data loss. That is not boilerplate caution. Reporting reading time and uploading progress means the plugin writes to a WeRead account through an interface the account holder did not officially provision for third-party clients, and the README tells you the consequences are yours.

Annotation handling is the other rough edge. The XPointer external annotation layer is described in the README as still experimental, with limits documented in docs/xpointer-overlay-prototype.md. And the highlight layer only applies to books you have matched. For a local book with no WeRead counterpart, 匹配微信读书书目 and 继续匹配 have nothing to bind to, so the feature is simply unavailable. Anyone expecting their sideloaded library to gain WeRead annotations automatically will be disappointed.

Finally, the defaults are conservative in ways that surprise people. Progress pull and push are both off, automatic pre-download of the next chapter is off and warns about network stalls when enabled, and the daily update check is off. A new user can finish setup and see no synchronization at all until they visit 设置 and enable it.

How it differs from KOReader's built-in sync and from Calibre workflows

KOReader already has a progress sync mechanism, and the difference in approach is the source of truth. Built-in sync keeps progress between KOReader instances, typically through a sync server you or someone else runs; the WeRead account is not involved. This plugin syncs against WeRead itself, so progress made on the phone app appears on the Kindle and vice versa. If your reading happens across WeRead's own clients, the plugin is the only one of the two that can see that.

The comparison with a Calibre-based workflow is starker. Calibre converts and transfers files; it has no concept of a WeRead account, no reading-time reporting, and no way to pull highlights from a service. A Calibre user gets a static file on the device and owns it completely. A weread.koplugin user gets a cached copy with an annotation layer that depends on a live account and an expiring session. The trade is sync and convenience against independence, and the README's licence section makes the code side of that trade explicit: AGPL-3.0-only, matching KOReader, so modifications and redistributions must stay open under the same terms.

Licence, maintenance and what an upgrade costs

The code is AGPL-3.0-only, the same licence KOReader uses, and the README states that modifications, integrations and redistributions must keep the copyright and licence notices and publish derivative source under the licence. One file is carved out: fonts/NotoEmoji-Regular.ttf ships under SIL Open Font License 1.1, with its own LICENSE file in fonts/. If you fork the plugin for internal use, the font's terms travel separately from the code's. This is a description of what the repository says, not legal advice.

The repository is not archived, and the last push was on 2026-09-15, two days before this writing. Releases v1.4.0, v1.4.1 and v1.4.2 all landed on 2026-09-05 and 2026-09-06, so the release cadence around that period was dense. In practical terms that means the plugin is moving, and moving projects break things. The README pins a minimum KOReader version for a reason: issue #14 is cited as the case where an older build failed to show the menu. An upgrade path therefore has two moving parts, the plugin and KOReader itself, and the plugin's own 更新管理 menu handles only the first.

The maintenance cost on the user side is the account session. Cookie renewal is a manual menu action, and the login is QR-based, so a device that sits unused for months will need a phone before it can sync again. Budget for that, not for a one-time setup.

Editorial conclusion

Adopt it if you already run KOReader on a Kindle or Kobo and your WeRead account can generate a Skill API Key, because the plugin's value is exactly the gap it fills: no official WeRead client exists for those devices. Skip it if you read only sideloaded DRM-free files, or if you cannot accept the README's own disclaimer that account bans and data loss are the user's risk. Before installing, confirm your KOReader build is 2026.03 or later and that 工具 → 微信读书 appears after a restart; if the menu entry is missing, the plugin has not loaded and nothing else will work.

Frequently asked questions

Official sources

1. finlater/weread.koplugin on GitHub
2. Issues
3. License: AGPL-3.0
4. README
5. Releases