OneBot is a multi-protocol bot driven by feature plugins. It's primary purpose is for chatting, but it's flexible enough to be used for a variety of things.
OneBot is powered by plugins, this will be a list of features and what plugins provide them.
OneBot can connect to, read, and send messages on the following protocols:
OneBot supports the following plugins and features. This section will also list commands provided by the plugins. A command for parrot
for example is say
, and the default command prefix is ,
. So if a user typed ,say Hello World!
the bot would reply with Hello World!
.
8ball <question>
/ 8b <question>
bash
comic
ladder.D2DV
file to display formatted leaderboards for various difficulties.d2xp [count]
d2 [count]
d2hc [count]
d2xphc [count]
d2all [count]
roll [sides]
/ r [sides]
fc
/ fact
ipfs-check <multiaddr> <CID> [Backend URL]
ipfs-findprovs <CID>
ipfs dht findprovs <CID>
on a local Kubo node, returning the result if possible.ipfs-stat <CID>
ipfs block stat <CID>
on a local Kubo node, returning the result if possible.web3-help
web3-store <cid>
bal [ID]
/ balance [ID]
cute
chill
meme
risk
dep <amount / all>
/ deposit <amount / all>
withdraw <amount / all>
alias <UID>
unalias
confirmalias <UID>
leaderboard
/ lb
say [text]
/ s [text]
rev [text]
/ r [text]
q <question>
/ question <question>
stats [yyyy-mm]
roleid <role>
addtrigger <messageID> <emoji> <@role>
/ at <messageID> <emoji> <@role>
removetrigger <messageID> <emoji>
/ rt <messageID> <emoji>
In your terminal run the follow commands as an unprivileged user in their home folder:
wget https://github.com/TheDiscordian/onebot/releases/latest/download/onebot-linux64.tar.xz
tar -xf onebot-linux64.tar.xz
mv bin/release ./onebot
rmdir bin
OneBot will now be located in the onebot
directory.
OneBot looks in the current directory for a config file named onebot.sample.toml
by default, copy it to onebot.toml
with cp onebot.sample.toml onebot.toml
. Open onebot.toml
using your favourite text editor (if you're very new to shells, try nano onebot.toml
). You should see the following at the top:
[general]
default_prefix = ","
default_nickname = "OneBot"
You'll want to set these to what you want the command prefix to be, and the default nickname. The command prefix is used for invoking commands for example if it's ,
you could use the parrot
plugin by saying ,say Hello World!
. The nickname should be whatever you want the bot to be nicknamed (or what it's already nicknamed). This isn't extremely important, but if it's wrong some plugins may misbehave.
In onebot.toml
, head down to the line defining the protocol plugins, it should look something like this:
protocols = ["matrix", "discord", "bluesky"]
Edit this to only contain protocols you want to use.
The Matrix config section looks like this:
[matrix]
# for example: https://matrix.org
home_server = ""
# if using auth_token, it must be in "@username:homeserver" format
auth_user = ""
# if blank, falls back onto auth_pass
auth_token = ""
# if set, this will be used to retrieve an auth token, then the password can be omitted from this file
auth_pass = ""
It's pretty self-explanatory. You set the homeserver of the bot, just like you would on a Matrix client. You set your username also as you normally would. If you have an auth_token
, you can set that here too. If you don't have one, you can set auth_pass
instead. Once the bot successfully logs in once it will store an auth_token
in it's database, so you can remove the password from this file after.
The Discord config section looks like this:
[discord]
# is set as "Bot auth_token"
auth_token = ""
# id of admin user (for certain plugins like 'roletriggers')
admin_id = ""
You can get an auth_token
for the bot from the Discord Developer Portal (if you don't know how, check out this guide).
admin_id
isn't required, but can be helpful for plugins like roletriggers
. ID here would be a Discord UID of the admin user.
The Bluesky protocol is pretty new, and only supports https://bsky.social
as a PDS for now, but this is expected to change in the near future. It's section looks like this:
[bluesky]
# The handle on Bluesky of the account to use
handle = ""
# The password of the Bluesky account
password = ""
# The number of posts to fetch at once per poll
feed_count = 50
# The number of seconds to wait in between polls
feed_freq = 10
# The number of seconds to wait in between syncing followers
follow_freq = 60
The only required fields are handle
and password
. They're pretty self-explanatory, if you login with discordian.ca
, you use discordian.ca
as your handle. The password is your password (app passwords work too).
OneBot polls the PDS for new posts, and to check if it has any new followers. OneBot only sees posts by people it follows and will automatically follow anyone who follows it. The defaults should be fine for most people, however you're free to adjust these settings as much as your PDS allows.
The simplest way to run OneBot after configuration is simply to run the binary:
cd ~/onebot
./onebot
However if you'd like OneBot to persist outside of just this terminal session, then I highly recommend using tmux
. Install tmux, ensure OneBot isn't running, then try the following:
tmux
cd ~/onebot
./onebot # run the bot
CTRL+b, d
That last bit is saying "Press CTRL+b, release the keys, then press the d key". This will background a tmux shell, if you want to return to it at any time, ensure you're on your user account and run tmux attach
.
Get the source code with git clone https://github.com/TheDiscordian/onebot.git
Build the bot with make build
.
Run the bot with make run
.
Build everything and run with make dev
. Note: This will also trigger tools/updatelicense.py
, which is a recursive function.
Build the plugins via make plugins
and make protocols
. This will build all the plugins in the plugins directory, and all the protocol plugins in the protocols directory.
Check code correctness via make check
. Note: This tool outputs suggestions, make sure to ask before making changes to already comitted code based on these guidelines.