/opentag

name: opentag
description: Set up, run, and troubleshoot OpenTag with the published CLI across Slack, GitHub, GitLab, Linear, Lark / Feishu, Codex, Claude Code, OpenClaw, local config, platform credentials, and callback delivery.

OpenTag

OpenTag connects collaboration platforms to a local coding agent. Use this skill when a user wants help with `opentag setup`, `opentag start`, Slack, GitHub, GitLab, Linear, Lark / Feishu, Codex, Claude Code, OpenClaw, local OpenTag config, or end-to-end setup verification.

Default Path

Use the published CLI first. Do not start from repo-internal apps, old shell scripts, or private package binaries unless the user is explicitly doing core development.

Recommended user path:

npm install -g @opentag/cli
opentag setup
opentag start

No global install:

npx @opentag/cli setup
npx @opentag/cli start

Route The Request

Read only the reference needed for the user's path:

• First setup or Echo test loop: `references/local-echo.md`
• Slack setup: `references/slack-setup.md`
• GitHub setup: `references/github-setup.md`
• ACP coding-agent execution: `references/codex-runner.md`
• Broken setup, missing callbacks, rejected runs, or auth errors: `references/troubleshooting.md`

For platform credential steps, use the repository docs as the source of truth:

• Slack: `docs/platforms/slack.en.md`
• GitHub: `docs/platforms/github.en.md`
• GitLab: `docs/platforms/gitlab.en.md`
• Linear: `docs/platforms/linear.en.md`
• Lark / Feishu: `docs/platforms/lark.en.md`

Working Rules

• Keep setup user-led. Never invent tokens, app IDs, Slack team/channel IDs, GitHub owner/repo names, or local project paths.
• Prefer Slack, then GitHub, then GitLab, then Linear, then Lark / Feishu when listing platforms.
• Ask the user which platform and coding agent they want if it is not already clear outside Codex.
• In Codex Plan mode, use `request_user_input` / askhuman to collect non-secret setup choices before running `opentag setup`, then pass those choices as CLI flags so the terminal wizard does not silently choose defaults.
• Codex Default mode cannot render askhuman choice cards. If setup choices are needed and the current host does not expose a runtime transition into Plan mode, stop and explain that askhuman cannot render from Default mode in this run. Do not claim a Plan-mode handoff happened, do not ask the user to switch modes, do not ask the same choices in plain text, do not continue with CLI defaults, and do not run `opentag setup` until the choices are explicitly collected.
• Never request secrets through askhuman. Tokens, app secrets, signing secrets, app IDs, channel IDs, repository names, and any non-recommended project path still need explicit user confirmation before they are entered into the CLI or config.
• Prefer Codex or Claude Code when the corresponding local login is ready, Hermes when its ACP profile and provider are ready, OpenClaw when its Gateway is ready, and Echo only for dev/test verification.
• Do not ask setup users to invoke an agent directly. OpenTag provides built-in Generic ACP launches for Codex, Claude Code, Cursor, OpenCode, Hermes, and OpenClaw; diagnose them with `opentag doctor` and the built-in ACP conformance gate.
• OpenClaw currently reports `cancel=no`. A cancellation request stops OpenTag's local bridge, but Gateway-owned tool subprocess termination is not guaranteed; inspect provider-owned processes before starting conflicting follow-up work.
• Treat `opentag start` as a foreground process. Tell the user to keep it running and stop it with Ctrl-C.
• Do not expose secrets in responses. Use `opentag config show` for redacted config.
• When credentials are needed, point the user to the matching platform guide and walk them through the official setup.

Npm Registry And Network Failures

If `npm install -g @opentag/cli` or `npx @opentag/cli ...` fails before the OpenTag CLI starts, keep the exact npm error and diagnose the package delivery path before giving up. Treat errors such as `ENOTFOUND`, `EAI_AGAIN`, `ETIMEDOUT`, `ECONNRESET`, `fetch failed`, proxy connection failures, and TLS certificate errors as network or npm-environment issues, not as OpenTag setup failures.

Use safe, non-secret checks first:

node --version
npm config get registry
npm config get proxy
npm config get https-proxy
env | grep -i proxy
node -e "require('dns').lookup('registry.npmjs.org', (e, a, f) => console.log(e ? e.code + ' ' + e.message : a + ' ' + f))"
curl -I --max-time 15 https://registry.npmjs.org/@opentag%2fcli
npm view @opentag/cli version --fetch-timeout=15000

If DNS or registry access is flaky, say that the published CLI could not be reached yet and retry once after checking connectivity. If the user has a VPN or proxy, compare direct npm metadata access with a one-command proxy-scoped npm registry retry, but do not permanently change `npm config` without explicit user confirmation:

HTTPS_PROXY="<proxy-url>" HTTP_PROXY="<proxy-url>" npm view @opentag/cli version --fetch-timeout=15000

Only after npm registry metadata is reachable, retry the CLI help command:

npx --yes @opentag/cli --help

Only use a proxy URL the user provides or that is already active in the environment. Do not invent proxy hosts, tokens, certificates, or registry credentials. If npm cache metadata exists but `npx --offline` or `npm pack --offline` still fails, do not claim the CLI is available offline; report that the cache is not executable and wait for registry access to recover.

Codex Plan Mode Askhuman Setup Choices

When helping a Codex user install or configure OpenTag, collect these non-secret choices with `request_user_input` / askhuman only when the current Codex host is actually in Plan mode and the tool is available:

• Platform: Slack, GitHub, GitLab, Linear, Lark / Feishu, Telegram, or Discord.
• Coding agent: Codex, Claude Code, Cursor, OpenCode, Hermes, OpenClaw, or Echo, using