Identities
An identity is a person your gateway knows by name, for exampleAlice. The person and their
linked accounts live in one place in the gateway config:
identity fields, and cross-channel DM session merging. The values are
provider-prefixed channel identities: telegram:<id>, discord:<id>, oauth:<provider>:<subject>
and so on. Devices are not listed here: a paired device’s person is recorded on its pairing record
(see Conflicts and devices).
You never edit that map by hand. Every proof of control ends in one core link operation, exposed as
the identity CLI commands and the gateway identity.* RPCs, that writes the config for you.
Creating an identity
Added identity Alice., or Alice already exists. if the name is taken. Names allow
letters, digits, ., _ and -, up to 64 characters. The names prototype, constructor and
__proto__ are reserved and refused, as is the raw~ prefix (it marks contained unlinked-sender
session buckets).
Identities are never created implicitly. Every linking flow below, wednesdayai qr --identity,
pairing approve --identity and oidc invite, resolves an existing name first and fails on a
typo, so a misspelling cannot mint a person.
Proofs of control
A link value joins a person only after someone proves control of it. There are four proofs:1. Operator QR (web client)
Alice in one step; no devices link
follow-up is needed. With --qr you can also pass --setup-code-only, --no-ascii and --json
to identity link.
Once at least one identity exists, wednesdayai qr --client openclaw-user-client refuses to issue
a bootstrap without --identity:
2. Operator channel-pairing approval
telegram:<id> to Alice. If the link write
fails, the approval stands and the command prints the exact follow-up:
3. Self-service link code
A person links their own chat account without operator involvement:-
In a direct message to the bot, the person sends
/link. -
The bot replies with an 8-character code, valid for one hour, single use (at most 3 pending per
channel):
- A person who is already linked opens the web client, chooses Account menu → Linked accounts and enters the code.
<channel>:<id> to the linked person’s identity and
approves the pairing code, so a linked person can vouch for their own chat account when the channel
runs dmPolicy: "pairing". The code grants nothing on its own: sending /link only queues a
request, and the claimant must already be a linked person on a paired browser. Only codes issued
by /link are claimable: the code a stranger receives from the ordinary dmPolicy: "pairing" reply
is not, so admitting a new sender stays an operator decision (wednesdayai pairing approve).
The web client shows these errors:
- Unknown or expired code:
That code isn't valid or has expired. - Too many attempts:
Too many attempts. Try again in a few minutes.(5 attempts per device and 15 per person per minute, then a 5-minute lockout) - Conflict:
That account is already linked to someone else. Ask your administrator.
4. OIDC sign-in
With the bundledidentity-oidc plugin enabled, a person signs in with Google, Microsoft Entra or
GitHub; a provider-verified invite links the sign-in to the person and enrolls the browser. See
Identity OIDC.
Listing and unlinking
identity unlink <value> removes the value from every identity and prints
Unlinked telegram:123456789 from Alice., or telegram:123456789 is not linked. It refuses
device: values: unlinking a device deregisters it, which is wednesdayai devices unlink.
Conflicts and devices
A chat or OAuth value belongs to exactly one person. Linking a value another person already owns is refused withidentity_link_conflict:
"123" still owns
telegram:123. Link-code claims are serialized per claimed value, so two people redeeming codes
for the same sender cannot interleave their ownership check, link and approval.
Devices are linked with their own command. identity link refuses device: values and points you
at the device command:
owner_person column of pairing_devices in the session database), not in session.identityLinks.
wednesdayai devices link <deviceId> --identity <name> sets it once; linking the same person again
is a no-op, and a device another person owns is refused. The only rebind path is deregister then
re-pair: devices remove or devices unlink (they are the same: the device’s pairing record, its
tokens and its person go together, then its connections close), then pair again, which creates a
new device record, even for the same person. A setup code bound to a different person cannot
rebind a paired device either (bootstrap_device_owned). Node-only devices have no person and are
never linked.
device: values in session.identityLinks confer nothing. On startup the gateway moves each
one for a paired device that is not node-only onto that device’s record (a device listed under
several people goes to the first, the person it resolved to before), logs and skips the rest, and
strips them all from the config. config.set, config.patch and
config.apply refuse a write that adds one (DEVICE_LINK_VALUE_REFUSED). The
Control UI v2 console can link a paired device to a person or unlink
(deregister) it from the Nodes & devices page (Fleet group), over the device.identity.link
and device.identity.unlink RPCs (both need operator.admin). See devices.
What a linked device can see
Linking a device to a person also limits what that device sees. A connection withoutoperator.admin whose device is linked to a person receives chat and agent events, node pushes
(for example on WednesdayAI Glass), chat.history, chat.send and sessions.list only for:
- conversations that person owns: a direct conversation belongs to the person who started it, or to the first linked person who chats in it, and never changes hands after that; and
- conversations nobody owns, such as the shared main session, group chats and cron sessions.
session not found. Connections with operator.admin and
operator or web devices linked to nobody keep full visibility, so a single-person install behaves
as before. A linked node (a device connected as a node and linked to a person) sees that person’s
conversations and the shared ones. A node install linked to nobody has no person: it gets only
sessions nobody owns. Other session methods (for example sessions.describe or sessions.patch)
are not limited yet.
Each sign-in is its own device. When two people sign in to the web client from the same browser,
each sign-in pairs a separate device linked to that person, and each connection sees only its own
person’s sessions. A connection keeps the person it signed in as: if its device is later linked to
someone else, that open connection stops seeing either person’s sessions until it signs in again.
A message from that connection is refused if it reaches the gateway’s admission check after the
relink; a message admitted before the relink still runs. A conversation stays with its owner: a
message sent into it from an admin connection or an unlinked device does not change who owns it,
and the reply is delivered only to the owner’s devices (and to the sender). Resetting a session
(/new) starts a new conversation; the old one keeps its owner. If a message is refused because
its conversation now belongs to someone else, only the sender gets “session changed, retry”.
Unlinking or removing a device (devices unlink, devices remove, or Log out in the web
client) also closes that device’s open connections, including one that was still connecting. It
reconnects as whatever it is then paired and linked as.
A WednesdayAI app device’s companion browser (ADR 2242) always stays with the app’s person:
unlinking or removing the app removes its companions, a companion itself cannot be linked to a
different person, and a companion setup code redeemed by a device another person already owns is
refused with bootstrap_device_owned (see
Device companions and device.self).
Gateway RPCs
The CLI talks to the same gateway methods every client uses:
The narrow methods read the verified device id from the connection, never from the request body, so
a caller can only act on its own device and person. See Protocol for the scope
model.
What logout does
Log out in the web client asks the gateway to runidentity.logout (waiting up to 3 seconds),
then always clears the browser’s own credential and keypair. When the call reaches the gateway it:
- deregisters the paired device server side: its pairing record, tokens and person go together, then its connections close.
- removes any companion devices it issued (a WednesdayAI app device’s browser companions).
wednesdayai devices remove <deviceId>. The next sign-in pairs a fresh device. The
keypair is rotated because a paired browser belongs to one person: keeping it would let the next
person inherit the previous person’s device.
A #setup=<token> link (an enrollment bootstrap) that arrives at a browser which is already paired
is never redeemed automatically. The web client shows a confirmation naming the consequence, and
only after you confirm does it log the current device out and re-pair under the new identity. On a
browser with no stored credential, redemption is automatic. Every redemption pairs a fresh
keypair: an orphaned one (its token was cleared but the keypair remained) is rotated, and when
another gateway’s credential on the same origin still uses the browser’s keypair, the new pairing
gets a keypair of its own instead, so neither pairing is broken.
The web client’s person always comes from the device credential its own sign-in minted, never from
a per-browser link: every sign-in pairs a new device, and logout forgets it. A setup code for
another person therefore cannot rebind a paired browser; the gateway refuses it, which is why the
confirmation logs the browser out first.
The account-linking switch
gateway.webClient.accountLinking (default true) gates the self-service path. Set it to false
to keep all linking operator-only: /link replies
Account linking is turned off on this gateway. and identity.link.claim refuses with the same
copy. Operator commands (identity add/link/unlink, devices link, pairing approve) are
unaffected.
Reserved-name errors
A legacy config that still holds a reserved key blocks identity mutations until it is renamed:openclaw.json is a one-time migration fix, not part of enrollment: normal
enrollment never needs a hand edit.