功能描述

Gmail inbox triage, labeling, and safe archiving with gog plus a configurable lightweight LLM review layer. Use when building or running Gmail automation tha...

使用说明 (SKILL.md)

Gmail Labeler

Name: gmail-labeler
Author: felipematos

A production-oriented Gmail labeling workflow built around:

gog for Gmail access
a local overlay for private rules/accounts/routes
a hybrid review flow: heuristics first, lightweight LLM review for ambiguity-band messages
a 15-minute cron-friendly runner

What it does

Classifies inbox items into non-actionable vs actionable buckets
Applies Gmail labels and archives non-actionable mail
Keeps replies, opportunities, urgent billing items, and other actionable mail in Inbox
Supports English, Portuguese, and Spanish keyword coverage out of the box
Logs every decision to JSONL for auditability and tuning
Purges logs older than 30 days
Supports a daily self-improvement review loop based on prior decisions and user corrections

Default categories

Non-actionable

Newsletters
Promotions
Notifications
Ordinary receipts

Actionable

Billing issues
Replies
Opportunities
Action Required

What stays local/private

Keep user-specific editorial, business, or inbox-policy rules in the local overlay, not in the shared skill defaults. Examples of local-only rules:

PR / press release handling
press trip or media invitation routing
VIP sender policies
business-specific labels
custom notification routes

Operating model

1. Sender-type-first routing

Classify sender as:

person
company
person_or_unknown

This keeps bulk automated mail cheap to classify and reserves deeper review for ambiguous or human-origin messages.

2. Inbox-by-exception policy

Treat Inbox as an action queue, not a reading queue. Recommended default:

processed mail always gets Auto/Triaged
mail stays in Inbox only when it is clearly actionable / important
everything else should leave Inbox, even when the category is still somewhat generic

Practical effect:

important/actionable mail → keep in Inbox and add category labels when possible
non-important mail → remove INBOX, keep Auto/Triaged, then add a best-fit category label (Notification, Newsletter, Receipt, Press Releases, etc.)

3. Confidence-band review

Use heuristics first. Then send only ambiguity-band messages to a lightweight LLM review.

Recommended pattern:

high confidence → trust heuristics
medium confidence → LLM review
low confidence → conservative fallback

4. Conservative-but-useful fallback

If a message is clearly automated/company-origin but no specific filter matches, prefer a generic non-actionable classification (for example Notification) over leaving it untouched in Inbox.

5. Label normalization

Use a small canonical label set and avoid near-duplicates caused by translation, singular/plural, or typos. Example normalization targets:

Press Release → Press Releases
finance label variants → one canonical finance label
keep Auto/Triaged as the universal processed marker

Gmail-native labels to prefer

Use Gmail system labels when possible:

CATEGORY_PROMOTIONS
CATEGORY_UPDATES
IMPORTANT
STARRED
INBOX

Create custom labels only when needed, for example:

Newsletter
Notification
Receipt
Opportunity
Action Required
Auto/Triaged

Local overlay design

Keep the skill publishable by storing private configuration outside the skill directory.

Recommended local overlay path:

~/.openclaw/local/gmail-labeler.config.json

Store private values only in the local overlay:

email accounts
VIP senders/domains
notification targets
business-specific opportunity rules
personal/custom labels

Logging and review

Decision logs should live outside the skill source tree, for example:

/home/ubuntu/.openclaw/gmail-labeler-logs/

Recommended format:

one JSONL file per day
one row per decision
separate error rows

Suggested daily review inputs:

yesterday's decision log
false positives / false negatives
over-aggressive archiving
missed billing urgency
missed opportunities
user-requested corrections

Files to read

references/default-config.json
references/config-guide.md
references/filter-catalog.md
references/implementation-notes.md
references/logging-and-review.md
references/llm-review.md
references/cron-example.md
references/ain-email-review.schema.json

Runners

Main runner: scripts/gmail_labeler_runner.py
Launcher example: scripts/gmail_labeler_run.sh

Publishing guidance

Before publishing:

keep only generic defaults in the skill
remove personal accounts, chat ids, private domains, and custom user rules
keep examples generic
document clearly that private configuration belongs in the local overlay
keep PR / press-release handling user-specific when it reflects private editorial policy; do not publish those local heuristics by default
validate cron/non-interactive execution via the launcher, not only via direct Python invocation

安全使用建议

This skill implements plausible Gmail triage logic, but it has important undeclared dependencies and secret-handling behavior you should verify before installing. Actionable steps: - Expect to provide Gmail access credentials (gog account/token). The default config uses GOG_ACCOUNT and the launcher expects a GOG_KEYRING_PASSWORD; these env vars/secrets should be explicitly declared and reviewed. - The launcher script calls 'doppler'. If you don't use Doppler, edit the launcher or provide the key by another safe mechanism; do not run the provided script as-is unless you trust the Doppler project/configuration it references. - The install pulls an npm package (@felipematos/ain-cli) for LLM review. Decide whether you trust that package and whether you want Node/npm installed on the agent host. - LLM review can require provider API keys (not declared). If you enable the LLM layer, make sure provider credentials are stored locally/outside the skill and that the skill is configured to use them explicitly. - Run in dry-run mode on a non-production account first and inspect logs (they are written outside the skill folder by default) to confirm no unexpected outbound endpoints or secret exfiltration. - To improve confidence, ask the skill author to: (1) declare required binaries (gog, python3, doppler, node/npm if applicable), (2) list required env vars (GOG_ACCOUNT, GOG_KEYRING_PASSWORD or how to supply it), and (3) document any LLM provider credential expectations. If you cannot obtain those clarifications, treat the skill as risky for production Gmail accounts.

