Chat and Code
Chat with agents, run Code sessions, and use chat apps.
A chat is where an agent or Clem answers you, in the dashboard or from oo.
Each chat is with one agent and is yours alone.
- Use it when
- You want an agent or Clem to answer, in the dashboard or from oo
- You get
- Chats you own, with files, approvals, models and group chats
- Cost
- Each answer is model requests, listed on Requests
- Setup time
- None: open Chat
- Needs
- Chat with agents on the agent
Chats
Chat lists the agents you may use, and Clem if you may. An agent names a chat after its first answer, unless you named it.
Members see the agents they may chat with. Administrators see every agent. A member reaches a connected agent in its own app, not here.
Messages and answers
A message is up to 50,000 characters. Longer text goes as a file.
While the agent answers, a new message waits in a queue. Stop response ends the answer in progress. An agent may also write later on its own.
Some answers stop and ask you first:
- Approval required: the agent wants to use a tool. You allow it once, for the session, or deny it.
- Question: the agent needs an answer to go on.
Inbox lists the latest updates from your agents, including those waiting for you.
Files
You attach up to 5 files to a message, 5 MB each and 10 MB in all. An upload you don't send expires after a day. Hermes agents take text files, text PDFs and PNG, JPEG, GIF or WebP images. Files an agent sends back can be downloaded from the chat.
Models and thinking
In the message box, the model picker shows the chat's model. It lists the models the agent's key and your limits allow. Some models can't take over a chat already under way; choosing one starts a new chat. Where the agent offers it, Thinking sets how hard the model thinks. Higher levels cost more.
Context window
The ring beside the message box shows how full the model's context window is. Choose it to see Context window: the tokens used out of the window. For an OpenClaw agent, Estimated split shows what fills it. Its parts are System prompt, Agent files, Skills, Tools and Messages. Administrators also get See detailed breakdown, which opens the chat's model requests.
Group chats
A group chat holds several people and at most one agent. Everyone in it reads every message and answer. The agent works for whoever wrote the message, at their own level. It answers every message, or only when mentioned, as the group's owner chooses.
Chats from chat apps
Once your chat app account is linked to you, its direct messages with an OpenClaw agent show in Chat. Only you see them, and you reply in the app, not here.
Chats in the agent's terminal
An agent on Claude, Codex, Gemini CLI, OpenCode or Pi, on its own VM, keeps each chat as a session of its CLI. An agent with Per person files doesn't. Continue in the terminal gives the command that opens the chat in the VM's terminal. What you say there shows in the chat. A session you start in the terminal stays there. One side writes at a time: the chat or the CLI.
Archive and delete
An archived chat leaves the sidebar and takes no more messages. Search chats still finds it. A deleted chat's messages leave the chat. The agent's runtime may keep its own copy, and backups still hold one.
Cost
Every answer is model requests on the agent's key. Requests lists each one with its model and cost. The context figure in a chat is the model proxy's estimate, not a charge.
Limits
- A chat stays with its agent; it can't move to another agent.
- A chat app conversation is read-only in the dashboard.
- A chat that support had access to can't be deleted, only archived.
- Voice calls need your own sign-in, not an API key.
- While your Sunport installs an update, the dashboard's chats take no new messages.
How-to guides
Code sessions
A Code session is a coding workspace with its own transcript.
You start and continue it with oo code or the API. The dashboard has no Code screen.
Every message starts a run. A message sent during a run waits in the session's queue.
- Use it when
- A coding agent should change code on a machine your team shares
- You get
- A session with its own transcript, in a folder on that machine
- Cost
- Model requests; the machine's VM is priced in Compute
- Setup time
- None once you work on a machine
- Needs
- Work in Code, which every person has, and a machine you work on
Machines and folders
A session runs on a machine: a VM of your Sunport that your team shares. It uses what is installed there. It works in one folder on the machine, chosen when it starts. There is no copy and no branch of its own: in a repository, it works on the branch checked out there.
On the machine, a session works as the machine's shared account. Administrators, and the owner of every agent on that VM, can run one as root. Anyone who starts a session there can read what that account reads.
Environments
An environment sets a session's packages, instructions and model. One environment is built in. You can import others from a public GitHub repository, for yourself or for everyone. A session keeps the environment it started with. On a machine, an environment's setup commands don't run.
Models and thinking
Each session has its own model and thinking level. You may choose only the models your limits allow. Only its owner changes them, and not while a run goes or prompts wait.
Sharing
A session is its owner's. The owner shares it with a person as:
viewer: reads it.contributor: also sends messages and stops their own runs.
A contributor's runs use the machine's shared account, as the owner's do. Sharing a session doesn't give access to its machine.
What a session leaves running
A run doesn't stop what its commands started, such as a dev server. Those processes go on after the run, and after the session stops. Anyone who can read the session sees them. Only its owner stops one.
Archive and delete
Only a session's owner archives or deletes it. An archived session leaves your list and can't be continued. Deleting removes its messages for everyone. Neither stops what it left running, nor removes its folder.
Cost
A session's runs are model requests, listed on Requests. The machine's VM is priced like any other VM.
Limits
- A session on a machine can't be forked.
- You add or delete files in a machine's folder with the machine's own files, not through a session.
- A file you send in a message is up to 5 MB. A workspace transfer is up to 8 MiB.
- A session stays on its machine; it never moves to another.
- A timed-out
oo code waitdoesn't stop the run.
How-to guides
Chat apps
Chat apps are the apps people already chat in, such as Telegram and Slack. An agent answers there through its own bot, only to the people you let in.
- Use it when
- People should reach an agent from the chat app they already use
- You get
- The agent's own bot, answering only the people you let in
- Cost
- Model requests; a dedicated iMessage number has its own price
- Setup time
- Making the bot in the app, then pasting its token
- Needs
- Change agents and Start jobs to connect; Manage who can use agents to let people in
Which agents and apps
Assistants, OpenClaw and Hermes, connect to Telegram, Slack, Discord, Mattermost and iMessage. Coding agents run no chat app bots. Clem connects to Telegram, Slack, Mattermost and iMessage. Each person can also connect their own WeChat to an OpenClaw or Hermes agent.
You connect an agent on its Channels tab.
The bot is yours
For Telegram, Slack, Discord and Mattermost, you make the bot in the app. You paste its token into your Sunport. The token stays on your Sunport. One bot serves one agent. An agent's Mattermost bot is on your Sunport's own Mattermost, which can make the bot for you.
iMessage needs no bot. The agent texts from a number OpenOrange holds. That number is shared: a text that starts with an agent's @name reaches that agent. An administrator can buy the agent a number of its own instead.
Who gets in
A bot answers only the people on its allowlist, per app.
- People who can use the agent get in through their linked chat account.
- Others who message the bot may get a pairing code or a link to ask for access. Someone who manages the agent approves a code. An administrator decides a request.
- You can also add a person by their user ID on that app, or look it up by email.
A linked chat account acts as its person. Their level and limits apply. An account linked to nobody gets no tools.
Groups
A new bot takes private messages only. Turn on Groups, and the agent also answers in the groups its bot is in. There, it answers people on its allowlist when they mention it. Everyone in the group sees the answer. Each message runs at its sender's level.
A Hermes agent answers its allowed people in groups without a switch.
An administrator can trust one group. This works for Hermes agents and OpenClaw agents on their own VM. In a trusted group, anyone who writes makes the agent act with full access, as that administrator.
In the dashboard
A person's direct messages with an agent show in their own Chat, once their account is linked. Only they see them, and they reply in the app.
Your own WeChat
WeChat is yours alone, not the agent's bot.
You scan a code on the agent's WeChat card, and WeChat opens a bot chat.
What you write there is your own chat with the agent, at your level.
It shows in your Chat too.
Whatever the agent writes in that chat reaches you in WeChat.
Text, voice messages, pictures and files go both ways.
Send /help in the bot chat for its commands.
Clem's bots
Clem's bots are an administrator's decision. Only an administrator connects one or approves who may message Clem. Clem acts for each person with their own permissions.
Cost
Every answer is model requests on the agent's key, listed on Requests. A dedicated iMessage number costs what its offer shows, each month until you release it.
Limits
- Telegram bots don't see group mentions until you turn privacy mode off in BotFather.
- Telegram and Discord need a person's numeric user ID, not a username.
- Only an agent on its own VM can release its bot. Releasing doesn't revoke the token in the app.
- Agents adopted from another host keep their channel access read-only here.
- Dedicated iMessage numbers come with a paid plan, not a free trial.
- A Hermes agent takes iMessage in a person's own chat only, not in group chats.
- WeChat allows the scan only for accounts registered in mainland China and Hong Kong.
- Your WeChat has no groups, and reaches one agent at a time.
How-to guides
- Connect an agent to Telegram
- Connect an agent to Slack
- Connect an agent to Discord
- Connect an agent to Mattermost
- Turn on iMessage
- Buy an iMessage number
- Connect your WeChat to an agent
- Let someone message an agent
- Approve an access request
- Let an agent answer in groups
- Link your chat account
- Link a person's chat account
- Share chat app history
- Connect Clem to chat apps
- Release an agent's chat bot
How-to guides
Chat
Chat with an agent
Before you start: you need Chat with agents (agents.chat) on the agent. It comes with Chat, which an administrator gives on the agent's Access tab (Let people use an agent).
- Open Chat.
- In the sidebar, choose the agent.
- Choose New chat.
- Write your message and send it.
Check it worked: the agent's answer appears, and the agent names the chat.
To end an answer early, choose Stop response.
oo chat send returns before the agent answers. oo chat follow THREAD_ID --run RUN_ID prints the answer as it comes.Chat explains queues, approvals and costs.
Send files in chat
Before you start: you need Chat with agents (agents.chat) on the agent. It comes with Chat, which an administrator gives on the agent's Access tab (Let people use an agent). A message takes up to 5 files, 5 MB each.
- Open Chat and open the chat.
- Choose Attach files and pick the files, or drop them on the chat.
- Write your message and send it.
Check it worked: the files show on your message.
To save a file the agent sent, choose its name in the answer.
Chat lists which files each agent takes.
Choose a chat's model
Before you start: you need Chat with agents (agents.chat) on the agent. It comes with Chat, which an administrator gives on the agent's Access tab (Let people use an agent). You see only models your limits allow.
- Open Chat and open the chat.
- In the message box, choose the model's name.
- Choose a model.
- If a thinking level shows beside it, choose one.
Check it worked: the picker shows the new model. Your next message uses it.
Chat explains which models a chat offers.
Answer an approval or question
Before you start: only the person or agent who started the task can answer.
- Open Chat, or Inbox to find chats Waiting for you.
- Open the chat.
- For Approval required, choose Allow once, Allow this tool for session or Deny.
- For Question, write in Your answer and choose Send answer.
Check it worked: the card shows Approved, Denied or Answered, and the agent goes on.
Chat explains approvals and questions.
Rename a chat
Before you start: you need Chat with agents (agents.chat) on the agent. It comes with Chat, which an administrator gives on the agent's Access tab (Let people use an agent). In a group chat, anyone in it can rename it.
- Open Chat and open the chat.
- At the top, choose the chat's name.
- Type the new name and press Enter.
Check it worked: under the name, the chat says the agent keeps your name.
Chat explains how agents name chats.
Start a group chat
Before you start: to add an agent, you need Chat with agents (agents.chat) on it. It comes with Chat, which an administrator gives on the agent's Access tab (Let people use an agent). You own the groups you start.
- Open Chat.
- In the sidebar, choose New group.
- In Name, type a name, or leave it empty.
- In Members, add people and, if you want, one agent.
- Choose Create group.
Check it worked: the group opens, and its people see it in their sidebar.
To make the agent answer only when mentioned, choose the group's picture at the top. Under Answers, choose Only when @mentioned.
Chat explains who reads a group chat.
Call an agent
Before you start: you need Chat with agents (agents.chat) on the agent, signed in with your own account. It comes with Chat, which an administrator gives on the agent's Access tab (Let people use an agent). oo has no voice calls.
- Open Chat and open a chat with the agent.
- In the message box, choose Talk to Research, with your agent's name.
- Read who hears your voice, then choose Continue.
- Allow your browser to use the microphone.
- Talk. Choose End call when you are done.
Check it worked: what you both said shows in the chat as text.
Chat explains what a chat costs.
Save what's useful from a chat
Before you start: Megabrain must be turned on. Only you can see the notes you save.
- Open Chat and open the chat.
- Ask the agent to save what's useful and delete the chat.
- On the card Save what's useful, then delete this chat, edit or untick notes.
- Choose Save & delete chat.
- In Delete this chat?, choose Delete chat.
Check it worked: the chat says the chat was deleted and how many notes were saved.
Megabrain explains who can read a note.
Continue a chat in the agent's terminal
Before you start: the agent runs on Claude, Codex, Gemini CLI, OpenCode or Pi, on a VM of its own, with Shared files. You need to open a terminal on that VM (Open a VM terminal). Pi doesn't get the chat's models: if it needs a provider sign-in, use /login in Pi first, then choose a model with /model.
- Open Chat and open the chat with the agent.
- In the chat's header, choose Continue in the terminal.
- Choose Copy the command.
- On the agent's page, open the Server tab and choose Open terminal.
- Confirm with Open terminal.
- Paste the command and run it.
Check it worked: what you type there shows in the chat, marked in the agent's terminal.
Chat explains what a chat keeps and who sees it.
Archive or delete a chat
Before you start: you need Chat with agents (agents.chat) on the agent. It comes with Chat, which an administrator gives on the agent's Access tab (Let people use an agent).
- Open Chat.
- In the sidebar, right-click the chat, or press and hold it.
- Choose Archive or Delete.
- Confirm with Archive or Delete.
Check it worked: the chat leaves the sidebar. Search chats lists an archived chat under Archived.
Chat explains what deleting keeps.
Code
Start a Code session
Before you start: you need Work in Code (code.write), which every person has, and a machine you work on. The dashboard has no Code screen, so use oo.
-
List the machines you work on:
oo code machines -
List the folders on one:
oo code folders MACHINE -
Start the session with its first message:
oo code start --machine MACHINE --folder api --message "Add a health check endpoint" --wait -
Send the next message:
oo code send SESSION_ID --message "Now add a test for it" --wait
MACHINE is a name from the list. start prints SESSION_ID. --create-folder makes a folder that isn't there.
Check it worked: oo code get SESSION_ID shows the agent's answer.
oo code wait SESSION_ID waits again; oo code cancel SESSION_ID stops it.Code sessions explains machines and folders.
Send files in a Code session
Before you start: you need Work in Code (code.write), which every person has, on a session you own or were added to as a contributor. Use oo.
-
Upload the file and send it with a message:
oo files upload spec.md --for code oo code send SESSION_ID --attachment ATTACHMENT_ID --message "Build this spec" --wait -
List the session's files:
oo code workspace ls SESSION_ID -
Download one:
oo code workspace download SESSION_ID dist/report.pdf
upload prints ATTACHMENT_ID. Paths start at the session's folder.
Check it worked: the downloaded file is in your current folder.
Code sessions explains file limits.
Choose a Code session's model
Before you start: you must own the session. Use oo, between runs.
-
List the models you may choose, with their thinking levels:
oo code settings -
Change the session's model and thinking level:
oo code model SESSION_ID MODEL --thinking high
MODEL comes from allowed_model_aliases. --thinking auto uses the model's own level.
Check it worked: oo prints the session with its new model_alias.
Code sessions explains models and thinking.
Choose a Code environment
Before you start: you need Work in Code (code.write), which every person has. Use oo.
-
List the environments you may use:
oo code environments -
Make one your default for new sessions:
oo code settings --environment CONFIG_ID
CONFIG_ID is an environment's ID from the list. To use one for a single session, pass --environment CONFIG_ID to oo code start.
Check it worked: oo code settings shows CONFIG_ID as settings.config_id.
Code sessions explains environments.
Import a Code environment
Before you start: you need Manage Code (code.manage), which every person has. The repository must be public on GitHub. Use oo.
-
Import the repository as an environment:
oo code configs import https://github.com/owner/repository --name "Data tools" -
To let everyone in your Sunport use it, share it:
oo code configs edit CONFIG_ID --visibility sunport
import prints the environment with its CONFIG_ID. Without --visibility sunport, only you can use it.
Check it worked: oo code environments lists it.
oo code configs update CONFIG_ID takes its newest version, for new sessions only.Code sessions explains environments.
Stop a Code session's processes
Before you start: you must own the session. Use oo.
-
List what the session's commands still run on the machine:
oo code processes SESSION_ID -
Stop one, and what it started:
oo code processes SESSION_ID --stop 4321
Each process shows its PID, command, folder, start time and the ports it listens on. 4321 is a PID from the list. oo asks before it stops one.
Check it worked: oo code processes SESSION_ID no longer lists it.
Code sessions explains what a session leaves running.
Archive or delete a Code session
Before you start: you must own the session. Use oo.
-
Archive the session to keep it readable:
oo code archive SESSION_ID -
Or delete it for good:
oo code delete SESSION_ID
oo asks before it does either. Deleting can't be undone.
Check it worked: oo code list --filter archived lists an archived session. A deleted one is gone from oo code list.
oo code processes.Code sessions explains what each one keeps.
Chat apps
Connect an agent to Telegram
Before you start: you need Change agents (agents.update) and Start jobs (jobs.create) on the agent. Both come with Chat and settings, which an administrator gives on the agent's Access tab (Let people use an agent). The agent must run OpenClaw or Hermes.
- Open Agents and open the agent.
- On the Channels tab, under Connect a channel, set Channel to Telegram.
- Choose Open BotFather.
- In Telegram, send
/newbotto BotFather, and choose a name and a username. - Copy the token BotFather sends you.
- Paste it in Bot token and choose Connect.
Check it worked: Connected shows, with the bot's handle under it.
Chat apps explains who gets in.
Connect an agent to Slack
Before you start: you need Change agents (agents.update) and Start jobs (jobs.create) on the agent. Both come with Chat and settings, which an administrator gives on the agent's Access tab (Let people use an agent). The agent must run OpenClaw or Hermes.
- Open Agents and open the agent.
- On the Channels tab, under Connect a channel, set Channel to Slack.
- Choose Create the Slack app. Slack opens with the app filled in.
- In Slack, choose your workspace, then Next and Create.
- Choose Install to Workspace, then Allow.
- Under OAuth & Permissions, copy the Bot User OAuth Token (
xoxb-). - Under Basic Information › App-Level Tokens, generate a token with the
connections:writescope. Copy it (xapp-). - Paste them in Bot token and App-level token.
- Choose Connect.
Check it worked: Connected shows, with the bot's handle under it.
Chat apps explains who gets in.
Connect an agent to Discord
Before you start: you need Change agents (agents.update) and Start jobs (jobs.create) on the agent. Both come with Chat and settings, which an administrator gives on the agent's Access tab (Let people use an agent). The agent must run OpenClaw or Hermes.
- Open Agents and open the agent.
- On the Channels tab, under Connect a channel, set Channel to Discord.
- Choose Open the Developer Portal.
- In Discord, make a new application, named as the bot should appear.
- Under Bot, turn on Message Content Intent.
- Reset the token and copy it.
- Paste it in Bot token and choose Connect.
- Use the link the page then shows to add the bot to your server.
Check it worked: Connected shows, with the bot's handle under it.
Chat apps explains who gets in.
Connect an agent to Mattermost
Before you start: you need Change agents (agents.update) and Start jobs (jobs.create) on the agent. Both come with Chat and settings, which an administrator gives on the agent's Access tab (Let people use an agent). The agent must run OpenClaw or Hermes, and your Sunport must have its own Mattermost, a hosted app.
- Open Agents and open the agent.
- On the Channels tab, under Connect a channel, set Channel to Mattermost.
- If Make its bot on this Sunport's Mattermost shows, choose it. You're done.
- Otherwise, in your Sunport's Mattermost, open System Console › Integrations › Bot Accounts.
- Add a bot account and copy its access token.
- Paste it in Bot token and choose Connect.
Check it worked: Connected shows, with the bot's handle under it.
Chat apps explains who gets in.
Turn on iMessage
Before you start: you need Change agents (agents.update) and Start jobs (jobs.create) on the agent, signed in with your own account. Both come with Chat and settings, which an administrator gives on the agent's Access tab (Let people use an agent). The agent must run OpenClaw or Hermes, on a Sunport that offers iMessage.
- Open Agents and open the agent.
- On the Channels tab, in the iMessage card, choose Connect iMessage.
- Wait a few minutes while the agent restarts.
- When your code shows, choose Open in Messages on your phone, or text the code to the number shown.
Check it worked: the card shows On, and the agent replies to your text.
If your number is already linked, no code shows: just text the agent. Others who can open this card choose Link my number. Anyone who can use the agent can run oo agents imessage link.
Chat apps explains shared and dedicated numbers.
Buy an iMessage number
Before you start: you need to be an administrator, signed in with your own account, with Change billing (billing.write). An administrator can make you one. Free trials can't buy one.
- Open Agents and open the agent.
- On the Channels tab, in the iMessage card, find Dedicated iMessage number.
- Choose Get a number for Research, with your agent's name.
- Check the price, then confirm.
Check it worked: the number shows with Active.
Chat apps explains what a number costs.
Connect your WeChat to an agent
Before you start: you need Chat with agents (agents.chat) on an OpenClaw or Hermes agent, signed in with your own account. The Channels tab shows only with Chat and settings, which an administrator gives on the agent's Access tab (Let people use an agent). Your WeChat account must be registered in mainland China or Hong Kong.
- Open Agents and open the agent.
- On the Channels tab, in the WeChat card, choose Connect WeChat.
- Open WeChat on your phone and scan the code.
- Confirm in WeChat.
- If WeChat shows a number, enter it on the card and choose Continue.
- Write to the bot chat WeChat opens.
Check it worked: the card shows Connected, and the agent answers in WeChat.
Chat apps explains what reaches your WeChat.
Let someone message an agent
Before you start: you need Manage who can use agents (agents.access) and Start jobs (jobs.create) on the agent. Both come with Chat and settings, which an administrator gives on the agent's Access tab (Let people use an agent).
To add someone by email or user ID:
- Open Agents and open the agent.
- On the Channels tab, under Allowed users by channel, choose the app in Channel.
- In Provider User ID, type their email or their user ID on that app.
- Choose Add user, or Look up for an email.
- For an email, check the account found and choose Add this user.
To approve someone who messaged an OpenClaw agent's bot and got a pairing code:
- On the same tab, under Pairing requests & accounts, find their request.
- Choose Approve.
Check it worked: they show under the app in Allowed users by channel, or under Approved users.
Chat apps explains allowlists and pairing.
Let an agent answer in groups
Before you start: you need Manage who can use agents (agents.access) and Start jobs (jobs.create) on an OpenClaw agent. Both come with Chat and settings, which an administrator gives on the agent's Access tab (Let people use an agent).
- Open Agents and open the agent.
- On the Channels tab, under Allowed users by channel, find the app.
- Turn on Groups.
- In Turn on groups?, choose Turn on groups.
- In the chat app, add the bot to a group or channel.
Check it worked: someone on the allowlist mentions the bot in the group, and it answers.
/setprivacy to BotFather, choose the bot and Disable. Then remove the bot from each group and add it back.Chat apps explains groups and trusted groups.
Link your chat account
Before you start: you need your own sign-in. Without a Clem bot there, send /link to an agent's bot that lets you in.
- Open Settings › Profile.
- Under Chat accounts, choose Connect and the app, such as Connect Telegram.
- Message Clem on that app, as the page then shows.
- Open the link Clem sends you and press Accept.
Check it worked: Chat accounts lists the account as linked.
oo agents imessage link AGENT.Chat apps explains what a linked account can do.
Connect Clem to chat apps
Before you start: you must be an administrator, signed in with your own account. An administrator can make you one. Use a bot made for Clem alone.
- Open Agents and open Clem.
- On the Channels tab, under Connect a channel, choose the app in Chat app.
- Make the bot as the page shows, and paste its token in Bot token.
- Choose Connect.
- Message the new bot from your own account.
- Back on the page, choose Approve next to your account.
Check it worked: your account shows under Can message Clem, and Clem answers in the app.
Chat apps explains Clem's bots.
Release an agent's chat bot
Before you start: you need Change agents (agents.update) and Start jobs (jobs.create) on the agent. Both come with Chat and settings, which an administrator gives on the agent's Access tab (Let people use an agent). The agent must run OpenClaw or Hermes on its own VM. The dashboard has no release button, so use oo.
oo agents channels remove research telegramoo asks before it releases the bot. To give it to another agent, run oo agents channels add there with the bot's token.
Check it worked: oo exits 0 and prints the finished result.
Chat apps explains who owns a bot.