@lacneu/twenty-openclaw

Twenty CRM plugin for OpenClaw. Lets an OpenClaw agent discover, model and operate any Twenty workspace — read and write the standard entities (People, Companies, Opportunities, Notes, Tasks), create custom objects and fields on the fly via the Metadata API, then CRUD their records — with workspace whitelisting, approval gating on every destructive operation, an optional global read-only switch, and a small set of opinionated business helpers (export, dedup, bulk import, similarity search, relationship summary).

Status: P0 → P8 shipped. 83 tools, end-to-end validated live against crm.lacneu.com (Ataraxis). The plugin currently ships:

• 1 introspection tool (twenty_workspace_info).
• 9 typed read tools (list/get on People, Companies, Opportunities, Notes, Tasks).
• 1 cross-record activities timeline (twenty_activities_list_for).
• 15 typed write tools (create/update/delete on the same five entities).
• 6 business helpers (export, people_find_similar, people_dedup, companies_dedup, bulk_import_csv, summarize_relationship).
• 10 Twenty Metadata API tools (custom-objects + fields lifecycle).
• 5 generic record-dispatch tools that work on any entity, standard or custom (record_list/get/create/update/delete).
• 12 dashboard tools — build, modify, and inspect dashboards (PageLayouts + tabs + widgets + chart-data) directly from the chat.
• 25 workflow tools — design, version, activate, run, and report on workflows (4 trigger types, 17 action types, runs + logic functions) directly from the chat.
• before_tool_call approval hook gating 24 destructive ops by default, with per-tool context warnings on the 5 high-risk workflow ops.

Overview

The plugin talks to the Twenty REST API (/rest/...) and the Twenty Metadata REST API (/rest/metadata/...) 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_metadata_object_create",
            "twenty_metadata_object_update",
            "twenty_metadata_object_delete",
            "twenty_metadata_field_create",
            "twenty_metadata_field_update",
            "twenty_metadata_field_delete",
            "twenty_record_delete",
            "twenty_dashboard_delete",
            "twenty_dashboard_tab_delete",
            "twenty_dashboard_widget_delete",
            "twenty_dashboard_replace_layout",
            "twenty_workflow_delete",
            "twenty_workflow_version_activate",
            "twenty_workflow_version_deactivate",
            "twenty_workflow_version_delete",
            "twenty_workflow_run"
          ],
          "allowedImportPaths": [
            "/home/node/.openclaw/",
            "/tmp/"
          ],
          "readOnly": false,
          "logLevel": "info"
        }
      }
    }
  }
}

Tools

Introspection (1)

Typed read (9 + 1 timeline)

Filter syntax follows the Twenty REST conventions, e.g. name[ilike]:%acme%, domainName.primaryLinkUrl[ilike]:%acme.com%, employees[gte]:50, createdAt[gte]:2026-01-01.

Typed write (15)

Soft-delete contract. The 5 typed *_delete tools issue DELETE /rest/<entity>/{id}?soft_delete=true. Records remain in the database with a deletedAt timestamp and stay restorable through the Twenty UI. Hard-delete on entity records is intentionally not exposed.

Note — restore endpoint not exposed. Twenty 2.1 declares PATCH /rest/restore/<entity>/{id} in OpenAPI but the server returns 400 BadRequest at runtime, and the GraphQL alternative (restorePerson mutation) returns RECORD_NOT_FOUND. The factory pattern remains in git history at tag v0.2.0 and will be re-added once Twenty fixes the upstream bug. In the meantime, restore through the Twenty UI.

Business helpers (6)

Twenty Metadata API (10)

These tools call /rest/metadata/objects and /rest/metadata/fields and let the agent shape the workspace itself without leaving the chat.

Synchronous schema regeneration. After metadata_object_create, the new /rest/<plural> endpoint is available within ~50 ms. The plugin does not poll — the very next record_create call against the new entity succeeds.

Generic record dispatch (5)

