@lacneu/twenty-openclaw

Twenty CRM REST API plugin for OpenClaw. Lets an OpenClaw agent read and (eventually) modify Twenty workspaces — People, Companies, Opportunities, Notes, Tasks — with workspace whitelisting, approval gating on destructive operations, an optional global read-only switch, and a small set of opinionated business helpers (dedup, enrich, bulk import).

Status: P0 + P1 + P2 + P3. The plugin currently ships:

• 1 introspection tool (twenty_workspace_info)
• 9 read tools (list/get on People, Companies, Opportunities, Notes, Tasks)
• 1 cross-record activities tool (twenty_activities_list_for)
• 15 write tools — create/update/delete on the same five entities
• before_tool_call approval hook gating every destructive operation

P4 business helpers (dedup, enrich, bulk import) are not yet shipped — see the Roadmap.

Overview

The plugin talks to the Twenty REST API (/rest/...) using a single API key sent as Authorization: Bearer <key>. It refuses to call any workspace UUID that isn't in allowedWorkspaceIds.

Install

Via OpenClaw CLI (recommended once published)

openclaw plugins install @lacneu/twenty-openclaw

From source (local development)

git clone https://github.com/OlivierNeu/twenty-openclaw-plugin.git
cd twenty-openclaw-plugin
npm install
npm run build
# Then point your OpenClaw instance at the local checkout via
# plugins.entries["twenty-openclaw"].path.

Configuration

Configuration goes under plugins.entries["twenty-openclaw"].config in your openclaw.json. Every string field supports ${ENV_VAR} substitution.

{
  "plugins": {
    "allow": ["twenty-openclaw"],
    "entries": {
      "twenty-openclaw": {
        "config": {
          "enabled": true,
          "apiKey": "${TWENTY_API_KEY}",
          "serverUrl": "https://crm.lacneu.com",
          "allowedWorkspaceIds": ["${TWENTY_WORKSPACE_ID}"],
          "defaultWorkspaceId": "${TWENTY_WORKSPACE_ID}",
          "approvalRequired": [
            "twenty_people_delete",
            "twenty_companies_delete",
            "twenty_opportunities_delete",
            "twenty_notes_delete",
            "twenty_tasks_delete",
            "twenty_dedup_auto_merge",
            "twenty_bulk_import_csv",
            "twenty_bulk_delete",
            "twenty_custom_object_delete",
            "twenty_field_delete"
          ],
          "readOnly": false,
          "logLevel": "info"
        }
      }
    }
  }
}

Tools

Currently shipped

Soft-delete contract. All *_delete tools issue DELETE /rest/<entity>/{id}?soft_delete=true. The Twenty OpenAPI default is HARD delete (soft_delete=false); this plugin overrides that explicitly so records remain in the database with a deletedAt timestamp and are recoverable through the Twenty UI or a future twenty_<entity>_restore tool. Hard-delete is intentionally not exposed in this release.

Planned (P4 — business helpers)

• twenty_enrich — enrich a Person/Company from public data sources.
• twenty_dedup_* — find and merge duplicates.
• twenty_find_similar — semantic search across records.
• twenty_bulk_import_csv / twenty_bulk_delete — bulk operations.
• twenty_<entity>_restore — undo a soft-delete.

Approval gating (before_tool_call)

Every tool name listed in approvalRequired triggers a before_tool_call hook that returns a requireApproval directive to the OpenClaw runtime. The runtime then surfaces the prompt to the operator via the active channel (Telegram inline button, Control UI, ...) and only proceeds when the operator approves. Denied or timed-out calls (10 min default) are rejected without ever reaching Twenty.

Approval prompts include:

• severity: "critical" — the operator's UI flags it appropriately.
• timeoutMs: 600_000 (10 minutes).
• timeoutBehavior: "deny" — silence is refusal.
• A JSON snapshot of the tool parameters (with workspaceId stripped).

The hook is wired automatically when the plugin loads — no extra configuration is required on the host side. To audit or tweak the gated list, override approvalRequired in plugins.entries.twenty-openclaw.config:

openclaw config set 'plugins.entries.twenty-openclaw.config.approvalRequired' \
  '["twenty_people_delete","twenty_companies_delete","twenty_opportunities_delete","twenty_notes_delete","twenty_tasks_delete"]' \
  --strict-json

Pass an empty array to disable approval gating entirely (not recommended).

Note on hook policy flags. OpenClaw 2026.4.x introduced plugins.entries.<id>.hooks.allowConversationAccess — but that toggle only governs llm_input / llm_output / agent_end hooks (raw conversation surfaces). before_tool_call is not in that family, so no manifest-level or config-level toggle is required for this plugin's approval hook.

Examples

Once the plugin is loaded, an OpenClaw agent can simply call:

twenty_workspace_info()

and receive a JSON summary like:

{
  "workspaceUrl": "https://crm.lacneu.com",
  "objectCount": 12,
  "customObjectCount": 2,
  "objects": [
    { "nameSingular": "person", "namePlural": "people", "labelSingular": "Person", "isCustom": false, "isActive": true, "isSystem": false, "fieldCount": 24 },
    { "nameSingular": "company", "namePlural": "companies", "labelSingular": "Company", "isCustom": false, "isActive": true, "isSystem": false, "fieldCount": 18 },
    "..."
  ]
}

Smoke test

cp .env.smoketest .env.smoketest.local   # do not commit local copy
# edit .env.smoketest.local with real values
TWENTY_API_KEY=... TWENTY_SERVER_URL=... TWENTY_WORKSPACE_ID=... npm run smoke-test

The script lives in scripts/smoke-test.mjs and runs one twenty_workspace_info call against the configured server. It exits 0 on success, 1 on tool failure, 2 on missing env vars.

Development

npm install
npm run typecheck
npm test
npm run build

npm test compiles src/** + test/** to dist-test/ and runs node --test. CI matrices node 22 + node 24.

Roadmap

• P0 — repo + license + .gitignore. ✅
• P1 — bootstrap: manifest, package, single read-only tool, smoke script, CI/Release workflows. ✅
• P2 — domain read tools (list/get for the five entities + cross-record activities timeline). ✅
• P3 — write tools (create/update/delete on the five entities) + before_tool_call approval gating on every destructive operation. ✅ (this release)
• P4 — business helpers (enrich, dedup, find_similar, bulk import, restore). 🟡

License

MIT — see LICENSE.