mirror of
https://github.com/nearai/ironclaw.git
synced 2026-09-02 23:56:24 +08:00
d4fa8e1f60
* feat(extensions): add per-field help text to admin configuration forms Manifest [admin_configuration] fields gain an optional `description` that renders as a hint under each input on the WebUI Admin -> Configuration form, so operators see what each value is and where it comes from while filling the form. Threaded additively through every layer: - registry: `AdminConfigurationField.description` (serde default — every existing manifest and persisted resolved record parses unchanged) - extension host: carried on `AdminConfigurationFieldState` redacted views - assistant: `RebornAdminConfigurationField.description` on the wire, omitted when empty - extension manager: mapped through the admin-configuration view provider - webui frontend: rendered under the input in configuration-tab.tsx The telegram manifest is the first consumer: one hint per field (BotFather token, invent-your-own webhook secret with the allowed charset, full webhook URL with local-tunnel pointer, @-less bot username), and the group description shrinks to a summary plus the tunnel note. Coverage at each seam: manifest v3 contract (declared description survives resolution, undeclared resolves empty), host service contract (help text reaches the redacted view), manager view unit test (passthrough beside the secret-redaction guard), frontend vitest (hint renders), and the webui_v2_product_api integration test asserts every telegram field carries non-empty help text on the wire through the production stack. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * docs(channels): rewrite channel setup for the Admin -> Configuration flow The Telegram and Slack pages, the channels overview, and the onboarding page still taught the retired "Extensions -> Channels tab -> scroll to the bottom of the Built-in section -> Configure" flow. Deployment credentials now live under Admin -> Configuration, with the extension card's Configure handling only the personal half (pairing / OAuth). - telegram.mdx: setup rewritten around Admin -> Configuration with a table for all four fields; new step with an ngrok walkthrough for local installations (static domain, exact webhook URL, hostname-rotation note); troubleshooting covers stale tunnel hostnames and fail-closed activation. - slack.mdx: operator step now points at the Slack deployment configuration card; stale "can't find where to configure" answer fixed. - overview.mdx + onboard.mdx: setup taught as two halves (operator deployment config vs personal pairing), dead-end guidance updated. - zh mirrors of telegram and the overview updated to match. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * fix(webui): address review findings on admin-config field help Applies three CodeRabbit findings on #7550: - a11y: the field help paragraph gets a stable id and the input references it via aria-describedby, so assistive technology reads the guidance with the control; fields without help text carry no dangling reference (asserted both ways in configuration-tab.test.ts). - docs: the ngrok walkthrough now uses the current free-plan syntax — `ngrok http 3000` with the automatically assigned development domain — instead of the deprecated `--domain` flag and the retired claim-a-name flow; paid-plan reserved domains use `--url`. zh mirror updated. - test: the integration wire assertion now pins each Telegram handle to a distinctive fragment of its own manifest help text (plus a field-count guard), so a description copied across fields or attached to the wrong handle fails even though all four are non-empty. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * style(extensions): keep the description field doc at its schema owner only The pass-through copies on AdminConfigurationFieldState and the wire DTO restated the field name and broke their structs' undocumented-sibling idiom; the empty-means-undeclared convention lives once, on the registry schema. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> --------- Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
140 lines
4.5 KiB
Plaintext
140 lines
4.5 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.
|
|
Channel setup has two halves, done in two different places:
|
|
|
|
<Steps>
|
|
|
|
<Step title="Operator half: Admin → Configuration (once per instance)">
|
|
|
|
In the sidebar, open **Admin**, then **Configuration**. Each channel that needs
|
|
deployment credentials shows a configuration card there — **Telegram deployment
|
|
configuration**, **Slack deployment configuration**, and so on. Fill in the card's
|
|
fields and save. The values are stored in the encrypted secret store.
|
|
|
|
This is the half the whole instance shares: the Telegram bot token and webhook
|
|
settings, the Slack app credentials.
|
|
|
|
</Step>
|
|
|
|
<Step title="Personal half: Extensions (each person)">
|
|
|
|
Open **Extensions**, install the channel's extension, and use **Connect** /
|
|
**Configure** on its card. For Telegram this opens the *pairing* panel that links your
|
|
Telegram account to your IronClaw user; for Slack it runs your personal OAuth
|
|
connection. You can also just ask the agent in chat — it drives this half for you.
|
|
|
|
</Step>
|
|
|
|
</Steps>
|
|
|
|
### The One Dead End to Know About
|
|
|
|
<AccordionGroup>
|
|
|
|
<Accordion title='"An administrator must configure the Telegram bot first"'>
|
|
|
|
The pairing panel assumes the deployment configuration is already saved. 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. Complete the operator half under **Admin → Configuration**
|
|
first, then pair.
|
|
|
|
</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 or pairing an
|
|
in-chat connection panel opens right there. If your account is already connected, the
|
|
agent confirms that and continues with your request.
|
|
|
|
What the agent cannot do is the *operator* half — the deployment credentials under
|
|
**Admin → Configuration**. 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 first, then ask again.
|
|
|
|
</Accordion>
|
|
|
|
</AccordionGroup>
|
|
|
|
<Info>
|
|
Telegram has **two** setup steps that are easy to confuse: an operator saves the
|
|
deployment configuration 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>
|