tinyhat-codex-auth

Files (2)

• SKILL.md
• chatgpt-enable-device-code-for-codex.png · assets/

SKILL.md (first lines)

# Tinyhat Codex Auth

Use this when the user wants this Tinyhat-managed Hermes agent to use
their OpenAI Codex / ChatGPT subscription instead of Tinyhat-funded
platform credits.

## Explain Funding When Relevant

A new agent starts with about US$5 of AI model credit so it works immediately.
The owner can add more at any time from their Tinyhat credit: load
`tinyhat:tinyhat-credit` and use `tinyhat_openrouter_credit_allocate` for the
exact amount they request. Their request is the approval; do not ask again.
Connecting the user's own ChatGPT / Codex subscription through `/codex_auth`
is another optional way to fund model use.
When neither model credit nor a connected subscription is available, the
Agent cannot answer model-backed requests until the owner adds funding.

On first contact, answer the user's message first, then add one brief,
plain-language sentence about the starter credit and both funding choices.
Keep it in the same reply and skip it if a subscription is already connected.
An ordinary greeting is not a request for an onboarding tour: keep the hello
to one short sentence before this note, without a list of capabilities.
The starting credit is not the current balance. Explain the details only when
the user asks about cost, model access, or getting started; never repeat the
first-contact note in later conversations.

- Never block or delay the user's actual request on funding advice.
- A tool-owned native response stands alone; do not add a second explanation.
- If unsure whether a subscription is connected, check `tinyhat_codex_auth`
  with `{"action": "status"}` before claiming it is not connected.
- Never estimate remaining model funding or exact spend. Use
  `tinyhat:tinyhat-credit` for actual balances and recent transactions.
- When the user asks to connect their subscription, start the flow below.

Do not ask a multiple-choice clarification for common wording like
"connect my ChatGPT account" or "use my Codex subscription". Treat that
as a request to start Tinyhat's Codex auth flow. Only clarify if the user
explicitly asks for ChatGPT conversation history/data or for an OpenAI
API key instead of subscription auth.

## Default Flow: Screenshot, Then `/codex_auth`

For common natural-language requests, call `tinyhat_codex_auth` once
with:

```json
{"action": "prerequisite"}
```

This sends the screenshot that shows where the ChatGPT Security setting
lives, with a short caption and the clickable `/codex_auth` command.
After the tool call, do not send an extra normal chat reply. The photo
caption is the user-facing reply.

The tool caption uses copy like this. Keep `/codex_auth` on its own line
so it is hard to miss:

```text
To use your Codex subscription here:

1. Open chatgpt.com > Settings > Security.
2. Turn on "Enable device code authorization for Codex".

Then come back here and tap:

/codex_auth
```

The tool sends this bundled screenshot with that caption:

```text
skills/tinyhat-codex-auth/assets/chatgpt-enable-device-code-for-codex.png
```

After this prerequisite tool returns, do not send a follow-up reply unless
Telegram delivery failed and the tool explicitly says a reply is needed.
Do not repeat the same link, and do not call the tool again.

The user must do this on their side:

1. Open `chatgpt.com`.
2. Go to Settings.
3. Open Security.
4. Scroll to **Secure sign in with ChatGPT**.
5. Turn on **Enable device code authorization for Codex**.

Personal accounts can usually turn this on directly. Team, Business, and
Enterprise accounts may require a workspace admin if the toggle is
disabled.

## Start Auth Only If The User Confirms In Chat

Normally the user starts auth by tapping `/codex_auth` in the Telegram
message. If instead the user replies in chat that the setting is already
enabled and asks you to continue, call `tinyhat_codex_auth` with:

```json
{"action": "start", "confirmed": true}
```

Only this second call starts the installed auth helper that sends the
OpenAI authorization button and copyable code.

Let the tool's Telegram messages stand. Do not send a second link or a
second code in your own reply.

Tinyhat installs this Telegram auth flow during Computer setup:

```text
/codex_auth
```

The command sends an OpenAI authorization button to Telegram, sends the
device code as a separate copyable message, waits for OpenAI to finish
the device flow on this Computer, switches Hermes to Codex auth, and
restarts the Telegram gateway so the next reply uses the new credential.

If the `tinyhat_codex_auth` tool is unavailable, start the installed flow
yourself only after the user confirms the ChatGPT setting is on. Prefer

From tinyhat-ai/tinyhat, MIT.

More from tinyhat-ai/tinyhat