Plugin SDK

OpenClone 向けプラグインを作る

どの言語でも、どのデータソースでも。1つのエンドポイントにPOSTするだけ。プラグインが自動的にVaultに書き込みます——重複排除、サニタイズ、テナント分離はすべて処理済み。

1 endpoint · 15 source types · 500 events/batch · Any language

プラグインレジストリ

公式およびコミュニティプラグイン。インストール、フォーク、または出発点として使用してください。

● Stable

Mac System Audio

macOS

System audio capture via ScreenCaptureKit + Whisper STT. Captures all app audio including meetings.

audio_system openclone-mac-audio
● Stable

Mac Screen OCR

macOS

Screenshots active window every 30s + Apple Vision OCR. Captures everything you read and write.

screen_ocr openclone-mac-screen
Beta

Browser Extension

Chrome/Firefox

Captures browsing history, reading time, and article content. Manifest V3.

web_browsing openclone-browser
● Stable

Microphone

macOS / iOS

Ambient microphone capture via AVFoundation + Whisper STT. Voice notes and conversations.

audio_mic openclone-mac-mic
● Stable

Voice Journal

iOS / macOS

Voice notes from the mobile or desktop app. Transcribed and stored in Journal/.

journal
Planned

Windows Audio

Windows

WASAPI Loopback capture — all app audio.

Planned

Windows Screen

Windows

DXGI capture + WinRT OCR.

Planned

Linux Audio

Linux

PulseAudio/PipeWire monitor source.

Planned

Linux Screen

Linux

X11/Wayland screenshot + Tesseract OCR.

Planned

Health

iOS/Android

HealthKit + Health Connect. Steps, sleep, HR, HRV.

Planned

Calendar

All

EventKit + Google Calendar API.

Planned

Obsidian

All

Filesystem watcher on your Obsidian vault.

Planned

Spotify / Last.fm

All

Last.fm scrobbling — works with any music player.

View all on GitHub → · Want to build one? Read on ↓

APIリファレンス — POST /api/v1/ingest

プラグインが呼び出す唯一のエンドポイント。イベントのバッチを送信し、保存済みとスキップ済みの数を受け取ります。

Request body

POST /api/v1/ingest Content-Type: application/json
{
  "source_type": "audio_system",
  "platform": "macos",
  "device_id": "550e8400-e29b-41d4-a716-446655440000",
  "plugin_id": "openclone-mac-audio",
  "plugin_version": "1.0.0",
  "timestamp": 1708258800.0,
  "events": [
    {
      "timestamp": 1708258800.0,
      "data": {
        "text": "We discussed the product roadmap for Q2.",
        "duration": 60,
        "app_name": "Google Meet",
        "confidence": 0.95
      },
      "raw_ref": "chunk-2026-02-18-14h30-001"
    }
  ]
}

Response (200)

{
  "stored": 3,
  "skipped": 1,
  "file": "Audio/2026-02-26.md"
}

Error codes

401 Invalid or missing X-API-Key
422 Validation error (field details in body)
429 Rate limit exceeded — retry with backoff
500 Storage error — vault write failed

Field reference

Field Type Required Constraints
source_type string yes One of 15 defined types (see below)
platform string yes macos · windows · linux · ios · android · web
device_id string yes UUID v4 — stable across sessions
plugin_id string yes Kebab-case, max 64 chars, alphanumeric + hyphens
plugin_version string yes Semver (1.0.0)
timestamp float yes Unix epoch — not before 2020-01-01, not > +24h
events array yes 1–500 events per request
events[].timestamp float yes Per-event timestamp (same constraints)
events[].data object yes Source-type-specific fields (see Source Types)
events[].raw_ref string no Your unique ID for deduplication — recommended
Auth: Include X-API-Key: your-api-key in every request. Get your key from backend/.env → API_KEY.

プラグインマニフェスト — plugin.json

プラグインのメタデータを宣言します。レジストリ表示と権限チェックに使用されます。

plugin.json
{
  "id": "my-audio-plugin",
  "name": "My Audio Capture",
  "version": "1.0.0",
  "platform": ["macos"],
  "source_types": ["audio_system"],
  "sensitivity": "MEDIUM",
  "requires_permissions": ["screen_recording"],
  "config_schema": {
    "chunk_duration": { "type": "integer", "default": 60 },
    "blocklist": { "type": "array", "default": ["Spotify", "Music"] }
  }
}

