菜单
Add an embedded HTTP + WebSocket chat server with PWA frontend. Provides a web chat interface for talking to NanoClaw agents from the browser, with bearer / tailscale / proxy-header auth and Web Push.
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
基于 SOC 职业分类
Build and publish a website. Use whenever the user asks to make, create, build, or publish a website, landing page, dashboard, status page, one-pager, or anything else a human will load in a browser. Covers both the publish recipe (no tunnels, no third-party hosts) and the design discipline that keeps the result from looking like generic AI slop.
Use for Clemson GC curriculum content questions — what a specific course teaches, what skills or projects it includes, what assignments are used, where a topic or learning outcome is covered, and how courses relate to each other pedagogically. This is about course *content*, not degree rules or credit requirements (use gc-advisor for those).
Use for ANY Clemson procurement or purchasing question — what's allowed or required, policy, rules, P-card, requisitions, purchase orders, suppliers, approvals, spending limits, bids/quotes. Use the procurement tools; never answer Clemson procurement from your own knowledge.
Use for Clemson class schedules and instructor scheduling — finding course sections, what an instructor is teaching, section details (time/seats/location), room availability, and academic terms. Use these tools, not your own knowledge.
Use for questions about Clemson Graphic Communications alumni outcomes — where graduates work now, first-job placement, career trajectories, AI exposure of GC occupations, industry/occupation distribution, grad-school rates, and outcome trends by graduation cohort. Data comes from the gc-alumni MCP server (read-only SQLite). For degree rules or course content use gc-advisor or clemson-curriculum instead.
Use for Clemson GC degree rules and academic requirements — degree audit (which requirements has a student met?), credit counts, gen-ed rules, specialty-area rules, prerequisite checking, course planning, and academic regulation lookups. This is about *rules and requirements*, not course content or pedagogy (use clemson-curriculum for what a course teaches, its skills/projects/assignments). Always pulls from the pinned catalog database — never from memory or the live website.
| name | add-webchat |
| description | Add an embedded HTTP + WebSocket chat server with PWA frontend. Provides a web chat interface for talking to NanoClaw agents from the browser, with bearer / tailscale / proxy-header auth and Web Push. |
Adds an in-process chat server + PWA. Runs on its own port (default 3100); doesn't share with webhook-server. The PWA talks to v2's agent groups via webchat-owned room metadata, and pipes inbound chat through the standard channel-adapter path so the existing router / sessions / outbound delivery flow handles it like any other channel.
Webchat layers on top of a working v2 install — it does not replicate /setup. Before installing, make sure these are in place. (/setup handles all of them; if you ran /setup end-to-end, skip this section.)
Per-checkout container image is built. v2 names the agent image nanoclaw-agent-v2-<sha1(projectRoot)[:8]>:latest so multiple installs can share a docker daemon. Without it, every session wake fails with pull access denied for nanoclaw-agent-v2-... (exit 125) and the agent never replies.
./container/build.sh
docker images | grep nanoclaw-agent-v2- # confirm the image exists
A credential path for the agent container. Either OneCLI or the native credential proxy must be configured so containers can authenticate to the LLM provider. Webchat will boot and accept messages without it, but every spawn will land in outbound.db empty (the agent-runner exits with no credentials).
ONECLI_URL in .env to your local gateway (typically http://172.17.0.1:10254). If ONECLI_URL is unset, the SDK defaults to https://app.onecli.sh (the cloud) and 401s. Verify with curl ${ONECLI_URL}/api/agents./use-native-credential-proxy and set ANTHROPIC_API_KEY (or CLAUDE_CODE_OAUTH_TOKEN) in .env.pnpm run dev doesn't auto-load .env in v2 trunk. If you're running the host in dev mode, export the env first: set -a; source .env; set +a; pnpm run dev. launchctl / systemd aren't affected (they pass env directly).
NanoClaw doesn't ship channel adapters in trunk. This skill copies the webchat module from the skill's own add/ directory (the adapter is self-contained and doesn't ship on the channels branch — there's no Chat SDK package to wrap).
Skip to Configure if all of these are already in place:
src/channels/webchat/index.ts existssrc/channels/index.ts contains import './webchat/index.js';src/db/migrations/index.ts: moduleWebchat, moduleWebchatDropRooms, moduleWebchatRoomPrimes, moduleWebchatModels, AND moduleWebchatApprovalsIndexws, busboy, web-push, AND undici are listed in package.json dependenciescontainer/agent-runner/src/destinations.ts contains the webchat:send-file-hint START sentinel (step 7 patch applied)src/modules/agent-to-agent/create-agent.ts contains the webchat:create-agent-gating START sentinel (step 6 patch applied)Otherwise continue. Every step below is safe to re-run.
-n skips files that already exist so re-running install won't clobber local edits to the channel module.
mkdir -p src/channels/webchat
cp -n .claude/skills/add-webchat/add/src/channels/webchat/*.ts src/channels/webchat/
mkdir -p src/modules/agent-to-agent
cp -n .claude/skills/add-webchat/add/src/modules/agent-to-agent/*.ts src/modules/agent-to-agent/
The src/modules/agent-to-agent/ copy is create-agent.test.ts — the
test for the auth gate that step 7 patches into create-agent.ts. It's
ineffective without that patch.
If you've intentionally changed a channel file and want install to refresh it from the skill, drop
-n.
mkdir -p public/webchat
cp -rn .claude/skills/add-webchat/add/public/webchat/. public/webchat/
grep -q "channels/webchat/index.js" src/channels/index.ts \
|| echo "import './webchat/index.js';" >> src/channels/index.ts
Edit src/db/migrations/index.ts. Skip each addition if it's already present — running install twice will otherwise produce a duplicate-import / unused-import error from tsc and break the build.
Add this import alongside the others (skip if grep -q "channels/webchat/migration" src/db/migrations/index.ts already matches):
import {
moduleWebchat,
moduleWebchatDropRooms,
moduleWebchatRoomPrimes,
moduleWebchatModels,
moduleWebchatApprovalsIndex,
} from '../../channels/webchat/migration.js';
And add all five symbols to the migrations array (skip individual entries that are already present — any position is fine, order is determined by name uniqueness, not array index):
const migrations: Migration[] = [
// ... existing entries
moduleWebchat,
moduleWebchatDropRooms,
moduleWebchatRoomPrimes,
moduleWebchatModels,
moduleWebchatApprovalsIndex,
];
pnpm add ws@8.20.0 busboy@1.6.0 web-push@3.6.7 undici@7.16.0
pnpm add -D @types/ws@8.18.1 @types/busboy@1.5.4 @types/web-push@3.6.4
undici is required by drafter.ts for ProxyAgent — it routes the
agent-drafter LLM call through the OneCLI proxy. Node's built-in fetch
uses undici internally but doesn't expose ProxyAgent, so the explicit
package is needed. Undici ships its own TypeScript types — no
@types/undici required.
create_agent with an owner/admin auth gateThe agent-to-agent create_agent action lets one agent spawn another.
Without this gate, any authenticated user who can drive an agent
(via webchat or any other channel) can cause that agent to spawn
arbitrary new agents — privilege escalation. The gate reads the trusted
senderId from inbound.db (host-owned) and rejects unless the
requesting user is owner, admin-of-this-group, or a CLI client (Unix
socket carve-out).
The patch is sentinel-bounded and reversible. REMOVE.md calls the
inverse script.
node .claude/skills/add-webchat/install/patch-create-agent.mjs
Idempotent (safe to re-run; detects the sentinel and exits 0). Fails
loud if trunk's create-agent.ts has been reformatted upstream — in
that case re-pull main and re-run, or update the script's anchors.
Requires the permissions module (src/modules/permissions/) to be
present — it provides isOwner and hasAdminPrivilege. SKILL.md's
pre-flight already calls this out as a prerequisite for webchat.
The webchat PWA inline-renders attachments (image previews, PDF previews,
syntax-highlighted code). Without a small prompt nudge, agents tend to
describe files in prose instead of calling send_file — which works but
the file feature goes unused. This step patches container/agent-runner/ src/destinations.ts to add the hint when at least one destination is a
chat surface. The patch is sentinel-bounded and reversible — REMOVE.md
calls the inverse script.
node .claude/skills/add-webchat/install/patch-destinations.mjs
Idempotent (safe to re-run; detects the sentinel and exits 0). Fails loud
if trunk's destinations.ts has been reformatted upstream — in that case
re-pull main and re-run, or update the script's anchors.
pnpm run build
Build must be clean before continuing.
The destinations.ts patch lives in agent-runner code which gets baked
into the agent container image. Without this rebuild, running agents
keep using the un-patched destinations section until their next image
refresh.
./container/build.sh
Re-running this section is safe if every variable you add follows the idempotent pattern shown below. Running install twice will otherwise duplicate lines in
.env(most env loaders take the last write, so this is benign — but ugly). When following the snippets below, prefer thegrep -q ... || echo ... >> .envform over copy-paste.
The server is disabled by default. Enable it now:
grep -q '^WEBCHAT_ENABLED=' .env || echo 'WEBCHAT_ENABLED=true' >> .env
STOP — you must ask this before proceeding. Use AskUserQuestion:
"Should the chat server be accessible from other devices on your network, or only from this machine?"
Options:
Do NOT skip this question or assume localhost.
No further configuration needed.
WEBCHAT_ENABLED=true
# WEBCHAT_PORT=3100 # default
# WEBCHAT_HOST=127.0.0.1 # default
⚠️ Reverse-proxy gotcha. Localhost-only does not protect against fronting reverse proxies that forward to
127.0.0.1— Tailscale Serve, nginx, Caddy, oauth2-proxy, Cloudflare Tunnel. If you have one of those exposing this host, every request lands at webchat as if it came from loopback. Two safe options: (a) tear down the forward (e.g.tailscale serve --https=443 off), or (b) configureWEBCHAT_TOKEN/WEBCHAT_TAILSCALE/WEBCHAT_TRUSTED_PROXY_IPS— once any explicit auth method is set, the loopback auto-pass is disabled and the proxy must surface the upstream identity. Quick check:tailscale serve statusandss -tlnp | grep -v 127.0.0.1from this host.
The server refuses to start when bound to a non-loopback host without at least one explicit auth method. Pick one or more:
Bearer token (works everywhere):
python3 -c "import secrets; print(secrets.token_urlsafe(32))" # generate a token
WEBCHAT_ENABLED=true
WEBCHAT_HOST=0.0.0.0
WEBCHAT_TOKEN=<generated-token>
Tell the user to save the token — they'll need it the first time they connect.
Tailscale (zero-config for tailnet users):
WEBCHAT_ENABLED=true
WEBCHAT_HOST=0.0.0.0
WEBCHAT_TAILSCALE=true
The server runs tailscale whois against the remote IP and uses the email as the user identity (webchat:tailscale:<email>).
Heads up — same-machine localhost won't work in this mode. With
WEBCHAT_TAILSCALE=trueset, the loopback auto-pass is disabled (it has to be — see the reverse-proxy gotcha above), andtailscale whois 127.0.0.1returns no identity. So even from this host, the PWA must be opened by tailnet hostname or IP, not127.0.0.1. Bookmarkhttp://<your-tailnet-hostname>:3100/(e.g. via MagicDNS) orhttp://$(tailscale ip -4):3100/. Curl from the local shell needs the same —curl http://127.0.0.1:3100/...returns 401.
Reverse-proxy header (for SSO via oauth2-proxy, Cloudflare Access, Azure EasyAuth, etc.):
WEBCHAT_ENABLED=true
WEBCHAT_HOST=0.0.0.0
WEBCHAT_TRUSTED_PROXY_IPS=10.0.0.5 # explicit IP/CIDR (recommended)
# WEBCHAT_TRUSTED_PROXY_IPS=auto # auto-detect Azure / Cloudflare
# WEBCHAT_TRUSTED_PROXY_HEADER=x-forwarded-user # default; override if needed
Identity comes from the asserted header (webchat:<header-value>). With auto, Azure EasyAuth (x-ms-client-principal-name) and Cloudflare Access (cf-access-authenticated-user-email) are detected first.
Provide a cert + key to serve over HTTPS:
WEBCHAT_TLS_CERT=/path/to/fullchain.pem
WEBCHAT_TLS_KEY=/path/to/privkey.pem
Generate and persist a VAPID key pair now. Without this the PWA shows a server missing VAPID key warning the moment it tries to subscribe — every fresh install hits it, so do this by default rather than leaving it for later.
The block below is idempotent: it skips if WEBCHAT_VAPID_PUBLIC_KEY is already set, so re-running install won't rotate the keys (which would invalidate every existing browser subscription).
if ! grep -q '^WEBCHAT_VAPID_PUBLIC_KEY=' .env; then
KEYS=$(pnpm exec web-push generate-vapid-keys --json)
PUB=$(echo "$KEYS" | python3 -c 'import json,sys; print(json.load(sys.stdin)["publicKey"])')
PRIV=$(echo "$KEYS" | python3 -c 'import json,sys; print(json.load(sys.stdin)["privateKey"])')
echo "WEBCHAT_VAPID_PUBLIC_KEY=$PUB" >> .env
echo "WEBCHAT_VAPID_PRIVATE_KEY=$PRIV" >> .env
fi
The subject is a mailto: URL the push service can use to contact you about deliverability problems. Ask the user for an email — AskUserQuestion: "Email address for VAPID subject (where push services should reach you about deliverability)?" — and write it in:
SUBJECT_EMAIL="<answer>"
grep -q '^WEBCHAT_VAPID_SUBJECT=' .env || echo "WEBCHAT_VAPID_SUBJECT=mailto:${SUBJECT_EMAIL}" >> .env
To opt out of push entirely, leave all three keys empty — the rest of the chat server works regardless, and the PWA's push button stays disabled cleanly.
mkdir -p data/env && cp .env data/env/env
The first authenticated user becomes the owner automatically (one-time grant, persisted in user_roles). Owner can:
POST /api/agentsCLAUDE.local.mdSubsequent users have no role. The owner can grant admin (global or scoped to a specific agent group) to others — admins of agent group X manage X but not others. This works automatically because v2's command-gate.ts and the webchat admin endpoints both consult user_roles via hasAdminPrivilege(userId, agentGroupId).
When the permissions module is not installed, the gate degrades to "single trusted operator" — anyone with bearer / tailscale / proxy access has full control. To get the full role model, install permissions before webchat.
Restart the host so the new channel adapter loads:
# macOS
launchctl kickstart -k gui/$(id -u)/com.nanoclaw
# Linux
systemctl --user restart nanoclaw
webchatmessaging_groups row with channel_type='webchat'; the room id is its platform_id).POST /api/agents (agent-first): creates an agent + a 1:1 room with the agent's folder as the room id. Use when you're thinking "give me a chat-accessible agent."POST /api/rooms (room-first): creates a room and wires 1+ agents to it (existing or inline-new). Use when you're thinking "set up a conversation space" or want multi-agent rooms.messaging_group_agents) is many-to-many — the PWA exposes this via + Add agent in room settings.@<folder>-mention another wired agent. The mentioned agent answers those. Implemented entirely by rewriting messaging_group_agents.engage_pattern (negative-lookahead for the prime, positive \B@<folder>\b for others) — the existing v2 router does the actual gating via engage_mode='pattern'. No router-side change. Storage: webchat_room_primes(room_id, agent_group_id). Endpoints: PUT /api/rooms/:id/prime { agentId }, DELETE /api/rooms/:id/prime. The is_prime flag is included in GET /api/rooms/:id/agents.anthropic (pin to a custom Anthropic model_id, reuses the agent's existing OneCLI Anthropic credential) and ollama (route at a local Ollama endpoint; no auth needed, Ollama speaks the Anthropic API at <endpoint>/v1/messages). Health-checked on save (Ollama: /api/tags reachability + model-name verification). Auto-discovery available via POST /api/models/discover. Implementation is trunk-free — assignments are written into the per-agent data/v2-sessions/<agent>/.claude-shared/settings.json env block (ANTHROPIC_BASE_URL, ANTHROPIC_MODEL); the SDK's user setting source applies them at startup. Effect timing: takes effect on the next container spawn for the agent. Storage: webchat_models + webchat_agent_models (1:1 PK on agent_group_id). Endpoints: GET/POST /api/models, PUT/DELETE /api/models/:id (DELETE returns 409 + impact list when assigned; re-POST with ?force=1 to cascade-unassign), POST /api/models/discover, PUT /api/agents/:id/model { modelId | null }. The assigned_model_id field is included in GET /api/agents. Future kinds (e.g. OpenAI-compatible) will use the credential_ref column to point at OneCLI secret names — out of MVP scope.POST /api/agents/draft { prompt }, returning a suggested { name, instructions } that populates the form for the operator to review. Host-side LLM call routed through the OneCLI gateway with a reserved webchat-drafter agent identifier (registered with OneCLI on first use, idempotent). The host never holds the raw API key — OneCLI's proxy injects auth on each call, same model containers use. Per the v2 CLAUDE.md OneCLI gotcha, the drafter identifier starts in selective secret mode and 401s on the first call; one-time fix: onecli agents list to find the internal id, then onecli agents set-secret-mode --id <internal-id> --mode all. Latency ~3-5s per request (network-bound, no container spawn). Owner-only.This skill is upstream-PR scope; the following are known follow-ups:
jid, isMain, etc.) on /api/agents. Endpoint paths are v2-native; the response object keys are not. Stubs for /api/stats / /api/routes / /api/tasks keep the v1 dashboard pages from crashing. Cleaning the response shape (and dropping the dashboard stubs) is a follow-up.reconcileOrphanAgents, which provisions a 1:1 room for any agent without one. If you delete a room but leave the agents, the next PWA connect will recreate per-agent 1:1 rooms for them. Delete the agents too if you want them gone, or accept the auto-room as the v2 default.data/webchat/uploads/<roomId>/. They are served via HTTP, not mounted into agent containers (v1 wrote files into the agent's group folder so the agent could cat them; that path doesn't generalise to v2's fan-out model). Agents that need file bytes can fetch the URL./api/bots/create-from-chat "ask main to register") is dropped. Use POST /api/agents (agent-first) or POST /api/rooms (room-first) directly from the PWA.A fresh webchat install has no agents yet, and /init-first-agent doesn't have a webchat code path (it's built around the DM-channel mental model that webchat doesn't share). Use POST /api/agents with withRoom: true instead — that opt-in flag tells the handler to provision the agent group, initialize the on-disk filesystem (groups/<folder>/CLAUDE.local.md), create a 1:1 webchat room, and wire the channel→agent in one call.
(Without withRoom, the call creates a bare agent_group with no chat surface — the v2 default, since agents are entities and rooms are conversation spaces. You'd then wire the agent into a room via POST /api/rooms or the PWA's "+ Add agent" inside an existing room.)
Ask the user for an agent name and an optional persona. There is no special first-agent role in v2 — every webchat agent has the same capabilities (see "Channel Info"), so pick a name that reflects what the agent is for.
AskUserQuestion: "What should we call this first agent?"
AskUserQuestion: "Optional — a one-line persona / system instruction. Leave blank for the default."
Then curl it (substitute the answers). The X-Webchat-CSRF header is required on every owner-only POST — the PWA sets it automatically; for direct curl calls you have to include it explicitly:
curl -s -X POST http://127.0.0.1:3100/api/agents \
-H 'Content-Type: application/json' \
-H 'X-Webchat-CSRF: 1' \
-d '{"name":"Helper","instructions":"You are a helpful local assistant. Keep replies short and direct.","withRoom":true}'
If WEBCHAT_TOKEN is set, add -H 'Authorization: Bearer <token>'.
Confirm the response includes "ok": true and an agentGroup.id UUID. The room appears in the PWA sidebar immediately (the broadcastRooms event fires on creation).
Credentials reminder. The agent will only respond to messages once its container can authenticate to the LLM provider. Make sure either OneCLI or the native credential proxy is set up. With OneCLI, freshly-created agents start in
selectivesecret mode — if the agent connects but gets401 Unauthorized, runonecli agents set-secret-mode --id <agent-group-id> --mode all(see the v2CLAUDE.md"Gotcha" section).
No adapter for channel type webchat warnings in the logYou probably have multiple host processes for this checkout. pnpm run dev does not single-instance — a Ctrl-C followed by a fresh pnpm run dev can leave the previous node alive (especially after non-graceful kills). All those orphans run delivery polls and race for outbound messages: the orphan that loses the port bind has no webchat adapter in its activeAdapters map, so when it wins the race it logs No adapter ... and clears the outbox without delivering. The reply is gone.
Webchat's setup() now logs a fatal port ${port} already in use — another nanoclaw host is likely running line on EADDRINUSE so the second start fails loudly instead of silently joining the race. If you didn't see that line and still get intermittent silence, the duplicate started before this skill was applied.
Recovery for an existing duplicate-process state:
# kill every node process running tsx for THIS checkout
pgrep -f "$(basename $(pwd)).*tsx" | xargs -r kill -9
sleep 2
# verify just one (or zero) listener:
ss -tlnp | grep ":3100"
# start clean
pnpm run dev
The underlying single-instance guard in v2 trunk is tracked separately — when it lands, the second pnpm run dev will refuse to start at all instead of half-starting.
If you're in the middle of /setup, return to the setup flow now. Otherwise:
http://127.0.0.1:3100/ (or your configured host:port) in a browser.For additional agents, repeat the POST /api/agents call — each creates its own room.