CRUD on any entity (standard or custom) parameterised by entity name. Composes naturally with the Metadata tools: agent creates a custom object via P5 → populates records via P6, no plugin redeploy needed.

The entity name is regex-validated pre-network (^[a-zA-Z][a-zA-Z0-9]*$) to reject path-traversal attempts (people/../../etc/passwd → rejected before any HTTP call is made).

Dashboards (12 tools)

Build, modify, and inspect Twenty dashboards from the chat. Mirrors the exact LLM contract Twenty's own internal AI agent uses (port of twenty-server/src/modules/dashboard/tools/), so the agent gets a proven authoring surface — without needing the agent to learn Twenty's internals.

A Twenty dashboard is the union of a dashboards workspace record (with title, pageLayoutId, position) and a PageLayout of type=DASHBOARD (containing tabs, themselves containing widgets on a 12-column grid). These tools coordinate both layers transparently.

Dashboard-level (5)

Tab-level (3)

Widget-level (4)

Grid system

12 columns (0-11). Typical sizes: KPI rowSpan 2-4, charts 6-8. Full width = columnSpan: 12, half = 6, third = 4, quarter = 3.

Configuration recipes (excerpt)

Aggregations available: COUNT, COUNT_UNIQUE_VALUES, COUNT_EMPTY, COUNT_NOT_EMPTY, COUNT_TRUE, COUNT_FALSE, SUM, AVG, MIN, MAX, PERCENTAGE_EMPTY, PERCENTAGE_NOT_EMPTY.

Date granularities for time-bucketed charts: DAY, WEEK, MONTH, QUARTER, YEAR, DAY_OF_THE_WEEK, MONTH_OF_THE_YEAR, QUARTER_OF_THE_YEAR.

Approval gating philosophy

Only irreversible destructions are gated by default: dashboard_delete, dashboard_replace_layout, tab_delete, widget_delete. Construction tools (*_add, *_update, create_complete, duplicate) are not gated — the LLM iterates during build (add → check → tweak), and approval prompts on every step would cripple the flow.

Required permission

The Twenty API key must hold the LAYOUTS permission flag. Workspace- admin keys inherit it automatically; restricted keys require an admin to grant it explicitly through Twenty's role configuration.

Workflows (25 tools)

Design, version, activate, run, and report on Twenty workflows — the full lifecycle from chat. Mirrors Twenty's internal workflow LLM tooling (twenty-server/src/modules/workflow/workflow-tools/tools/).

A Twenty workflow is the union of 4 entities:

Workflow (record, REST /rest/workflows)
   ├─ versions[]  ─→ WorkflowVersion (DRAFT/ACTIVE/DEACTIVATED/ARCHIVED)
   │                   ├─ trigger (JSON: DATABASE_EVENT|MANUAL|CRON|WEBHOOK)
   │                   └─ steps[]  ─→ WorkflowAction (17 types)
   │                                   id, name, type, valid, settings, position
   ├─ runs[]      ─→ WorkflowRun (each execution: status + state.stepInfos)
   └─ automatedTriggers[]

Workflow-level (5)

Version-level (6)

Step + edge-level (9)

None gated by default. The LLM iterates rapidly during build (add → check → tweak); approval prompts on every step would cripple the flow.

Run-level (4)

Logic functions (3)

For CODE workflow steps. Live on /metadata.

Trigger types and configurations

Action types — the 17 step types

Record CRUD: CREATE_RECORD, UPDATE_RECORD, UPSERT_RECORD, DELETE_RECORD, FIND_RECORDS. Email: SEND_EMAIL, DRAFT_EMAIL. Logic: IF_ELSE, FILTER, ITERATOR. AI: AI_AGENT. External: HTTP_REQUEST. Code: CODE (TS function), LOGIC_FUNCTION (alias). UX: FORM, DELAY, EMPTY. The workflow-schemas.ts file ports each action's settings shape directly from twenty-shared/workflow/ schemas/ so the LLM sees the canonical contract.