Field reference

Field Notes
id Unique kebab-case identifier
name Display name in registry
version Semver string
platform macos · windows · linux · ios · android · web
source_types Which source_types this plugin writes
sensitivity LOW · MEDIUM · HIGH · CRITICAL
requires_permissions Platform permissions needed (optional)
config_schema User-configurable settings with defaults (optional)
Place plugin.json at the root of your plugin directory. The backend reads it at startup and registers your plugin in the registry endpoint (GET /api/v1/plugins).

ソースタイプ

各 source_type はVaultフォルダーと機密レベルにマッピングされます。データに最も近いものを使用してください。

source_type Vault folder Sensitivity Typical data fields
audio_system Audio/ MEDIUM text, duration, app_name, confidence
audio_mic Audio/ HIGH text, duration, confidence
screen_ocr Screen/ MEDIUM text, app_name, window_title, url
journal Journal/ LOW text, duration
web_browsing Web/ MEDIUM url, title, domain, reading_time
music Music/ LOW track, artist, album, duration
health Health/ HIGH steps, heart_rate, sleep_hours
calendar Calendar/ LOW title, start, end, attendees, location
notes Notes/ LOW title, text, tags
gps Location/ MEDIUM lat, lon, accuracy, place_name
photos Photos/ MEDIUM filename, location, timestamp
email Email/ CRITICAL subject, from, to, date (no body)
messaging Messages/ CRITICAL platform, from, preview (local only)
activity Activity/ LOW app_name, duration, category
braindump Braindump/ LOW text
Note on HIGH/CRITICAL types: Always inform users before activating plugins with HIGH or CRITICAL sensitivity. These types capture personal data that users may not want recorded automatically. The backend enforces no technical restriction, but your plugin should default to openclone.enabled: false.

コード例

一般的な言語のすぐに使えるサンプル。URL、キー、データフィールドを置き換えてください。

curl — quickest way to test
curl -X POST http://localhost:8000/api/v1/ingest \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-api-key" \
  -d '{
    "source_type": "braindump", "platform": "macos",
    "device_id": "test-001", "plugin_id": "my-plugin",
    "plugin_version": "1.0.0", "timestamp": 1708258800.0,
    "events": [{"timestamp":1708258800.0,"data":{"text":"Hello!"},"raw_ref":"e1"}]
  }'

# Response: {"stored":1,"skipped":0,"file":"Braindump/2026-02-26.md"}

高度なトピック

重複排除

各イベントはサーバー側で重複排除されます。raw_ref にイベントごとの安定した一意IDを設定してください。バックエンドが source_type + plugin_id + raw_ref をハッシュし、重複を静かにスキップします。

// In your event:
"raw_ref": "chunk-abc123"
// Backend hashes:
source_type + plugin_id + raw_ref
// Duplicate → skipped

レート制限

APIキーごとに60リクエスト/分。バッチあたり最大500イベント。最大1 MB。タイムスタンプは2020-01-01以降かつ未来24時間以内。超過で429——指数バックオフで再試行してください。

60 req / min / key
500 events / batch
1 MB max payload
429 → retry with backoff

バッチイベント

イベントをローカルにバッファリングしてバッチ送信します。1リクエストあたり最大500イベント。同じ日次 .md ファイルに書き込まれます。部分バッチもサポートされています。

// Recommended pattern:
buffer = []
buffer.append(event)
// Every 60s or 100 events:
ingest(buffer[:500])
buffer.clear()
Timestamp rules: Events must have timestamps between 2020-01-01 and now + 24h. Out-of-range timestamps are rejected with a 422. Always use the event's actual capture time, not the send time.

5 minutes to your first memory entry

1

Create plugin.json

Declare your plugin ID, platform, and source type.

"source_type": "braindump"
2

POST your first event

Use the curl example above — one command, 30 seconds.

{"stored": 1}
3

Verify in vault

Open the vault folder. Your .md file is ready.

Braindump/2026-02-26.md

プラグインを公開する

PixxzR/openclone リポジトリにPRを開いて、プラグインを公式レジストリに追加してください。plugin.json、README、インストールスクリプトを含めてください。

PR checklist

  • plugin.json with all required fields
  • README.md with install instructions
  • install.sh (macOS) or setup instructions
  • No hardcoded API keys or personal data
  • Defaults to openclone.enabled: false
  • Source type matches one of the 15 defined types