TG Auth Setup

Install a small OpenClaw plugin that adds an owner-only /setup command for OpenAI Codex auth bootstrap from Telegram.

This is the current working flow we use now:

• /setup starts OAuth and prints the browser login URL.
• After login, paste the full redirect URL or code as a normal next Telegram message — no extra command needed.
• /setup code <redirect_url_or_code> is still available as a fallback.
• /setup codex <token> or /setup <token> stores a token profile instead of OAuth.
• /setup status shows which auth profile is active and the exact auth-profiles.json path.
• /cancel or /setup cancel cancels a waiting OAuth session.

Quick usage

/setup
/setup status
/setup oauth
/setup code <redirect_url_or_code>
/setup cancel
/cancel
/setup codex <token>
/setup <token>

What is bundled

• assets/tg-auth-setup-plugin/ — the OpenClaw plugin package.
• scripts/install_plugin.sh — installer wrapper around openclaw plugins install.

Install the plugin into OpenClaw

Prefer copy mode for real servers:

bash {baseDir}/scripts/install_plugin.sh copy

Use link mode only for local plugin development where edits should stay live:

bash {baseDir}/scripts/install_plugin.sh link

Both modes install plugin id tg-auth-setup.

Verify and activate

After install:

openclaw plugins info tg-auth-setup
openclaw gateway restart

Then confirm from Telegram:

/setup status

If /setup is unknown, the Gateway usually has not been restarted or the plugin is not installed in the active OpenClaw runtime.

Operator flow in Telegram

1. Check current status

/setup status

The command reports whether openai-codex:default is missing, token-based, or OAuth-based, plus the active auth-profiles.json path. If OAuth is in progress, it also shows the session state and cancel hint.

2. OAuth setup, preferred

/setup

Then:

1. Open the returned auth URL in a local browser.
2. Finish sign-in.
3. Copy the full redirect URL or auth code.
4. Paste it back into Telegram as a normal message.

Fallback if the plain follow-up message is inconvenient:

/setup code <redirect_url_or_code>

The plugin keeps a short-lived per-sender OAuth session in memory, captures the next message from the same sender, stores OAuth credentials, and patches OpenClaw config when complete.

3. Token-based setup

/setup codex <token>

or just:

/setup <token>

This writes a token profile for openai-codex:default and patches config so OpenClaw can use it.

4. Cancel a stuck flow

/cancel

Alias:

/setup cancel

What the plugin changes

The bundled plugin:

• writes openai-codex:default into the target agent auth-profiles.json;
• stores either a token profile or an OAuth profile;
• patches OpenClaw config so auth.profiles.openai-codex:default points at provider openai-codex with mode token or oauth;
• sets agents.defaults.model.primary to openai-codex/gpt-5.5 only if no primary model is already configured — it does not overwrite an existing agent model.

Implementation notes

• OAuth helper loading is resilient across npm/global installs: it searches the active OpenClaw install, PATH-derived prefixes, npm global root, and common @mariozechner/pi-ai locations.
• Auth path defaults to ~/.openclaw/agents/main/agent/auth-profiles.json, or OPENCLAW_AGENT_DIR/auth-profiles.json when OPENCLAW_AGENT_DIR is set.
• Writes are atomic and use restrictive file permissions where possible (0700 dir, 0600 file).
• OAuth sessions timeout after 10 minutes.

Files to inspect

When debugging or adapting behavior, read:

• assets/tg-auth-setup-plugin/openclaw.plugin.json
• assets/tg-auth-setup-plugin/index.js
• scripts/install_plugin.sh

Guardrails

• Treat /setup codex <token> messages as sensitive; delete the Telegram message after successful setup.
• The command is registered with requireAuth: true; keep it limited to authorized senders only.
• Restart Gateway after installing or updating the plugin.
• Do not hardcode /usr/lib/node_modules or /usr/local/lib/node_modules; resolve the OAuth helper relative to the active OpenClaw install when adapting this skill.