Integration
OpenClawCodexASR
By Experimental OpenClaw audio transcription plugin using your local Codex/ChatGPT subscription login—no separate OpenAI API key required. Unofficial and based on an undocumented endpoint.
Install
npm install
npmConfiguration Example
{
"status": "loaded",
"mediaUnderstandingProviderIds": ["codex-asr"]
}README
# Codex Subscription ASR for OpenClaw
Use your existing Codex/ChatGPT login to transcribe voice notes and audio
attachments received by OpenClaw.
> [!WARNING]
> This is an unofficial, experimental project. It uses an undocumented
> ChatGPT endpoint and is not affiliated with, endorsed by, or supported by
> OpenAI. The endpoint, authentication format, or compatibility headers may
> change without notice.
## What this plugin does
When OpenClaw receives an audio attachment, this plugin:
1. reads the local Codex login from `auth.json`;
2. sends the audio file to the ChatGPT transcription endpoint;
3. validates and cleans the returned transcript; and
4. gives the transcript back to OpenClaw for normal message processing.
The access token is read locally and kept only in process memory. It is not
copied into the OpenClaw configuration. The plugin reloads the credentials
when the authentication file changes.
This plugin handles audio that OpenClaw has already received. It does **not**
provide microphone recording, a global shortcut, clipboard output, text
injection, transcript history, or transcript rewriting.
## Requirements
- OpenClaw `2026.7.1-2` or newer
- A working Codex or ChatGPT login on the same machine/account that runs the
OpenClaw Gateway
- A local clone or downloaded copy of this repository
The Gateway process must be able to read the Codex authentication file and
reach `https://chatgpt.com`.
## Installation
### 1. Sign in to Codex
Sign in with Codex before installing the plugin. By default, the plugin looks
for credentials in this order:
1. the plugin's configured `authPath`;
2. `%CODEX_HOME%\auth.json` on Windows or `$CODEX_HOME/auth.json` on
macOS/Linux; and
3. `~/.codex/auth.json`.
If Codex already works for the same operating-system user as OpenClaw, no
additional authentication setup is normally required.
### 2. Install the local plugin
Open a terminal in this repository. For a normal installation, OpenClaw copies
the plugin into its managed plugin directory:
```powershell
openclaw plugins install .
```
For development, link the checkout instead so later local builds are used:
```powershell
openclaw plugins install --link .
```
OpenClaw may ask you to confirm that you trust this local source. Review the
code before accepting. If the command is run non-interactively, the current
OpenClaw CLI may require `--force` for a local source.
### 3. Enable the plugin
```powershell
openclaw plugins enable codex-asr
```
This setting is persistent. You normally run it only once, not after every
OpenClaw or computer restart.
You can also enable it in the OpenClaw Control UI under **Settings → Plugins**.
### 4. Make it the default audio transcription provider
Add or merge the following into your OpenClaw configuration:
```json5
{
plugins: {
entries: {
"codex-asr": {
enabled: true,
},
},
},
tools: {
media: {
models: [
{
type: "provider",
provider: "codex-asr",
model: "subscription",
capabilities: ["audio"],
},
],
audio: {
enabled: true,
preferredModel: "codex-asr/subscription",
timeoutSeconds: 45,
maxBytes: 20971520,
},
},
},
}
```
`preferredModel` explicitly selects this plugin for audio. Keeping it as the
only audio-capable entry also prevents OpenClaw from silently falling back to
a separately billed transcription provider.
If your OpenClaw configuration uses `plugins.allow`, add `"codex-asr"` to that
array. A matching entry in `plugins.deny` will always prevent the plugin from
loading.
### 5. Restart and verify
Installing or replacing plugin code requires a Gateway restart:
```powershell
openclaw gateway restart
```
Then verify both the saved installation and the live provider registration:
```powershell
openclaw plugins list --enabled --verbose
openclaw plugins inspect codex-asr --runtime --json
```
A successful runtime inspection reports a loaded plugin and includes:
```json
{
"status": "loaded",
"mediaUnderstandingProviderIds": ["codex-asr"]
}
```
Finally, send a voice note or audio attachment through a channel connected to
OpenClaw. The resulting transcript should be supplied to the agent as the
audio message content.
## What happens after OpenClaw restarts?
Nothing needs to be activated again after a normal restart. OpenClaw persists:
- the installed plugin record;
- `plugins.entries.codex-asr.enabled: true`; and
- the `tools.media` audio-provider selection.
At startup, the plugin registers itself automatically (`onStartup: true`). As
long as the configuration is still present and the authentication file can be
read, `codex-asr/subscription` remains the default audio transcription model.
If it does not load after a reboot, check:
```powershell
openclaw gateway status --deep --require-rpc
openclaw plugins inspect codex-asr --runtime --json
openclaw plugins doctor
```
Also confirm that the Gateway runs as the same user that owns the Codex login.
Services running as another Windows account, container user, or system user
will not automatically see your personal `~/.codex/auth.json`.
## Custom authentication path
If the Gateway runs under another user or the authentication file is stored
elsewhere, configure an absolute path:
```json5
{
plugins: {
entries: {
"codex-asr": {
enabled: true,
config: {
authPath: "C:\\Users\\your-name\\.codex\\auth.json",
},
},
},
},
}
```
On macOS or Linux, use an absolute path such as
`/home/your-name/.codex/auth.json`. Ensure that only the intended account can
read this file. Do not paste tokens directly into the configuration.
## Disable or remove
Temporarily disable the plugin without deleting it:
```powershell
openclaw plugins disable codex-asr
```
Remove the managed installation:
```powershell
openclaw plugins uninstall codex-asr
```
After disabling or removing it, also remove the `codex-asr` entry from
`tools.media.models` and change or remove `audio.preferredModel`.
## Troubleshooting
### Authentication was not found
- Run Codex and sign in again.
- Confirm that `auth.json` exists for the user running the Gateway.
- Set an absolute `authPath` if the Gateway uses another account or home
directory.
### Login expired or unauthorized
Sign in to Codex/ChatGPT again. The plugin deliberately does not refresh OAuth
credentials itself.
### Plugin is installed but not loaded
- Run `openclaw plugins enable codex-asr`.
- Check `plugins.allow` and `plugins.deny`.
- Restart the Gateway after installing or rebuilding plugin code.
- Run `openclaw plugins doctor` and inspect the runtime registration.
### Audio is handled by another provider
Set `tools.media.audio.preferredModel` to
`"codex-asr/subscription"`. Check the other entries in `tools.media.models` and
remove unwanted audio fallbacks.
### Timeout or recording too large
The example configuration allows 20 MiB and waits 45 seconds. Increase
`maxBytes` or `timeoutSeconds` carefully if your OpenClaw host and upstream
service support larger or longer requests.
### The plugin stopped working after an upstream update
The ChatGPT transcription endpoint and compatibility identity are
undocumented. A ChatGPT or Codex update can break this integration even when
the local configuration has not changed.
## Development
Development requires a Node.js version accepted by the `engines` field in
`package.json`.
```powershell
npm install
npm test
npm run validate:manifest
```
Or run the complete check:
```powershell
npm run check
```
The tests build the TypeScript source and exercise authentication, provider
registration, request construction, response limits, timeout/cancellation,
error sanitization, and transcript normalization.
OpenClaw's simple `plugins validate` metadata flow is not applicable to this
native media-understanding provider. Use the runtime inspection command shown
above to verify the provider in an OpenClaw host.
## Security and billing notes
- Treat this plugin as trusted local code: it can read your Codex access token.
- Never commit or share `auth.json`.
- Error messages are intentionally sanitized so tokens, file paths, and
upstream response bodies are not exposed.
- This project is designed for a Codex/ChatGPT subscription login. Do not add
OpenAI's regular transcription provider as a fallback unless you have
intentionally configured and accepted billing for a separate API key.
## License
Licensed under the [MIT License](LICENSE). Copyright (c) 2026 Ilias.
integration
Comments
Sign in to leave a comment