Give your OpenClaw agent its own Inkbox identity:
a mailbox, iMessage, a phone number for calls and SMS, voice, contacts, notes, and an internet address.
Keep OpenClaw reachable from anywhere without forking OpenClaw.
Email · Calls · SMS / MMS · iMessage · Contacts · Notes
Status: outbound tools, read tools, bundled skills, setup wizard, doctor checks, SMS/MMS batching, 1:1 and group text conversations, inbound email/SMS/iMessage/voice, realtime phone calls, post-call actions, and package-included skills are implemented. ClawHub publishing is still pending.
- An installed OpenClaw agent,
2026.5.19or newer. Start at openclaw.ai or follow the OpenClaw install docs. - The recommended OpenClaw installer for macOS, Linux, or WSL2:
curl -fsSL https://openclaw.ai/install.sh | bash
openclaw --versionThen onboard OpenClaw and configure a model provider. We recommend using either an OpenAI API key or a ChatGPT/Codex subscription:
openclaw onboard
openclaw configureIf you already manage Node yourself, the OpenClaw docs also support installing the CLI with npm before running the same onboard/configure commands:
npm install -g openclaw@latest- An Inkbox account or API key.
openclaw inkbox setupcan guide a new agent identity through signup/setup.
Run these from the plugin checkout after the OpenClaw prerequisite above is installed:
git clone https://github.com/inkbox-ai/openclaw-plugin.git
cd openclaw-plugin
npm install
npm run build
openclaw --version
openclaw plugins install -l --force --accept-capabilities ./Configure Inkbox:
openclaw inkbox setup
openclaw inkbox doctorThe setup wizard writes channels.inkbox into the active OpenClaw profile and adds the Inkbox tool group to the profile's tool policy.
An agent can complete setup after a human assigns an existing identity handle, API base URL, and credential. Use the local plugin installation flow above, but inspect the checkout before installing it into OpenClaw:
- Confirm the clone's remote, current revision, and clean working tree.
- Review
package.json, its scripts, and the declared and locked dependencies before runningnpm install. - Run
npm installandnpm run build, review the installed dependency summary and build output, and check the working tree for unexpected changes. - Only then run the local
openclaw plugins install -l --force --accept-capabilities ./command.
First inspect the checkout and manifest. Also review package-lock.json before continuing:
git remote get-url origin
git log -1 --oneline
git status --short --branch
npm pkg get scripts dependencies devDependencies peerDependenciesAfter that review, install the dependencies and build. Inspect the dependency summary, build output, and working tree before continuing:
npm install
npm ls --depth=0
npm run build
git status --shortOnly install the reviewed local build into OpenClaw when those checks have the expected results:
openclaw plugins install -l --force --accept-capabilities ./Keep the credential out of source control, project instructions, command arguments, and transcripts. Place it in the private process environment as INKBOX_API_KEY; if entering it in a terminal, read it without echoing:
read -rsp 'Inkbox API key: ' INKBOX_API_KEY && printf '\n'
export INKBOX_API_KEY
openclaw inkbox bootstrap --identity '<handle>' --base-url '<url>' \
--voice-ai --rotate-signing-key --start-gateway
unset INKBOX_API_KEYbootstrap is non-interactive. It validates and preserves the exact assigned identity, scopes down an admin key before saving it, preserves existing Voice AI settings, updates the active OpenClaw profile, and starts, restarts, or installs the gateway service. When it starts the gateway, it disables the optional startup agent prewarm so bootstrap can finish safely from inside a live OpenClaw session; the first real inbound turn may pay the one-time cold-start cost. Signing-key replacement is explicit because it transfers verified webhook delivery away from gateways using the previous key.
The command prints secret-redacted JSON and is safe to resume:
- For
"status": "configured", runopenclaw inkbox doctorand confirm the configured identity and live connection are healthy. - For
"status": "requires_human", show the human each requested entry inhumanActions. After the human completes those actions, restoreINKBOX_API_KEYprivately and rerun the same bootstrap command with the same assigned handle; do not create or select a different identity. - For
"status": "error", inspect the redactederrorand completedactions, diagnose the credential, assigned handle, base URL, local config, or gateway state as indicated, and correct that cause. Then restoreINKBOX_API_KEYprivately and rerun the same bootstrap command with the same assigned handle.openclaw inkbox doctorand, for gateway errors,openclaw gateway statusprovide focused diagnostics.
Always unset the transient INKBOX_API_KEY after each attempt. Bootstrap saves the resulting agent-scoped credential in the active OpenClaw profile; never copy credentials into this checkout or any other project file.
This is a manual testing-only playground; it is not published and is not an automated CI or release artifact. The included image preinstalls OpenClaw and builds this checkout. It contains no credentials:
docker build -t inkbox-openclaw-plugin .
docker run -d --name inkbox-openclaw \
-e OPENAI_API_KEY="$OPENAI_API_KEY" \
inkbox-openclaw-plugin
docker exec -it inkbox-openclaw bashInside the container, install the already-built local plugin and run setup:
openclaw plugins install -l --force --accept-capabilities /opt/inkbox-plugin-src
openclaw inkbox setup
openclaw inkbox doctor
openclaw gateway runOpenClaw requires the explicit install acknowledgment because the plugin's gateway setup helper invokes the OpenClaw CLI to start, restart, or install the gateway service.
Start the gateway:
openclaw gateway runKeep that process running. On startup the plugin opens an Inkbox tunnel, configures mail/text/iMessage webhook subscriptions and the incoming-call URL, and routes inbound email, SMS, iMessage, and calls into OpenClaw sessions.
Restart the gateway after changing Inkbox config, updating the plugin, or re-running setup:
openclaw gateway restartIf you started the gateway in the foreground with openclaw gateway run, press Ctrl+C in that terminal and start it again:
openclaw gateway runopenclaw inkbox setup walks the current OpenClaw profile through Inkbox configuration:
- Authenticates to Inkbox or uses the API key already present in config.
- Resolves or creates the Inkbox agent identity for this OpenClaw agent.
- Stores an agent-scoped API key, the identity handle, and webhook signing key in
channels.inkbox. - Offers to enable iMessage for the agent, then optionally provisions a local SMS + voice phone number.
- Shows a native Phone call voice stack selector with Inkbox Voice AI, OpenAI Realtime API, and Inkbox TTS/STT.
- For Voice AI, configures contact-scoped or YOLO authority using an admin-scoped key only when authority must change; the admin credential is never persisted. For Realtime, validates the OpenAI API key and returns to the three choices if validation fails.
- Points mailbox, text, iMessage, and
call.endedevents at separate canonical subscriptions. Local voice stacks useauto_acceptwith the gateway media WebSocket; Voice AI useshosted_agent. - Prints the final mailbox/phone summary.
If setup provisions a new local phone number, it waits for any inbound SMS START to that number before finishing. It also seeds ~/.openclaw/inkbox/identity-state.json so openclaw inkbox doctor can show useful channel state.
Inkbox reachability is controlled server-side with mailbox and phone contact rules in the Inkbox Console. The plugin does not create a second local inbound allowlist unless you explicitly set allowedInboundContactIds.
Preferred config shape:
{
"channels": {
"inkbox": {
"apiKey": "ApiKey_xxxxxxxxxxxx",
"identity": "my-agent-handle",
"signingKey": "whsec_xxxxxxxxxxxx",
"voiceStack": "inkbox_voice_ai",
"voiceAiAuthorityMode": "contact_scoped",
"voicemailDetection": "enabled"
}
},
"tools": {
"allow": ["inkbox"]
}
}Equivalent config commands:
openclaw config set channels.inkbox.enabled true --strict-json
openclaw config set channels.inkbox.apiKey "ApiKey_xxxxxxxxxxxx"
openclaw config set channels.inkbox.identity "my-agent-handle"
openclaw config set channels.inkbox.signingKey "whsec_xxxxxxxxxxxx"
openclaw config set tools.allow '["inkbox"]' --strict-json
openclaw config validateEnv vars are also supported by the plugin and CLI:
export INKBOX_API_KEY="ApiKey_xxxxxxxxxxxx"
export INKBOX_IDENTITY="my-agent-handle"
export INKBOX_SIGNING_KEY="whsec_xxxxxxxxxxxx"
export INKBOX_BASE_URL="https://your-inkbox-api.example"Legacy plugin-scoped config under plugins.entries.inkbox.config still works, but new installs should use channels.inkbox.
"inkbox" in tools.allow enables the required tools. Optional tools must be listed by name.
Common full-access smoke allowlist, excluding vault plaintext tools:
openclaw config set tools.allow '[
"inkbox",
"inkbox_forward_email",
"inkbox_place_call",
"inkbox_mark_emails_read",
"inkbox_list_texts",
"inkbox_get_text",
"inkbox_mark_text_read",
"inkbox_mark_text_conversation_read",
"inkbox_imessage_triage_number",
"inkbox_list_imessage_assignments",
"inkbox_send_imessage_reaction",
"inkbox_mark_imessage_conversation_read",
"inkbox_update_note",
"inkbox_delete_note",
"inkbox_list_mail_contact_rules",
"inkbox_list_phone_contact_rules",
"inkbox_list_note_access",
"inkbox_grant_note_access",
"inkbox_revoke_note_access",
"inkbox_whoami"
]' --strict-jsonAdd vault tools only when the identity has vault access and the gateway environment has the vault unlock key:
export INKBOX_OPENCLAW_VAULT_KEY="..."
openclaw config set tools.allow '[
"inkbox",
"inkbox_credentials_list",
"inkbox_credentials_get_login",
"inkbox_credentials_get_api_key",
"inkbox_credentials_get_ssh_key",
"inkbox_totp_code"
]' --strict-jsonopenclaw inkbox setup offers three explicit choices:
- Inkbox Voice AI handles calls on behalf of the agent. OpenClaw receives the final transcript and open post-call actions after hangup. Outbound calls use
mode=hosted_agent, include a taskreason, and intentionally omit a per-call authority override so the saved Voice AI default applies. - OpenAI Realtime API uses your validated OpenAI API key. The realtime voice agent can consult OpenClaw for complex work.
- Inkbox TTS/STT keeps the OpenClaw agent in the spoken loop through Inkbox speech services, with increased latency.
Plain-text output from a Voice AI post-call turn is suppressed because the call has ended; requested side effects run through normal tools. Completion receipts are durable and unfinished calls are replayed after gateway restart.
Use the native OpenClaw runner for hosted-call settlement, A2A progress, and silent cross-channel completion. These features depend on the host's before_agent_run and model-call lifecycle hooks; Codex and other external runners do not emit the same lifecycle. Recent OpenClaw versions default official OpenAI models to the Codex runner, so select the native runner explicitly for your chosen model, for example:
openclaw config set 'agents.defaults.models["openai/gpt-5.6-sol"].agentRuntime.id' openclawUse your configured model key in place of the example. Inkbox setup does not change your model or override an explicitly chosen runner. This setting concerns the main agent, not the separate realtime voice provider.
Setup also enables OpenClaw's plugins.entries.inkbox.hooks.allowConversationAccess permission. The plugin needs this host permission to bind channel sends and Voice AI completions to their exact runs before accepting side-effecting tool evidence, and to associate A2A progress with its worker run. Conversation bodies are not stored in the completion registry or replay journal.
For manual configuration, explicitly set plugins.entries.inkbox.hooks.allowConversationAccess: true to enable those lifecycle hooks, native approval routing, and confirmation that background group context was consumed. Without that permission, unconfirmed background context remains retained and may appear in later turns; the plugin does not enable the permission automatically outside setup.
Calls can use raw Inkbox call media through OpenAI Realtime. The call transport negotiates HD voice as mono 16 kHz PCM16LE, resampled continuously to and from the realtime provider’s 24 kHz PCM format. Older call endpoints remain compatible with 8 kHz μ-law audio. OpenAI GA Realtime requires an OpenAI API key; ChatGPT/Codex subscription OAuth profiles are not used for this path. During openclaw inkbox setup, the wizard looks for an existing OpenAI API key in channels.inkbox.voiceRealtime.providers.openai.apiKey, INKBOX_REALTIME_API_KEY, an OpenClaw openai API-key auth profile, or OPENAI_API_KEY. Environment keys are setup-time discovery inputs unless the wizard validates and persists them into channels.inkbox.voiceRealtime.providers.openai.apiKey. If it finds one, it asks whether to enable Realtime calls, validates access to gpt-realtime-2, and stores the validated key in the Inkbox Realtime provider config. If no key is found, it prompts for one and validates it before enabling Realtime.
export INKBOX_REALTIME_API_KEY="sk-..."
openclaw configure
openclaw inkbox setup
openclaw gateway runRealtime calls receive the agent's Inkbox handle, mailbox, phone number, caller contact metadata, and outbound-call purpose before greeting. The realtime voice model can call openclaw_agent_consult, inkbox_register_post_call_action, inkbox_edit_post_call_action, inkbox_delete_post_call_action, and inkbox_hang_up_call. If validation fails during setup, the wizard returns to the three voice-stack choices. An explicitly configured openai_realtime stack does not silently fall back to another stack at runtime.
Optional realtime overrides:
openclaw config set channels.inkbox.voiceRealtime.provider openai
openclaw config set channels.inkbox.voiceRealtime.model gpt-realtime-2
openclaw config set channels.inkbox.voiceRealtime.voice cedarDisable realtime:
openclaw config set channels.inkbox.voiceRealtime.enabled false --strict-jsonCalls — inbound and outbound — can run over either of two lines, and the agent picks the one that matches the channel it's talking on:
- The dedicated phone number. The agent's own number (the same line SMS uses). Outbound calls present this number; inbound calls to it ring the agent.
- The shared Inkbox iMessage line. The agent can also place and receive voice calls with a person it's connected to over iMessage, over the same shared line that person already messages. The underlying number is never surfaced — Inkbox resolves it from the iMessage connection — and it only works for people already connected over iMessage (an unknown caller is rejected; an outbound call with no connection is refused).
Inbound answering is configured once per identity (hosted_agent for Inkbox Voice AI, otherwise auto_accept to open the call bridge WebSocket), so a single setting governs both lines. Outbound, the agent sets origination on inkbox_place_call (dedicated_number / shared_imessage_number), or omits it — the plugin then uses whichever line is the only one available, or the line matching the conversation's channel when both are.
iMessage works differently from SMS: the agent does not get its own iMessage number. People connect to the agent through the Inkbox iMessage router, and each connected person gets a dedicated thread with the agent.
- Enable iMessage for the agent during
openclaw inkbox setup(or later by re-running it). Enablement is stored on the Inkbox identity, not in local config. - From an iPhone, text the connect command (for example
connect @my-agent-handle) to the Inkbox iMessage router number. The wizard prints both, and the agent can also share them via theinkbox_imessage_triage_numbertool. - Inkbox texts back from the number assigned to that conversation. Send any first message there — the agent can only reply after you message it first (recipient-first; there is no cold outreach over iMessage).
- The setup wizard waits for that first message and replies with a welcome confirming the channel. From then on, the gateway routes the thread into the same contact-keyed OpenClaw session as email/SMS/voice, and the agent replies over iMessage in that thread.
If a person disconnects the agent, outbound sends to that conversation fail until they reconnect through the router and message the agent again. Conversation rows expose assignmentStatus (active/released) so the agent can see this, and inkbox_list_imessage_assignments lists who is currently connected. Outbound delivery transitions (imessage.sent, imessage.delivered, imessage.delivery_failed) arrive as webhooks and are logged by the gateway without waking the agent, matching the SMS lifecycle handling.
While the agent composes a reply, the recipient sees a typing indicator — the gateway pulses it until the response sends. In automatic group mode and direct conversations, a question tapback is treated as a request for clarification. Other tapbacks are ambient events: normally nothing is sent; if a response is warranted, the agent sends it explicitly into the same conversation. In group mention mode, unmentioned reactions remain background context without waking the agent.
Once someone is connected over iMessage, the agent can also place and receive voice calls with them over that same shared line — see Two calling lines. This works even for an agent that has no dedicated phone number.
Set channels.inkbox.imessageThreadedReplies: true or INKBOX_IMESSAGE_THREADED_REPLIES=1 and restart the gateway. The default is off. Source-triggered answers use that incoming message as replyToMessageId, with the API's plainReplyFallback: true; the plugin never issues a second plain send. Explicit reply tools cannot override the source or fallback. Deliberately sending to another recipient or conversation is a separate effect: it inherits no reply target and does not count as delivery of the current answer. Proactive/cron messages also have no inherited reply target.
The durable receiver acknowledges incoming messages only after saving them. Same-sender, same-conversation, same-native-thread text bursts wait 750 ms of quiet (at most 2 seconds), cap at eight sources/4,000 characters, require identical parent/thread/root ancestry, and answer the first source. Queue ownership and uncertainty fencing remain conversation-wide across those native threads. Media, reactions, controls, and Companion snapshots stay separate. Follow-ups wait for the current native dispatch, without interrupting it; OpenClaw still owns model execution, sessions, approvals, and configured scheduling. Voice sessions remain separate.
Use inkbox_get_imessage_thread with a message ID or inkbox_get_imessage_conversation_thread with a conversation and opaque thread ID; follow nextCursor. Delivery-failure callbacks, including callbacks arriving before the send result or unmatched proactive failures, are context only in this mode—not instructions to resend.
Before either an explicit or automatic targeted send, the plugin rechecks the source message and reads one native-thread item to verify backend support and conversation ownership. This probe is not added to model history. Unsupported or unverifiable targets fail before recording send intent; there is no untargeted retry.
An authorized /stop or /cancel silently cancels this sender's already-admitted work in the same iMessage conversation, including queued follow-ups. The active exact native run must terminate before later input proceeds; other conversations and voice consultations are unaffected. The Stop receipt survives restart, so replaying it cannot cancel work received afterward. If a send has already started, its accepted or uncertain outcome is retained; any remaining unsent reply blocks are stopped.
Run openclaw inkbox setup and explicitly enable Slack. Setup can reuse a saved workspace or accept masked app-configuration credentials, prepare the identity's app asynchronously, hand off browser installation, and observe its connected state. The plugin does not retain the token pair or provision apps in the background. Preparation and installation waits are separately bounded/cancellable; an unknown app-creation outcome is never blindly retried. Alternatively connect the identity in the Inkbox Console first and set channels.inkbox.slackEnabled: true or INKBOX_SLACK_ENABLED=1, then restart.
The same signed receiver handles Slack. Subscription reconciliation adds missing events to the current active URL without deleting unrelated events or receivers. skipWebhookReconcile remains supported. Disabling Slack gates events, recovered jobs, automatic replies, and its eight tools:
inkbox_slack_list_connections,inkbox_slack_list_conversations,inkbox_slack_list_messagesinkbox_slack_search,inkbox_slack_send_message,inkbox_slack_get_actioninkbox_slack_upload_file,inkbox_slack_get_operation
Search covers retained text, not arbitrary workspace files. Follow a returned cursor even after an empty page. Explicit sends require a stable idempotency key; inspect pending/unknown actions with get_action rather than repeating a send. Native channel targets use slack:<connection UUID>:<Slack conversation ID>, with a separate optional native thread timestamp.
Ordinary DMs stay inline and mentions in channels can start native threads. Unaddressed ordinary channel messages do not start work in an unengaged thread; eligible follow-ups in an already engaged thread retain Auto/Mention policy. Companion history/session scope spans the channel, while each current message owns its exact connection, channel, actor, and null-or-native-thread reply destination. Safe/Relaxed admission and Auto/Mention wake policy remain independent. Quiet context is durable and does not start a model, tool, or indicator. A mention can wake Companion without forcing a reply when the native room-event policy permits silence.
Slack turns receive Slack-specific formatting instructions, and ordinary Markdown links/bold are repaired outside code blocks. Local files (1 byte–10 MiB) can be uploaded with inkbox_slack_upload_file; local media returned by the host is also uploaded to the original reply thread. Within one source turn, identical bytes to the same destination reuse the first upload receipt even if later filename/caption metadata differs. A local path or Markdown image is not a delivered file. Only a confirmed successful upload is delivery proof; unknown outcomes remain recorded and must not be blindly resent.
Native tool activity appears in one source-owned progress surface, separate from approvals and final answers. SDK 0.7.16 or newer can use native task streams when supported by the workspace and the original thread/recipient context. The published 0.7.15 baseline uses one ordinary status message edited in place. Scope presence alone does not prove native support; an uncertain native write never causes a second fallback message. Automatic reconciliation is bounded, and definitive unknown outcomes remain inspectable without repeated provider reads. Pending operation keys and confirmed stream IDs survive restart; unresolved old-SDK edits remain fenced when read-only lookup is unavailable. Progress journals require a local hard-link-capable filesystem; do not share the same plugin state directory between containers with separate PID namespaces. Shutdown pauses a card without claiming a confirmed Stop; restart reconciles the original durable job before updating it.
Working indicators follow the outgoing destination: inline replies use eyes on the source; native subthreads use Slack processing/suspended/active state and never reaction fallbacks. Approval waits suspend the native thread. Overlapping work is aggregated, bounded status retries do not affect delivery, and shutdown/restart cleanup retains unresolved operations.
Native Stop and slash controls require the active sender and exact current thread, not an earlier activation sponsor. Native Stop and addressed textual Stop retain the exact current source across awaited reads and restart; an old uncertain send cannot capture Stop for newer work. Legacy pending Stop controls without a recorded target become no-op receipts instead of targeting another turn. Stop can also cancel a saved answer before its send checkpoint; a send already in progress retains its accepted or uncertain outcome. Historical messages and display names never grant authority. Canonical authors use the sender's verified home-workspace/user pair. Local Slack person allowlists may also use an installation-workspace/user pair, but only in that verified installation; bare user IDs are not supported. Proactive local outbound allowlists use slack:<connection UUID>:<conversation ID>.
Existing Companion journals remain readable. New records add optional source ownership, burst receipts, tool-send intents, and exact native run IDs; no existing receipt is discarded. Completed answers are saved before sending. Accepted/uncertain external sends and uncertain model submissions are never replayed automatically. Later work may progress once the old native run is positively terminal; restart recovery can request cancellation of that exact run and requires terminal evidence before releasing it. Legacy ambiguous jobs without provable ownership remain paused for inspection. Do not delete the journal to retry, or downgrade while unresolved new-format work remains. Disabling/re-enabling a feature preserves its receipts.
Completed ordinary Slack and native iMessage records move into an indexed local receipt archive so the active journal does not rewrite all historical payloads on each message. Replay proof and accepted delivery IDs are retained without expiry; this bounds historical work on the active path, not total disk usage. Pending, saved, active, and uncertain work stays in the journal. Approval prompts have separate request-owned send receipts: an uncertain prompt remains visible for inspection but does not suppress a later model answer or authorize replay of the prompt. Migration is resumable and writes durable receipts and indexes before removing a completed hot record. Back up and restore the journal and its adjacent .receipts directory together. After migration, do not downgrade to a version without archive readers: an older version cannot recognize archived replay proof.
Native iMessage delivery outcomes also retain metadata in account/environment/identity-scoped imessage-outcomes-* directories. Back these up with the journal and receipt archive. A failure callback cannot replace an accepted send's original route or erase its nullable native ancestry; callbacks that arrive before acceptance retain their failed status until the original route becomes known. Notices stay context-only and never wake a retry or authorize an unthreaded resend. Unmatched proactive failures use their conversation only as a quiet fallback. Per-output records and pending-notice indexes avoid rewriting the full history; total disk use is not bounded, and permanent exactly-once notice delivery is not promised. Optional outcome-storage failure does not turn an accepted send into a rejection. Existing hot/archive delivery receipts can repair route correlation when available; an older reader does not understand this additional metadata.
openclaw doctor reports Slack connection/subscription readiness, disabled or unavailable native iMessage capability, and content-free durable queue counts. Pending inputs, saved answers, active runs, unconfirmed outcomes, pending Stop fences, and disabled retained work are distinct. SDK/API reachability and queue readiness do not prove a visible Slack indicator or delivery to an iMessage device.
Metadata listing requires no unlock. The plugin now defaults to INKBOX_OPENCLAW_VAULT_KEY; vault.keyEnvVar still supports a custom variable. Move an existing SDK-wide INKBOX_VAULT_KEY to the plugin-specific variable to retain lazy unlock: the SDK itself eagerly processes its global variable, including an empty value. The plugin does not mutate process environment or SDK internals to suppress that behavior.
Every plaintext or TOTP request requires the current local key, rechecks the configured identity's access, and fetches current secret data. Removing or changing the key invalidates cached unlock state; an in-flight result is withheld if its key is revoked. Login results replace seed material with has_totp; request the current code separately. inkbox_credentials_get_secret adds individually selected key_pair/other access and retains login redaction. All Vault tools, including metadata and this generic reader, remain optional and must be enabled explicitly.
openclaw inkbox setup
openclaw inkbox doctor
openclaw inkbox whoami
openclaw doctor
openclaw statusUseful OpenClaw commands while iterating:
openclaw config file
openclaw config get channels.inkbox
openclaw config validate
openclaw plugins list
openclaw skills list
openclaw logsOptional provider-specific auth examples:
openclaw models auth login --provider openai --set-default
openclaw models auth login --provider openai-codex --set-defaultAfter the gateway prints [gateway] ready, [inkbox] tunnel open, mail/text subscriptions configured, and the incoming-call URL wired:
- Run
openclaw inkbox doctor. - Text
STARTto the agent's Inkbox phone number from every phone the agent should text. - Send the agent an SMS and verify it replies in the same SMS thread.
- If iMessage is enabled, connect via the Inkbox iMessage router, message the agent, and verify it replies in the same iMessage thread.
- Send the agent an email and verify it replies from its Inkbox mailbox.
- Call the agent phone number and ask for its handle, email, and phone.
- Ask during a call for a post-call SMS or email follow-up, then verify it sends after hangup.
- Ask the agent to save a contact and an Inkbox note, then ask it to read them back.
| Field | Required | Default | Description |
|---|---|---|---|
apiKey |
yes | - | Agent-scoped Inkbox API key. Admin keys are accepted by setup only so it can mint an agent-scoped key. |
identity |
yes | - | Inkbox agent identity handle. |
signingKey |
inbound | - | Webhook HMAC secret. Required for inbound email/SMS/iMessage/calls. |
baseUrl |
no | SDK default | Override Inkbox API base URL. |
tunnelName |
no | identity handle | Override Inkbox tunnel name. |
publicUrl |
no | - | Public OpenClaw URL. If omitted, the plugin opens an Inkbox tunnel. |
allowedRecipients |
no | - | Outbound recipient allowlist for messaging targets and A2A Agent Card URLs. Empty means no local outbound filtering. |
allowedInboundContactIds |
no | - | Optional local inbound allowlist by Inkbox contact UUID. Empty means Inkbox contact rules decide reachability. |
includeContactMemories |
no | true |
Include memories from the matched contact as background context for inbound email, messaging, reactions, and calls. Set false to disable them. |
a2aProgressIntervalSeconds |
no | 180 |
Send a short nonterminal progress update while serving an A2A task at this cadence. Set to 0 to disable periodic updates. The immediate receipt includes the configured frequency. |
sms.batchDelayMs |
no | 0 |
Inbound SMS and iMessage fragment batching window. |
voiceStack |
no | legacy-compatible | inkbox_voice_ai, openai_realtime, or inkbox_tts_stt. Setup always writes an explicit value. |
voiceAiAuthorityMode |
Voice AI | saved server value | Informational local copy of the selected contact_scoped or yolo authority. |
voicemailDetection |
no | enabled |
Outbound-call voicemail detection policy. CI should set disabled. |
voiceTranscriptCoalesceMs |
no | plugin default | Non-realtime voice transcript coalescing window. |
voiceAgentPrewarm |
no | plugin default | Prewarm the voice path when the gateway starts. |
voiceRealtime.enabled |
no | auto | Use raw phone media with an OpenClaw realtime voice provider. Set false to force Inkbox STT/TTS. |
voiceRealtime.provider |
no | openai |
Realtime provider id, for example openai. |
voiceRealtime.model |
no | provider default | Realtime model override, for example gpt-realtime-2. |
voiceRealtime.voice |
no | cedar |
Realtime voice name. |
voiceRealtime.toolPolicy |
no | owner |
Tool policy for realtime openclaw_agent_consult. |
voiceRealtime.consultPolicy |
no | substantive |
When realtime calls should consult the main OpenClaw agent. |
voiceRealtime.providers.openai.apiKey |
no | - | OpenAI API key validated by setup and used for Realtime calls. |
voiceRealtime.fallbackToInkboxSttTts |
no | true |
Fall back to Inkbox STT/TTS when realtime is unavailable. |
slackEnabled |
no | false |
Enable connected Slack messaging and eight Slack tools. |
imessageThreadedReplies |
no | false |
Source-targeted native replies and durable follow-ups. |
vault.keyEnvVar |
no | INKBOX_OPENCLAW_VAULT_KEY |
Env var containing the vault unlock key. |
Claimed identities can discover and execute the current remote catalog with
inkbox_remote_tools and inkbox_remote_call. inkbox_reply_current declares a
final reply to the current incoming email or direct SMS. See remote tools
for approval, retry and compatibility behavior.
Required by default:
- Outbound:
inkbox_send_email,inkbox_send_sms,inkbox_send_imessage - A2A client:
inkbox_a2a_call,inkbox_a2a_check,inkbox_a2a_reply,inkbox_list_a2a_tasks,inkbox_list_a2a_messages - A2A history supports optional direction, requester, worker, task/context, state/role, keyword, timestamp, cursor, and limit filters as applicable.
- Inbound A2A tasks are delivered into isolated context sessions. During those
turns,
inkbox_a2a_complete,inkbox_a2a_ask_caller, andinkbox_a2a_failcommit the task outcome explicitly. - The dependency floor is
@inkbox/sdk0.7.39. Source development pins its exact Git revision. - Email reads:
inkbox_list_unread_emails,inkbox_list_emails,inkbox_get_email,inkbox_get_email_thread - SMS reads:
inkbox_list_text_conversations,inkbox_get_text_conversation(conversation-ID aware, groups included by default) - iMessage reads:
inkbox_list_imessage_conversations,inkbox_get_imessage_conversation - Voice reads:
inkbox_list_calls,inkbox_list_call_transcripts - Contacts:
inkbox_lookup_contact,inkbox_get_contact,inkbox_list_contacts,inkbox_create_contact,inkbox_update_contact,inkbox_delete_contact - Notes:
inkbox_list_notes,inkbox_get_note,inkbox_create_note
Optional:
- Outbound:
inkbox_forward_email,inkbox_place_call - Lifecycle:
inkbox_mark_emails_read,inkbox_list_texts,inkbox_get_text,inkbox_mark_text_read,inkbox_mark_text_conversation_read,inkbox_mark_imessage_conversation_read - iMessage:
inkbox_imessage_triage_number,inkbox_list_imessage_assignments,inkbox_send_imessage_reaction - Notes:
inkbox_update_note,inkbox_delete_note - Contact rules:
inkbox_list_mail_contact_rules,inkbox_list_phone_contact_rules; manage changes in the Inkbox Console - Note access:
inkbox_list_note_access,inkbox_grant_note_access,inkbox_revoke_note_access - Vault:
inkbox_credentials_list,inkbox_credentials_get_login,inkbox_credentials_get_api_key,inkbox_credentials_get_ssh_key,inkbox_credentials_get_secret,inkbox_totp_code - Diagnostic:
inkbox_whoami
Send and email-forward tools accept optional completeSilently: true when the send is the final requested action and no acknowledgment is wanted. Successful sends then end the turn without an extra source-channel reply. Leave it unset when more work or a reply remains; failed sends never silently complete.
Group SMS, iMessage, and WhatsApp participants share a conversation session, including reactions. Different groups and direct conversations remain separate. Automatic email replies use the stored message's reply-all route, preserving visible To/CC and threading without adding BCC recipients or the agent itself. Explicit new-email tools still use the recipients you specify.
The setup wizard exposes these independent choices for new or existing identities:
| Setting | Values | Default |
|---|---|---|
channels.inkbox.groupReplyMode / INKBOX_GROUP_REPLY_MODE |
auto, mention |
auto |
channels.inkbox.companionResponseMode / INKBOX_COMPANION_RESPONSE_MODE |
safe, relaxed |
safe |
Saved account settings override environment defaults. In mention mode, the current
message must contain a complete, case-insensitive @agent or @<agent-handle>.
Links, email addresses, previous messages, and older batched fragments do not count.
Unmentioned group messages and reactions are persisted as background context for
the next waking turn, without model calls, tools, typing, or interrupting work.
Ordinary local slash controls and native /approve <id> <decision> answers from
the prompted sender remain available without a mention.
Eligible ordinary messages reach OpenClaw immediately and follow its native
queue/steering settings; the plugin does not replace that scheduler or force an
abort-and-restart on every new message. Quiet messages never enter that queue.
Companion model turns are processed serially within their conversation scope.
Automatic SMS/iMessage/WhatsApp groups allow the model to remain silent during ordinary
chatter. The dispatch uses OpenClaw's Inkbox-only
surfaces.inkbox.silentReply.group="allow" default without changing saved config;
explicit surface or agent-default silence settings are preserved. Current mentions
and commands retain the host's required-reply behavior. On newer OpenClaw hosts,
ordinary direct requests require an answer: NO_REPLY alone does not suppress it.
Successful explicit completeSilently sends still suppress duplicate acknowledgements.
Companion mode is enabled separately on the Inkbox identity by an administrator who selects a sponsor. Installing this plugin does not change that configuration. Sponsored email, group MMS, supported dedicated-line iMessage, and existing WhatsApp group conversations load the complete authorized initialization snapshot through the SDK, including later pages, notices, and attachment references. Environment, identity, channel, conversation scope, and activation isolate sessions. An activation is an access period, not an individual message; ordinary tracked messages remain separate.
Safe mode wakes only for current messages with sender_access: "direct".
Sponsored messages and messages with missing or unknown access stay context-only.
Relaxed mode may respond to any delivered sender. Admission metadata is not a
statement of trust or permission to execute commands. In Companion email mention
mode, the agent's actual mailbox in the current To list also counts as
addressed; Cc-only messages do not. This never bypasses Safe mode.
Companion slash controls require the current access/addressing gates and the sponsor.
Eligible controls can reach a running turn without waiting for its model reply.
/clear uses OpenClaw's /new, /cancel uses /stop, and /health shows native
session /status. OpenClaw has no historical-session picker for /resume; the
channel explains that limitation without starting a model or claiming a session
was resumed.
Native /approve <id> <decision> answers require those same access/addressing gates
and the original waking turn's sender, who may differ from the sponsor in Relaxed
mode (email matching is case-insensitive). In mention mode, use, for example,
@agent /approve <id> allow-once.
Native approval prompts are delivered immediately on the original turn's route;
eligible answers resolve the waiting host approval without starting another model
turn. Pending prompts expire or clear with the host's approval lifecycle.
History never acts as a new command or approval. Later replies use the saved
sponsor message for email or the canonical group conversation for texts; they do
not reload activation history before every turn or send.
Inputs are bounded at 128 KiB and are not silently truncated. Private journals in
~/.openclaw/inkbox/ persist receipts before acknowledgment and background context
across restarts. Completed model replies are checkpointed before sending. Known
transient pre-submission/pre-send failures retry with bounded backoff. Other
preparation failures stop after five retries; uncertain host
submissions or sends remain paused for inspection, never blindly replayed. This is
at-least-once webhook delivery, not a guarantee of exactly-once model execution.
Ordinary mention-mode background context retains compact sender/text/media entries
up to 128 KiB; when older context is omitted, the next waking turn receives an
explicit retention notice. Status/stop/approval commands do not consume background
context; an authorized, committed reset clears the captured context even if its
acknowledgment cannot be delivered. Companion snapshots remain fail-closed at their size
limit and are never silently truncated.
The package includes all skills/*/SKILL.md files in npm tarballs.
| Skill | Trigger |
|---|---|
inkbox-troubleshooting |
Runtime/config errors, failed tools, readiness issues |
inkbox-email-triage |
Checking or replying to Inkbox email |
inkbox-sms-responder |
Sending, replying to, or triaging SMS |
inkbox-imessage-responder |
Sending, replying to, or triaging iMessage |
inkbox-outbound-calling |
Placing calls to numbers or contacts |
inkbox-call-review |
Reviewing calls and transcripts |
inkbox-contact-lookup |
Resolving, creating, or updating contacts |
inkbox-contact-rules |
Managing mail/phone allow and block rules |
inkbox-identity-access |
Granting/revoking contact or note visibility |
inkbox-notes-memory |
Saving, retrieving, or updating Inkbox notes |
inkbox-credential-use |
Fetching vault credentials or TOTP codes |
inkbox-outreach-sequence |
Multi-step outreach over email/SMS |
npx --yes pnpm@10.28.0 install --frozen-lockfile
npm run typecheck
npm test
npm run build
npm_config_cache=/tmp/npm-cache npm pack --dry-run- Plugin, not fork: uses OpenClaw plugin SDK, channel gateway, tools, HTTP routes, CLI, and bundled skills.
- Agent-scoped: runtime should use an Inkbox agent-scoped API key.
- Tunnel-first inbound: with a signing key, gateway opens an Inkbox tunnel, creates mail/text webhook subscriptions (plus an identity-owned iMessage subscription when enabled), and wires the incoming-call URL.
- Voice: Inkbox STT/TTS fallback path and realtime raw-media path both route through the same call WebSocket.
- Post-call actions: realtime calls can register, edit, delete, and dispatch work for the main OpenClaw agent after hangup.
- Hangup: realtime calls expose a two-step hangup tool so the agent can say goodbye before dropping the phone leg.
- Identity-aware calls: call prompts include agent handle/mailbox/phone/tunnel and known caller contact metadata.
See PLAN.md for the longer architecture history and roadmap.
MIT - see LICENSE.
WhatsApp is available by approval for an agent with a dedicated personal iMessage number. The channel uses that same number, not a shared line. Request access from the Inkbox Console. There is no local enable flag, self-service provisioning tool, or automatic SMS fallback. Existing installations subscribe to notifications independently of a cached disabled identity snapshot, so later approval does not require changing credentials.
The plugin handles authenticated incoming direct and existing-group text and media, retains source-owned work and answers across restarts, and routes final replies to the originating WhatsApp conversation. Do not duplicate an ordinary final answer with a send tool. Delivery notifications update tracking without waking the model or automatically resending.
Fifteen native tools provide sending, conversation/message reads, owned-media upload/access, local mark-read, fresh status and read-only send lookup. Upload one local file within current organization limits (20 MiB transport ceiling) and retain its media ID before sending. Text is at most 4,000 Unicode code points. Preserve the original idempotency key and media ID after uncertainty; confirmed sending with unknown delivery is not a failed send. Incoming files have a temporary local path when bytes are available, or an explicit unavailable notice. Available images and audio enter the host’s native media processing, including captionless messages. Native file replies upload and send one local attachment with their original source and retained send receipt. The private local cache is bounded to 256 MiB/256 files, expires old files after 24 hours on cache activity, and refuses new materialization rather than evicting fresh files in use. Stable owned media IDs remain the recovery handle. Send to one E.164 recipient string or an existing conversation ID. Group names are display labels, not destinations. Groups are discovered through inbound messages: at least one message must arrive before outbound group sends are permitted. Group creation and recipient arrays/lists are not supported. Explicit quoted replies use conversationId plus replyToMessageId; thread tools page the corresponding history. Named/custom reaction tools require a stable idempotency key and preserve exact receipt status: queued or uncertain is not applied. Peer reactions are contextual notifications in the same conversation, not fresh commands. New ordinary replies are plain chat messages in the same conversation. Quote selectively for older messages, multiple requests, or a specific attachment by explicitly supplying replyToMessageId. Active-source tools inherit the destination, not a new quote; an explicit different destination remains separate outreach. Reaction context stays plain. Saved plain intents and caller-supplied recovery keys never acquire a new quote, and an uncertain or rejected quoted send never produces a plain replacement. Typing, remote read receipts and WhatsApp calls are not supported.
WhatsApp direct messaging requires @inkbox/sdk 0.7.29 or later and a compatible API. The same published SDK supports groups, structured mentions and WhatsApp Companion history. Incoming inline replies include the exact parent ID, accessible author, text, and attachment labels separately from current-message instructions. One optional SDK read uses its existing timeout: temporary failures produce temporarily_unavailable, while denied, missing or mismatched parents produce unavailable. The current message still arrives, and later messages can resolve the parent after recovery. Quoted mentions never trigger attention or commands.
Group attention uses the existing groupReplyMode and companionResponseMode settings. A native WhatsApp mention of the agent or a typed @agent/identity handle in the current message satisfies mention mode; quoted/history mentions never wake a new turn. Auto mode lets the host decide whether an ambient group message warrants a reply, including native NO_REPLY. Mentioned people are rendered using contact names only, the agent handle, a resolved phone number, or an explicit unknown-participant label; contact notes and memories are never inserted. This rendering also applies to direct messages and does not change attention or command authorization.
Ordinary groups recheck their current participants against configured local contact/recipient allowlists. Unresolved members cannot satisfy a configured allowlist. Companion uses the canonical authorized group activation and sponsor, revalidates that activation before host dispatch and effects, and never extends its grant to a direct message or another group. Explicit destinations retain their own authorization. Saved answers and attachments survive transient preflight failures without another model turn; accepted/unknown sends retain their receipts and are not automatically duplicated. Definitive policy rejections do not produce a replacement message.
Use a compatible API. Use inkbox_send_whatsapp for explicit sends: retries retain the host tool-call identity, or an explicit stable idempotencyKey. Reuse that key and unchanged payload after uncertainty; a distinct intentional send needs a distinct logical key. The generic host message adapter does not supply a stable attempt ID, so it cannot send WhatsApp messages. Ordinary inbound final replies remain automatic.
When INKBOX_HOSTED_MODE=1, doctor reads the secret-free report named by
INKBOX_DIAGNOSTICS_FILE. Reports must match the identity and harness, belong to
this user, have private file permissions, and be no more than 60 seconds old.
Missing, stale, or unhealthy reports do not establish readiness. With
INKBOX_DIAGNOSTIC_CONTEXT=terminal, the signing key is checked in the runtime
report; the key itself is not needed in the terminal. Runtime processes still
require their own signing key. Managed delivery does not require ordinary webhook
subscriptions. Standalone diagnostics are unchanged. These checks do not send
messages or prove end-to-end delivery.
