How to Set Up OpenClaw iMessage Without a Mac

We built an iMessage channel plugin for OpenClaw on Photon Beta (2.0), then ran it end to end on OpenClaw 2026.11.3: sign in, first text, a photo in, a photo out, a text sent while the gateway was stopped, the allowlist, and a fresh install from GitHub with setup run again. The setup commands below are the ones from that run.

How OpenClaw does iMessage today

As of OpenClaw 2026.11.3, iMessage comes from the official @openclaw/imessage plugin. The gateway starts imsg, a command-line tool that reads and sends through the Messages app, and talks to it over JSON-RPC. imsg has to run on a Mac where Messages is signed in, with Full Disk Access and Automation permission granted to it.

A gateway on Linux or Windows can still use this channel through an SSH wrapper that runs imsg on that Mac. Either way, a signed-in Mac stays in the loop.

Basic mode sends and receives text and media. Tapbacks, threaded replies, effects, typing indicators and read receipts need the private API mode of imsg, which only runs with System Integrity Protection turned off. OpenClaw's private API docs call that a real security tradeoff and suggest a dedicated Mac or a separate macOS user for it.

If you already keep a spare Mac online, that is OpenClaw's native route, and the OpenClaw iMessage docs walk through it. For every way to put an agent on iMessage, with a Mac or without one, see How to build an iMessage agent in 2026.

What happened to BlueBubbles in OpenClaw

OpenClaw used to ship a BlueBubbles channel. Its docs now say BlueBubbles support was removed: channels.bluebubbles configs move to channels.imessage, and iMessage runs through imsg only. The announcement has the migration steps.

The move keeps the Mac, since the BlueBubbles server also runs on macOS. If the BlueBubbles alternative you are after is one with no Mac at all, that is the gap Photon's plugin fills. The path from BlueBubbles to production covers the wider tradeoff.

Photon's iMessage plugin for OpenClaw

openclaw-photon is an open-source channel plugin, MIT licensed, at release v0.2.0. It adds a channel called Photon (iMessage, no Mac) to OpenClaw's setup. Photon hosts the iMessage line. Your gateway opens one outbound WebSocket connection to Photon and receives messages over it, so there is no webhook to register and no public URL to keep alive.

You need OpenClaw 2026.11.3 or later and a Photon account at app.beta.photon.codes. The setup wizard can create the Photon project and its API key for you. If you want to know how a hosted line works with no Mac on your side, What is an iMessage API? explains the model.

Set it up in three commands

1. Install the plugin

openclaw plugins install git:github.com/photon-comm/openclaw-photon

Use the git:github.com/... form shown here. On OpenClaw 2026.11.3, the github:owner/repo shorthand fails with unsupported npm spec: protocol specs are not allowed.

OpenClaw asks two questions: whether to install a plugin that doesn't come from ClawHub, and whether to grant its capabilities, which cover the Photon channel only. Answer y to both. In a script, pass the answers as flags:

openclaw plugins install git:github.com/photon-comm/openclaw-photon \
  --force --accept-capabilities

To pin this release, add its tag: git:github.com/photon-comm/[email protected].

2. Sign in to Photon and get a line

openclaw configure --section channels

Choose Photon (iMessage, no Mac) and sign in with Photon. The wizard prints an auth.photon.codes/device link with a code. Open it on any device and confirm the code; your password never goes into the terminal.

The wizard then lists your Photon projects, or creates one named OpenClaw, and makes an API key for the gateway that it saves in your OpenClaw config. It asks for the phone number or iMessage email you will text from, assigns that sender a shared line from Photon's pool, and prints the number to text.

Choose Finished, answer Yes to configure DM access, and pick Allowlist. Your number is already filled in, so only you can reach the agent. If it then asks about administration from chat, choose Skip for now.

3. Start the gateway

openclaw gateway run

Text the line from your phone. A shared line only answers, so the first message comes from you. The agent replies in the same conversation, as an iMessage from that line. In our run, the first reply read: "I'm your OpenClaw personal assistant, running on Claude Haiku 5.5 through the Photon Beta plugin."

Send from the command line

The channel works for outbound messages too, from the agent or from the CLI:

openclaw message send --channel photon --target +15551234567 \
  --message "Deploy finished."

Add --media with an image file or URL to send a picture. The picture goes first and the text follows it.

What the plugin supports today

In our end-to-end run on OpenClaw 2026.11.3 with Photon Beta (2.0), the agent answered the first text within ten seconds, described a photo we sent it, and sent a picture from its workspace back. Images sent with openclaw message send --media, from a file and from a URL, arrived. We stopped the gateway, texted the line, and started it again: the gateway picked up Photon's event stream where it had left off, and the agent answered that text in the same conversation. With the allowlist set, a text from a number not on it got no reply. A fresh install from GitHub, with setup run again, replied too.

The plugin also sends a read receipt when the agent picks up a message and a typing indicator while it works. OpenClaw's own channel only gets those in the private API mode of imsg.

The limits of v0.2.0:

• Direct messages only. Messages in group chats are ignored.

• One Photon project per gateway.

• Text and images only. Photon Beta doesn't accept tapbacks yet, so the plugin doesn't send them.

• A shared line can't start a conversation: you text it first. An agent that texts first needs a project with a dedicated line.

Without the plugin: Photon's MCP server

If your agent only needs to send, you can skip the plugin and give OpenClaw Photon's MCP server. We tested this route on OpenClaw 2026.11.3 with Photon Beta (2.0): the agent read conversations, and a message it sent was delivered.

The hosted server signs in with OAuth:

openclaw mcp add photon --url https://mcp.photon.codes/mcp \
  --transport streamable-http --auth oauth
openclaw mcp login photon
openclaw mcp probe photon

Stop the gateway first, because openclaw mcp add and openclaw mcp login refuse to run while it is up. In our run, the probe listed 148 tools.

The local server uses an account service key from the Photon Beta dashboard:

npm install @photon-ai/mcp
openclaw mcp add photonline --command node \
  --arg /absolute/path/to/node_modules/@photon-ai/mcp/dist/cli.js \
  --env 'PHOTON_API_KEY=${PHOTON_API_KEY}' \
  --include 'createOrGetUser,createOrGetSpace,sendMessage,listMessages,getMessage,listSpaces,getSpace,setSpaceTyping,markMessageRead,listResources'

The single quotes keep ${PHOTON_API_KEY} as written. OpenClaw reads the key from the gateway's environment, so set PHOTON_API_KEY there and the key stays out of the config file.

The agent needs the Photon project ID in its prompt, since every project tool takes it as path.id. A send then runs in order: listResources, createOrGetUser for the line and for the recipient, createOrGetSpace, and finally sendMessage.

A shared line can't start a conversation. An agent that texts first needs a dedicated line; on a shared line, the person has to text first.

Why inbound needs a relay

Receiving is where this route stops. Photon webhooks post to a public HTTPS URL and can't add custom headers. OpenClaw's hook endpoint requires a token in a header: without one the request gets a 401, and a ?token= query parameter gets a 400. So a Photon webhook can't call OpenClaw directly.

Something has to sit in between: a public relay that verifies Photon's webhook signature and forwards the event with the token header, or an always-on client on Photon's WebSocket event stream. We checked the OpenClaw half: a Photon-shaped message event posted to the hook made the agent reply, and the reply was delivered.

The plugin is that always-on client: it keeps the WebSocket connection open inside the gateway, so inbound messages need nothing else.

Deny shell tools for messaging agents

In the MCP test, a tool call failed and the agent went looking for API keys on the filesystem with shell commands. An agent that acts on text messages should not have a shell. Deny OpenClaw's runtime tools (exec, process and code_execution) in openclaw.json:

{
  "tools": { "deny": ["group:runtime"] }
}

For a tighter start, OpenClaw's messaging tool profile leaves out shell and file tools and still allows configured MCP servers. The tool policy docs list every group.

Frequently asked questions

Can OpenClaw use iMessage without a Mac?

Not through its own channel. As of 2026.11.3, OpenClaw's iMessage plugin needs imsg on a Mac signed in to Messages, either on the gateway host or over SSH. With Photon's plugin it can: Photon hosts the line, and the gateway needs no Mac.

Does OpenClaw still support BlueBubbles?

No. OpenClaw's docs say BlueBubbles support was removed, and they move channels.bluebubbles setups to the imsg channel, which still needs a Mac. For a BlueBubbles alternative without one, use the Photon plugin.

Is the Photon plugin on ClawHub or npm?

Not yet. Install it from GitHub with the git: command above. That is also why OpenClaw warns that the plugin doesn't come from ClawHub.

Does it work in group chats?

Not yet. The plugin handles direct messages and ignores messages in group chats.

Which Photon credentials does it use?

A Photon Beta (2.0) project ID and a project API key with the project:read, project:write and platforms:read permissions. The setup wizard signs you in and creates the key, or you can enter one from the dashboard at app.beta.photon.codes. For Photon Stable, with a Spectrum project ID and secret, use release v0.1.1 of the plugin.

Do I need a webhook or a public URL?

Not with the plugin. The gateway opens a WebSocket connection to Photon and receives messages over it. Only the MCP route needs a relay for inbound messages.

Can the agent send and receive images?

Yes. In our test the agent described a photo it was sent and sent a picture back, and images sent with openclaw message send --media arrived.

Does the conversation survive a gateway restart?

It did in our test. A text sent while the gateway was stopped got its answer once the gateway started again, in the same conversation.

Can one gateway serve several Photon projects?

Not today. The plugin connects one Photon project per gateway.

Get started

The plugin is on GitHub at photon-comm/openclaw-photon. You need a Photon account at app.beta.photon.codes; the setup wizard takes care of the project and the API key. For the Photon API itself, start with the Photon Beta docs.

openclaw plugins install git:github.com/photon-comm/openclaw-photon
openclaw configure --section channels
openclaw gateway run

Then text the line.