Variable references between steps

{{trigger.object.fieldName}}       — DATABASE_EVENT triggered record
{{trigger.record.fieldName}}       — MANUAL with single-record availability
{{trigger.body.fieldName}}         — WEBHOOK POST body
{{<step-uuid>.result.fieldName}}   — earlier step's output (UUID, not name)

Discover step ids via twenty_workflow_get. Pre-compute output schemas via twenty_workflow_compute_step_output_schema before referencing.

Required permission

The Twenty API key must be linked to a user who has the WORKFLOWS permission flag. Settings Twenty → Members & Roles → Roles → [your role, typically Admin] → check Workflows. Without it, Twenty returns Forbidden resource (FORBIDDEN) on action mutations (run/activate/deactivate/stop/createDraft/duplicate, plus the step + edge mutations). Standard CRUD on workflow records (list, get, create_complete, delete, runs_list, run_get) only requires entity- level read/write.

Use case — campaigns

Concretely, an agent can build campaign workflows like:

Trigger MANUAL (with BULK_RECORDS availability on Company)
  → step FIND_RECORDS on Company filtered by tag/label
  → step ITERATOR on the result
    → SEND_EMAIL inside the iterator
    → CREATE_RECORD (Note linked to the company) for tracking

twenty_workflow_create_complete writes all this in one cascade. The operator activates with twenty_workflow_version_activate, then launches with twenty_workflow_run (both approval-gated). After execution, twenty_workflow_run_get returns the run's stepStatusCounts and per-step errors so the agent can write a report.

Custom data modelling workflow (live demo)

End-to-end flow exercised against the Ataraxis 2CF workspace:

1. Agent: "I need to track ICOPE diagnostics for our patients"
2. metadata_object_create  →  Diagnostic ICOPE  (icopeDiagnostics)
   • Approval prompt → operator approves
3. metadata_field_create   →  dateEvaluation     (DATE)
4. metadata_field_create   →  scoreCognitif      (NUMBER)
5. metadata_field_create   →  scoreMobilite      (NUMBER)
6. metadata_field_create   →  person             (RELATION many_to_one → Person)
   • Twenty auto-creates the inverse field `diagnosticsIcope` on Person
7. record_create           →  first ICOPE diagnostic for John Doe
   • Operator: "approval — yes, this is the format I want"
8. record_list             →  back-reference works through the inverse field
9. record_update           →  fix a wrong score
10. record_delete (gated)  →  soft-delete the demo record

Every destructive step (metadata_*_create, *_update, *_delete, record_delete) prompts the operator through the active OpenClaw channel before any HTTP call.

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_metadata_object_delete","twenty_record_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 — typed write tools (create/update/delete on the five entities)
  • before_tool_call approval gating on every destructive operation. ✅
• P4 — business helpers: export, people_find_similar, people_dedup, companies_dedup, bulk_import_csv, summarize_relationship. ✅ (restore + enrich dropped from scope — see CHANGELOG 0.3.0.)
• P5 — Twenty Metadata API: 10 tools to create / update / delete custom objects and fields. ✅
• P6 — Generic record dispatch: 5 tools to CRUD any entity (standard or custom). ✅
• P7 — Dashboards: 12 tools to build / modify / inspect dashboards (PageLayout + tabs + widgets + chart-data). ✅ (approval gates only irreversible destructions; construction stays friction-free)
• P8 — Workflows: 25 tools (5 workflow + 6 version + 9 step/edge + 4 run + 3 logic-function). Design / activate / run / report end-to- end. Approval gates only irreversible destructions + production- impact ops (activate / deactivate / run). ✅

Future

• twenty_<entity>_restore once Twenty fixes the upstream REST/GraphQL restore bug.
• twenty_enrich_company once a concrete data provider is selected (free-tier limits + GDPR for cabinet conseil to validate).
• Real OpenClaw OTEL tracing through the runtime tracer (waiting on SDK exposure).

License

MIT — see LICENSE.