{"id":"add-webex","name":"add-webex","summary":"Chat SDKを通じてWebexチャンネル連携を追加しましょう。","body":"# Add Webex Channel\n\nAdds Cisco Webex support via the Chat SDK bridge. NanoClaw doesn't ship channels\nin trunk — this skill copies the Webex adapter in from the `channels` branch.\n\nThe mechanical steps under **Apply** carry `nc:` directive fences: an agent\nreads the prose and applies them, and a parser can apply them deterministically\nfrom the same document. Every directive is idempotent, so the whole skill is\nsafe to re-run; anything a parser can't apply falls back to the prose beside it.\n\n## Apply\n\n### 1. Copy the adapter and its registration test\n\nFetch the `channels` branch and copy the Webex adapter and its registration test\ninto `src/channels/` (overwrite — the branch is canonical):\n\n```nc:copy from-branch:channels\nsrc/channels/webex.ts\nsrc/channels/webex-registration.test.ts\n```\n\n### 2. Register the adapter\n\nAppend the self-registration import to the channel barrel (skipped if the line\nis already present). This one line is the skill's only reach-in into core:\n\n```nc:append to:src/channels/index.ts\nimport './webex.js';\n```\n\n### 3. Install the adapter package\n\nPinned to an exact version — the supply-chain policy rejects ranges and `latest`.\nThe Webex adapter ships under the third-party `@bitbasti/*` namespace, not\n`@chat-adapter/*`, so it carries its own version line (`0.1.0`) rather than\ntracking the chat core version:\n\n```nc:dep\n@bitbasti/chat-adapter-webex@0.1.0\n```\n\n### 4. Build and validate\n\nBuild first: it guards the typed `createChatSdkBridge(...)` core call and proves\nthe dependency is installed. Then run the one integration test.\n\n```nc:run effect:build\npnpm run build\n```\n```nc:run effect:test\npnpm exec vitest run src/channels/webex-registration.test.ts\n```\n\n`webex-registration.test.ts` imports the real channel barrel and asserts the\nregistry contains `webex`. It goes red if the import line is deleted or drifts,\nif the barrel fails to evaluate, or if `@bitbasti/chat-adapter-webex` isn't\ninstalled (the import throws) — so it also covers the dependency from step 3.\nEnd-to-end delivery against a real Webex space is verified manually once the\nservice runs — see the webhook setup below.\n\n## Credentials\n\nWebex bot setup is human and interactive — these steps are prose, not directives\n(no parser can click through the Webex Developer Portal). A recipe rebuild\nproduces a compiling, registered adapter that cannot receive a message until\nthey're done.\n\n### Create the Webex bot\n\n1. Go to [developer.webex.com](https://developer.webex.com/my-apps/new/bot) and create a new bot.\n2. Copy the **Bot Access Token**.\n3. Set up a webhook:\n   - Use the Webex API or Developer Portal to create a webhook pointing to `https://your-domain/webhook/webex`.\n   - Set a webhook secret for signature verification.\n\n### Store the credentials\n\nCapture the two values, then write them. `prompt` only *asks* and binds the\nanswer to a name; a separate directive consumes it — so the same prompts could\nfeed `ncl` or the OneCLI vault instead of `.env` by swapping only the consumer.\nHere they go to `.env` (set-if-absent — a value you've already filled in is\nnever overwritten):\n\n```nc:prompt bot_token secret\nPaste the Bot Access Token — from the Webex bot you created.\n```\n```nc:prompt webhook_secret secret\nPaste the webhook secret you set for signature verification.\n```\n```nc:env-set\nWEBEX_BOT_TOKEN={{bot_token}}\nWEBEX_WEBHOOK_SECRET={{webhook_secret}}\n```\n### Webhook server\n\nThe Chat SDK bridge automatically starts a shared webhook server on port 3000\n(`WEBHOOK_PORT` to change it), handling `/webhook/webex`. This port must be\npublicly reachable for Webex to deliver events. Running locally, expose it with\nngrok (`ngrok http 3000`), a Cloudflare Tunnel, or a reverse proxy on a VPS —\nthe resulting public URL is the base for the webhook URL above.\n\n## Next Steps\n\nIf you're in the middle of `/setup`, return to the setup flow now. Otherwise run\n`/manage-channels` to wire this channel to an agent group.\n\n## Channel Info\n\n- **type**: `webex`\n- **terminology**: Webex has \"spaces.\" A space can be a group conversation or a 1:1 direct message with the bot.\n- **how-to-find-id**: Open the space in Webex, click the space name > Settings — the Space ID is listed there. Or use the Webex API (`GET /rooms`) to list spaces and their IDs.\n- **supports-threads**: yes\n- **typical-use**: Interactive chat — team spaces or direct messages\n- **default-isolation**: Same agent group for spaces where you're the primary user. Separate agent group for spaces with different teams or sensitive information.\n\n## Troubleshooting\n\n**Sends fail with 401.** The Bot Access Token is shown once, on the bot's page under developer.webex.com → My Apps — it is *not* the 12-hour personal access token from the API docs pages, which is the classic mix-up (that one works briefly, then everything 401s). Regenerate the token on the bot page if needed; regenerating invalidates the old value, so update `WEBEX_BOT_TOKEN` right away.\n\n**Messages in the space never reach the agent.** Webex delivers only to the webhook you created: it must target your public host at `/webhook/webex` (shared webhook server, port 3000) with resource `messages`. List your webhooks with `GET https://webexapis.com/v1/webhooks` using the bot token — Webex flips a webhook to `inactive` after repeated delivery failures, and it stays off until you re-enable or recreate it.\n\n**Events arrive but are rejected.** Signature mismatch: the secret set at webhook creation must equal `WEBEX_WEBHOOK_SECRET` exactly. Recreate the webhook with a known secret and update `.env` to match.\n\n**Adapter installed but silent.** Run `pnpm exec vitest run src/channels/webex-registration.test.ts` — red means the barrel import or the `@bitbasti/chat-adapter-webex` install drifted, so re-run the Apply steps. If green, restart the service so it loads the adapter and the tokens, then watch `logs/nanoclaw.log` for the webhook hit.","author":"@nanocoai","ownerProfile":null,"authorContacts":null,"sourceUrl":"https://github.com/nanocoai/nanoclaw/tree/main/.claude/skills/add-webex","license":"MIT","category":"writing","lang":"en","tokens":1438,"stars":0,"calls30d":1,"claimed":false,"visibility":"public","origin":"crawler","version":"0.1.0","createdAt":"2026-08-22","updatedAt":"2026-08-22","files":[{"path":"apply-fixtures.json","size":309,"sha256":"cdb3a1e10eee1c484f7a275c32f24c039b7f8ec900f256f19ef34dd459f9b9b3"},{"path":"REMOVE.md","size":732,"sha256":"5dbf3ffc1ed418714e1942a58f17580fde6854f9e7aa18006cc74c25f18b0a9a"}],"requires":{"mcp":[],"tools":[]},"safety":{"flags":[],"scannedAt":"2026-08-22","hasScripts":false,"networkEndpoints":["developer.webex.com","webexapis.com"]}}