1---
2name: tg-auth-setup
3description: Install and use a Telegram `/setup` command that lets an authorized OpenClaw operator configure OpenAI Codex auth for the current agent from chat. Use when you need token-based setup, Telegram-driven OAuth completion, or self-serve Codex auth bootstrap without opening server files manually.
4---
5 
6# TG Auth Setup
7 
8Install a small OpenClaw plugin that adds an owner-only `/setup` command for OpenAI Codex auth bootstrap from Telegram.
9 
10This is the current working flow we use now:
11- `/setup` starts OAuth and prints the browser login URL.
12- After login, paste the full redirect URL or code as a normal next Telegram message — no extra command needed.
13- `/setup code <redirect_url_or_code>` is still available as a fallback.
14- `/setup codex <token>` or `/setup <token>` stores a token profile instead of OAuth.
15- `/setup status` shows which auth profile is active and the exact `auth-profiles.json` path.
16- `/cancel` or `/setup cancel` cancels a waiting OAuth session.
17 
18## Quick usage
19 
20```text
21/setup
22/setup status
23/setup oauth
24/setup code <redirect_url_or_code>
25/setup cancel
26/cancel
27/setup codex <token>
28/setup <token>
29```
30 
31## What is bundled
32 
33- `assets/tg-auth-setup-plugin/` — the OpenClaw plugin package.
34- `scripts/install_plugin.sh` — installer wrapper around `openclaw plugins install`.
35 
36## Install the plugin into OpenClaw
37 
38Prefer copy mode for real servers:
39 
40```bash
41bash {baseDir}/scripts/install_plugin.sh copy
42```
43 
44Use link mode only for local plugin development where edits should stay live:
45 
46```bash
47bash {baseDir}/scripts/install_plugin.sh link
48```
49 
50Both modes install plugin id `tg-auth-setup`.
51 
52## Verify and activate
53 
54After install:
55 
56```bash
57openclaw plugins info tg-auth-setup
58openclaw gateway restart
59```
60 
61Then confirm from Telegram:
62 
63```text
64/setup status
65```
66 
67If `/setup` is unknown, the Gateway usually has not been restarted or the plugin is not installed in the active OpenClaw runtime.
68 
69## Operator flow in Telegram
70 
71### 1. Check current status
72 
73```text
74/setup status
75```
76 
77The 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.
78 
79### 2. OAuth setup, preferred
80 
81```text
82/setup
83```
84 
85Then:
861. Open the returned auth URL in a local browser.
872. Finish sign-in.
883. Copy the full redirect URL or auth code.
894. Paste it back into Telegram as a normal message.
90 
91Fallback if the plain follow-up message is inconvenient:
92 
93```text
94/setup code <redirect_url_or_code>
95```
96 
97The 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.
98 
99### 3. Token-based setup
100 
101```text
102/setup codex <token>
103```
104 
105or just:
106 
107```text
108/setup <token>
109```
110 
111This writes a token profile for `openai-codex:default` and patches config so OpenClaw can use it.
112 
113### 4. Cancel a stuck flow
114 
115```text
116/cancel
117```
118 
119Alias:
120 
121```text
122/setup cancel
123```
124 
125## What the plugin changes
126 
127The bundled plugin:
128- writes `openai-codex:default` into the target agent `auth-profiles.json`;
129- stores either a token profile or an OAuth profile;
130- patches OpenClaw config so `auth.profiles.openai-codex:default` points at provider `openai-codex` with mode `token` or `oauth`;
131- 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.
132 
133## Implementation notes
134 
135- 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.
136- Auth path defaults to `~/.openclaw/agents/main/agent/auth-profiles.json`, or `OPENCLAW_AGENT_DIR/auth-profiles.json` when `OPENCLAW_AGENT_DIR` is set.
137- Writes are atomic and use restrictive file permissions where possible (`0700` dir, `0600` file).
138- OAuth sessions timeout after 10 minutes.
139 
140## Files to inspect
141 
142When debugging or adapting behavior, read:
143- `assets/tg-auth-setup-plugin/openclaw.plugin.json`
144- `assets/tg-auth-setup-plugin/index.js`
145- `scripts/install_plugin.sh`
146 
147## Guardrails
148 
149- Treat `/setup codex <token>` messages as sensitive; delete the Telegram message after successful setup.
150- The command is registered with `requireAuth: true`; keep it limited to authorized senders only.
151- Restart Gateway after installing or updating the plugin.
152- 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.
153