mirror of
https://github.com/nearai/ironclaw.git
synced 2026-09-02 23:56:24 +08:00
d27dba30f7
* fix(extensions): host-bundled description trust + already-connected install confirmation
Two chat-side dead-ends from the 2026-08-07 Slack QA session (thread
e79a994f, run 251aec0b on ironclaw-qa-testing-libsql):
1. Host-bundled capability descriptions were description_trust=Untrusted,
so the loop-tier prompt-text denylist strict-scanned compiled-in text
and silently omitted builtin.extension_register_hosted_mcp from every
model prompt's capability surface ("browser authorization-code flow"
matched the "authorization" credential pattern). HostBundled is the
only source eligible for effective FirstParty/System trust, so its
repo-authored descriptions now cross the verified-catalog boundary
like signature/digest-verified registry installs. Untrusted provenance
(InstalledLocal, UserRegistered, unknown) keeps the strict scan.
2. When install-driven activation passed the credential gate because the
caller's declared requirements were all satisfied, the response never
said so — the model got only conditional guidance ("If WebChat shows
an account connection panel...") and deflected an explicit "connect
account" request to the web interface even though the account was
already connected. The install response now appends an explicit
already-connected confirmation exactly when declared requirements
were verified present for the calling user.
Regression tests: manager surface test pins VerifiedCatalog trust for all
model-visible lifecycle capabilities through the real host runtime;
instruction-bundle tests pin retain/omit behavior for auth-vocabulary
descriptions by trust; install-path tests pin the confirmation on the
seeded-credential path and its absence for credential-free extensions.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* docs(channels): chat can drive the personal half of channel connect
The onboarding and channels pages claimed "asking the agent to connect a
channel doesn't work" and that the agent "may tell you it can't help".
That describes only the operator half (registering app/bot credentials).
The per-user half has shipped since early July: extension_install runs the
same activation credential gate as the Channels card, raises the in-chat
OAuth connection panel when the account is unconnected, and (as of the
sibling fix) confirms when it is already connected.
The self-knowledge protocol makes these pages the model's authority on
IronClaw's own capabilities, so the stale claim scripted the exact
refusal QA hit ("I can't initiate the Slack OAuth flow from here") on an
account that was already connected. Correct both pages to distinguish
the operator step from the chat-drivable personal connect.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* docs(channels): align slack and telegram setup notes with the connect contract
The slack page's operator-step note and the telegram troubleshooting
accordion still carried the blanket "asking the agent to connect will not
work" claim the overview/onboarding correction removed — same drift,
different phrasing (review catch on #7361, plus one more instance found
by a broader sweep). Both now state the two-step contract: the operator
half stays in the web interface; after it, chat drives the personal half
(install/activate -> in-chat connection or pairing panel, or an
already-connected confirmation).
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* test(golden): recapture surface digests over the description-trust change
The queue run failed golden_payload because the branch predated current
main and its own surface.rs trust fix changes the surface digest. The
recaptured snapshots differ ONLY in the surface sha256 lines (verified
char-by-char) — no prompt text or capability-list changes.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---------
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
146 lines
4.6 KiB
Plaintext
146 lines
4.6 KiB
Plaintext
---
|
|
title: "Overview"
|
|
description: "Reach your agent from a messaging app"
|
|
---
|
|
|
|
Channels let people reach your agent from somewhere other than the web interface. IronClaw
|
|
supports Slack and Telegram.
|
|
|
|
<CardGroup cols={2}>
|
|
<Card title="Slack" icon="slack" href="/channels/slack">
|
|
Talk to your agent in Slack channels and direct messages.
|
|
</Card>
|
|
|
|
<Card title="Telegram" icon="send" href="/channels/telegram">
|
|
Talk to your agent in Telegram direct messages and group chats.
|
|
</Card>
|
|
</CardGroup>
|
|
|
|
---
|
|
|
|
## How Channels Work
|
|
|
|
A channel is one capability surface of an extension. Installing the Slack or Telegram
|
|
extension gives your agent the ability to receive and send messages there; the extension's
|
|
manifest declares the channel surface alongside any tools it provides.
|
|
|
|
Setup happens in the [web interface](/using/webui). Start the server, connect the channel,
|
|
and the setup flow walks you through the credentials it needs and stores them encrypted.
|
|
|
|
```bash
|
|
ironclaw serve
|
|
```
|
|
|
|
<Note>
|
|
Channel credentials are stored in the encrypted secret store, not in `config.toml`. Your
|
|
configuration file names the environment variables that hold them, never the values
|
|
themselves. See [Security](/security).
|
|
</Note>
|
|
|
|
---
|
|
|
|
## Where Channel Setup Lives
|
|
|
|
This is the single most common thing to get stuck on, so it's worth being precise.
|
|
|
|
<Steps>
|
|
|
|
<Step title="Open Extensions, then switch to the Channels tab">
|
|
|
|
In the sidebar, open **Extensions**. It opens on the **Registry** tab.
|
|
|
|
<Warning>
|
|
Registry is *not* where channels are set up. Click across to the **Channels** tab. Using
|
|
**Configure** on a channel from the Registry tab leads to a dead end — see below.
|
|
</Warning>
|
|
|
|
</Step>
|
|
|
|
<Step title="Scroll to the bottom of the Built-in section">
|
|
|
|
The Channels tab opens with a **Built-in** panel. The Slack and Telegram connect cards are
|
|
at the **bottom of that panel**, below the rows for the web and terminal channels. They're
|
|
easy to miss on a short window — scroll.
|
|
|
|
</Step>
|
|
|
|
<Step title="Use Configure on the channel's card">
|
|
|
|
That card is the real setup surface. For Telegram it's where an operator enters the bot
|
|
token; for Slack it's where the app credentials go.
|
|
|
|
</Step>
|
|
|
|
</Steps>
|
|
|
|
### Two Dead Ends to Know About
|
|
|
|
<AccordionGroup>
|
|
|
|
<Accordion title="Configure on the Registry tab errors instead of setting up">
|
|
|
|
Telegram appears in the Registry tab, and its **Configure** button opens the *pairing*
|
|
panel. Pairing assumes the bot is already configured, so if it isn't, the only thing that
|
|
surface can do is report:
|
|
|
|
```
|
|
An administrator must configure the Telegram bot first.
|
|
```
|
|
|
|
That message is accurate but misleading — it reads like you lack permission. Nothing is
|
|
wrong with your account. Go to the **Channels** tab and use the card at the bottom of the
|
|
Built-in section instead.
|
|
|
|
</Accordion>
|
|
|
|
<Accordion title="Asking the agent to connect only works after the operator step">
|
|
|
|
"Connect Slack" in chat does work for the *personal* half of setup: the agent installs
|
|
and activates the extension, and if your account still needs OAuth an in-chat connection
|
|
panel opens right there — the same OAuth flow the Channels card runs. If your account is
|
|
already connected, the agent confirms that and continues with your request.
|
|
|
|
What the agent cannot do is the *operator* half — registering the Slack app or Telegram
|
|
bot credentials for the whole instance. That step is deliberately kept out of the tools
|
|
the agent can drive, so it stays in the web interface where you can see what you're
|
|
authorizing. If chat setup dead-ends, complete the operator step using the path above
|
|
first, then ask again.
|
|
|
|
</Accordion>
|
|
|
|
</AccordionGroup>
|
|
|
|
<Info>
|
|
Telegram has **two** setup steps that are easy to confuse: an operator configures the bot
|
|
token once for the whole instance, and then each person pairs their own Telegram account
|
|
to their IronClaw user. The "administrator must configure" error means step one hasn't
|
|
happened yet.
|
|
</Info>
|
|
|
|
---
|
|
|
|
## Receiving Messages
|
|
|
|
Both channels deliver events by webhook, so the messaging platform needs to reach your
|
|
IronClaw instance over HTTPS. On a laptop behind NAT that means either a public host or a
|
|
forwarding service; a served deployment already has a reachable URL.
|
|
|
|
Each channel's page covers the exact callback URL to register.
|
|
|
|
---
|
|
|
|
## Not Using a Channel?
|
|
|
|
You don't need one. The [web interface](/using/webui) and the terminal both talk to the
|
|
same agent:
|
|
|
|
```bash
|
|
ironclaw repl
|
|
ironclaw run -m "What's on my calendar today?"
|
|
```
|
|
|
|
<Info>
|
|
Discord, Signal, WeChat, and WeCom were available in IronClaw v1 and are not part of the
|
|
1.0 release. If you depend on one of them, stay on v1 until it returns.
|
|
</Info>
|