功能分析

Type: OpenClaw Skill Name: gmail-labeler Version: 0.1.3 The gmail-labeler skill is a Gmail triage and automation tool that uses the gog CLI for email access and the ain CLI for LLM-based classification. While the code is well-structured and its behavior is aligned with the stated purpose, it possesses several high-risk capabilities, including reading private email content, sending email snippets to external LLM providers (e.g., Amazon Bedrock, Alibaba), and executing shell commands via subprocess. The skill also handles sensitive credentials by fetching them from Doppler and contains hardcoded paths (e.g., /home/ubuntu/.openclaw/ in gmail_labeler_runner.py and gmail_labeler_run.sh) that assume a specific environment. Although no evidence of intentional malice was found, the broad access to private communications and the use of external AI services for processing that data warrant a suspicious classification.

能力评估

⚠ Purpose & Capability

The skill claims to be a Gmail triage/labeler using 'gog' and an optional lightweight LLM review. That general purpose matches the included Python runner and filters. However, the skill fails to declare several capabilities it actually relies on: the launcher fetches GOG_KEYRING_PASSWORD via the 'doppler' CLI and the default config references an account environment variable (GOG_ACCOUNT). Those are necessary for Gmail access but are not listed under required binaries or required env vars.

⚠ Instruction Scope

SKILL.md and the scripts largely stay within expected scope (classify, label, log, keep private overlays outside the repo). But the provided launcher script explicitly calls 'doppler secrets get' to fetch GOG_KEYRING_PASSWORD and then runs the Python runner. SKILL.md does not document or declare Doppler usage or the env var names the runner will read. The runner also writes logs outside the skill tree and expects a local overlay config path — those behaviors are reasonable for this tool but increase the environment/secret surface and should be declared.

ℹ Install Mechanism

The install spec pulls an npm package (@felipematos/ain-cli) to provide an 'ain' binary for structured LLM review. Using an npm package for an optional review helper is plausible. This is a moderate-risk install mechanism (npm packages are not pre-reviewed by the platform), but the package source is an identifiable npm name rather than an arbitrary download URL. The skill does not declare Node or npm as required binaries, which is an omission.

⚠ Credentials

The published metadata lists no required env vars or credentials, yet: 1) default-config.json sets accountEnv: 'GOG_ACCOUNT' (so the runner expects an env var for account selection), 2) the launcher uses 'doppler secrets get GOG_KEYRING_PASSWORD' to retrieve a keyring password, and 3) the LLM review section names providers/models (including cloud models) but does not declare any provider API keys. The skill therefore requests or depends on secrets and tooling that are not declared, which is disproportionate and a security concern.

✓ Persistence & Privilege

The skill is not marked always:true and does not request special permanent platform privileges. It writes logs and reads a local overlay (recommended to be outside the skill directory) but does not appear to modify other skills or request global agent configuration changes in the provided files.

版本历史

v0.1.3

Add inbox-by-exception guidance, generic non-actionable fallback strategy, and public label normalization guidance while keeping private editorial rules local.

v0.1.2

Document non-interactive auth/launcher requirements, idempotent processing guidance, thread->message mutation fallback, and clarify that press-release heuristics remain local/private.

v0.1.1

Refine the public release: keep the shared defaults generic, remove PR/press-trip handling from public defaults, preserve the hybrid heuristics + lightweight LLM review flow, multilingual support (EN/PT/ES), decision logging, retention, and local-overlay architecture for private rules and routes.

v0.1.0

Initial public release: hybrid Gmail labeling skill with heuristics-first triage, lightweight LLM review for ambiguous messages, multilingual keyword support (EN/PT/ES), decision logging, 30-day retention, daily self-improvement review loop, PR/press-release handling, and a clean local-overlay pattern for private configuration.

元数据

Slug gmail-labeler

版本 0.1.3

许可证 MIT-0

累计安装 0

当前安装数 0

历史版本数 4

常见问题

gmail-labeler 是什么？

Gmail inbox triage, labeling, and safe archiving with gog plus a configurable lightweight LLM review layer. Use when building or running Gmail automation tha... 它是一个面向 Claude Code / OpenClaw 的 AI Agent Skill 插件，目前累计下载 144 次。

如何安装 gmail-labeler？

在 OpenClaw 或 Claude Code 对话框中运行命令「/install gmail-labeler」即可一键安装，无需额外配置。

gmail-labeler 是免费的吗？

是的，gmail-labeler 完全免费，采用 MIT-0 许可证，可自由下载、安装和使用。

gmail-labeler 支持哪些平台？

gmail-labeler 跨平台运行，可在任意部署了 OpenClaw / Claude Code 的环境中使用（cross-platform）。

谁开发了 gmail-labeler？

由 Felipe Matos（@felipematos）开发并维护，当前版本 v0.1.3。

gmail-labeler