Slack

Two ways to connect

Slack support is optional and off until you connect it. The agent always runs on your computer; Slack is only where you talk to it.

Personal bot (default)

You create your own Slack app from a manifest OpenOrc generates, install it, and give OpenOrc three things: the bot token (xoxb-…), an app-level token with connections:write (xapp-…), and your Slack member ID. OpenOrc connects from your computer with Slack's Socket Mode, an outgoing WebSocket, so there is no public URL, no server to host, and no OpenOrc service in between.

The manifest asks for these bot scopes: app_mentions:read, chat:write, channels:history, groups:history, users:read, and files:read. It subscribes to mentions and to messages in public and private channels the bot is in. Before connecting, OpenOrc calls auth.test and users.info to check that the bot token and the member ID belong to the same workspace, and that the owner is a real person, not a bot. The app token is only used to open the connection; OpenOrc does not check that it belongs to the same Slack app.

Team relay (advanced)

One computer holds the Slack connection and relays requests to teammates' desktops. See The team relay.

Source: packages/core/src/services/slack/service.ts, apps/desktop/src/renderer/src/lib/slack-setup.ts

Which messages count

Slack sends the bot every message in the channels it has joined. OpenOrc acknowledges each one and ignores it unless all of these hold:

• It comes from the connected workspace, in a channel (not a direct message).
• It was written by a person, not a bot, and is an ordinary message or a file share.
• It mentions the bot, or it is a reply in a Slack thread where the bot was already mentioned.

With a personal bot, mentions by anyone other than the owner are ignored. Each Slack event ID is recorded, so an event Slack delivers twice is handled once.

From a mention to a conversation

1. OpenOrc posts "Request received for your OpenOrc desktop." in the Slack thread.
2. It reads the Slack thread's history up to that message with conversations.replies.
3. It finds the Workspace conversation linked to this Slack thread, or creates one titled "Slack:" followed by the start of your message, in the Workspace folder you set for Slack.
4. Your messages are recorded in the conversation as yours; other participants' messages are recorded as context, labeled "Slack participant".
5. A new conversation starts with the agent and model you set for Slack; later turns keep the conversation's current model. Every turn uses the stricter of the conversation's and the Slack setting's permission level, and Plan wins over Act.

The agent receives the whole Slack thread as quoted context, your message, and instructions to treat other participants' messages as context rather than as permission to act. The exact text is on What OpenOrc tells agents.

Later replies in the same Slack thread continue the same conversation. While the agent is busy, replies in that thread wait in a queue of up to 20; a mention in another thread gets a notice to wait for the current reply.

Source: packages/core/src/services/slack/relay.ts, runner.ts

Who can do what

With the team relay, each registered person is the owner of their own requests: their mentions run on their own desktop, never on someone else's.

Written questions from the agent, and stopping a run, are only available on the desktop. Slack shows a notice when the agent is waiting for a written answer.

Switching model or folder

Slack runs have two extra OpenOrc tools. execution_context reports the current provider, model, effort, and the folders available. execution_switch queues a change when you ask for another model, effort, or folder:

• The model and effort must match an entry in the provider's catalog exactly.
• Folders come from your imported projects, the Workspace folder, and up to 250 folders at most 3 levels below it, skipping hidden folders and build output.
• The switch happens after the current turn succeeds, in a fresh session with the same mode and permission level. A request can switch at most 4 times.

If a run fails, OpenOrc tries once more with the agent and model you set for Slack, and tells that model what failed.

What OpenOrc posts

• Progress: one message that is edited as the agent works, at most every 2 seconds, showing a status line and the last 9,000 characters of the agent's reply. The status line names the model and the tool the agent is using, such as "Working · <model> · <tool>". Reasoning and tool output are never posted.
• The final reply: the agent's last message, replacing the progress message, up to 11,500 characters.
• Notices: for example when your desktop is not connected, when a message is too long (over 20,000 characters), or when the agent is waiting for you on the desktop. When a request fails, the notice includes the provider's error message, redacted.

Every message starts by mentioning the owner. @ mentions in the agent's text are escaped so the agent cannot ping people, and link previews are turned off.

Approvals in Slack

When a Slack-started run asks for permission, OpenOrc posts the request in the thread: the reason, the tool name, and its input, split into Slack messages of up to 11,200 characters (four 2,800-character sections each). The last message has Allow once and Deny buttons. Questions that need a written answer are not posted; they wait on the desktop.

• A click counts only if it comes from the owner, in the same workspace, channel, and thread, on the latest approval message, within 10 minutes.
• The desktop checks again that the request is still waiting before applying the answer.
• When a request is answered or no longer pending, its message is edited to say so. Buttons from before a restart stop working.

Images

Images in an active Slack thread, from anyone, are passed to the agent. OpenOrc checks each file with files.info, accepts PNG, JPEG, GIF, and WebP up to 20 MB, and downloads it from files.slack.com with the bot token, following at most 3 redirects and checking each one before sending the token. Downloaded images are validated like attachments and cached in the profile folder.

When your computer is offline

Slack can only reach your agent while OpenOrc is open, connected, and your computer is awake. Nothing queues on a server.

• After restarting OpenOrc, press Connect again; Slack does not reconnect automatically.
• Messages sent while you were disconnected are not fetched later, except as history when the next mention arrives in that thread.
• If you disconnect while an agent is working, the agent keeps going, and the final reply is posted when you reconnect.
• If you quit while a Slack request is running, the request ends. After you reconnect, the thread gets a message saying it was interrupted.

The team relay

The team relay lets several people use one Slack app. One OpenOrc desktop, the host, holds the Slack tokens, runs Socket Mode, and serves a small HTTP API on 127.0.0.1 (port 47831 by default). The relay only listens on the host's loopback address, so teammates' desktops reach it through an SSH tunnel they set up themselves; OpenOrc does not create one.

• The host registers each teammate's Slack member ID and gets a device key (oqd_ followed by 64 hex characters) to give them. The key is shown once and works until the host removes that device. Only a SHA-256 hash of the key is stored.
• Each desktop polls /poll every second with its key. It receives only jobs for its own member ID, and can post results, request approvals, and download images only for its own jobs.
• Requests with an Origin header are refused, so a web page cannot call the relay.

The host sees all relayed messages, and the Slack tokens never leave it. When the person who mentions the bot has no connected desktop, including people with none registered, the bot replies that their desktop is not connected.

What is stored

Slack tokens and relay settings are in slack-secrets.enc, encrypted with Electron safeStorage; see Settings and secrets. In the database, OpenOrc keeps the Slack messages of each conversation, the IDs of events it handled, receipts that stop a request from running twice, and a journal of active jobs and of every Slack thread the bot takes part in. The journal holds the full text of each thread's messages, including other people's. These records are not pruned.