openclaw-codex-app-server 0.0.0

package/AGENTS.md

@@ -0,0 +1,22 @@
+# Repository Guidelines
+
+## Project Structure & Module Organization
+`index.ts` is the plugin entrypoint and registers commands, services, and interactive handlers. Core implementation lives in [`src/`](./src): controller flow in `controller.ts`, API/client integration in `client.ts`, configuration in `config.ts`, state and thread helpers in `state.ts`, `thread-picker.ts`, and `thread-selection.ts`, and user-facing text formatting in `format.ts`. Tests are colocated with source files as `src/*.test.ts`. Plugin metadata lives in `openclaw.plugin.json`; package and TypeScript settings are in `package.json` and `tsconfig.json`.
+
+## Build, Test, and Development Commands
+Use `pnpm` for local work.
+
+- `pnpm test`: run the Vitest suite once.
+- `pnpm typecheck`: run strict TypeScript checking with `tsc --noEmit`.
+- `pnpm openclaw plugins install --link /path/to/openclaw-codex-app-server`: link this package into a local OpenClaw checkout for manual integration testing.
+
+There is no separate build step in this repository; correctness is gated by tests and typechecking.
+
+## Coding Style & Naming Conventions
+Write TypeScript targeting Node ESM (`"module": "NodeNext"`). Match the existing style: 2-space indentation, double quotes, semicolons, and small focused helpers. Use `PascalCase` for classes and types, `camelCase` for functions and variables, and `SCREAMING_SNAKE_CASE` for shared constants such as command lists or namespace identifiers. Keep command and plugin-facing strings explicit and near the registration code when possible.
+
+## Testing Guidelines
+Tests use Vitest and should stay next to the code they cover, named `*.test.ts`. Prefer narrow unit tests over broad fixtures; most existing tests assert exact payloads and formatting behavior. Run `pnpm test` and `pnpm typecheck` before opening a PR. Add or update tests for any command handling, thread-selection logic, formatting branch, or protocol-shape change.
+
+## Commit & Pull Request Guidelines
+Follow the repository’s existing commit style: short imperative subjects, often with a `Plugin:` prefix, for example `Plugin: restore Codex interactive workflows`. Keep commits scoped to one behavior change. PRs should include a concise summary, linked issue or context, and the exact validation performed (`pnpm test`, `pnpm typecheck`, manual OpenClaw plugin exercise). Include screenshots or message transcripts when changing interactive Telegram or Discord flows.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,129 @@
+# OpenClaw Codex App Server Plugin
+
+Codex App Server as an OpenClaw plugin for Telegram and Discord conversations. It binds a chat to a Codex thread, forwards plain-text messages into that thread, and exposes command-driven controls for resume, planning, review, model selection, compaction, and more.
+
+## Local Setup Before OpenClaw PR #45318 Lands
+
+This plugin targets the plugin interface from [openclaw/openclaw#45318](https://github.com/openclaw/openclaw/pull/45318). Until that work is merged and shipped in the latest OpenClaw release, develop against a local OpenClaw checkout on that PR branch or `main` once merged.
+
+### 0. Clone this repository
+
+```bash
+git clone <this-repo-url>
+cd openclaw-codex-app-server
+```
+
+### 1. Check out OpenClaw with the plugin interface
+
+```bash
+git clone https://github.com/openclaw/openclaw.git
+cd openclaw
+gh pr checkout 45318
+pnpm install
+```
+
+If you are not using `gh`, fetch the PR directly:
+
+```bash
+git fetch origin pull/45318/head:pr-45318
+git checkout pr-45318
+pnpm install
+```
+
+Once the PR is merged, use `main` instead.
+
+### 2. Point this plugin repo at your local OpenClaw checkout
+
+From this repository:
+
+```bash
+pnpm add -D openclaw@file:/absolute/path/to/openclaw
+pnpm install
+```
+
+That makes the local `openclaw` package available to this plugin before a published release includes the new interface.
+
+### 3. Install the plugin from your local checkout
+
+From the openclaw repository:
+
+```bash
+pnpm openclaw plugins install --link "/absolute/path/to/openclaw-codex-app-server"
+```
+
+### 4. Start OpenClaw
+
+From your OpenClaw checkout:
+
+```bash
+pnpm gateway:watch
+```
+
+## Typical Workflow
+
+1. Start in the Telegram or Discord conversation where you want Codex bound.
+2. Run `/codex_resume`.
+3. Use the buttons to browse projects and threads, or pass filters in the command.
+4. Once bound, plain text in that conversation routes to the selected Codex thread.
+5. Use the control commands below as needed.
+
+Buttons are presented for project and thread selection, model switching, and skill shortcuts. If your filter is ambiguous, the plugin sends a picker instead of guessing.
+
+## Command Reference
+
+| Command | What it does | Notes / examples |
+| --- | --- | --- |
+| `/codex_resume` | Bind this conversation to a Codex thread. | With no args, opens a picker for recent sessions in the current workspace. |
+| `/codex_resume --projects` | Browse projects first. | Opens a project picker, then a thread picker. |
+| `/codex_resume --all` | Search recent sessions across projects. | Useful when the thread is not in the current workspace. |
+| `/codex_resume --cwd ~/github/openclaw` | Restrict browsing/search to one workspace. | `--cwd` accepts an absolute path or `~/...`. |
+| `/codex_resume --sync` | Resume and try to sync the chat/topic name to the Codex thread. | You can combine this with other flags. |
+| `/codex_resume release-fix` | Resume a matching thread by title or id. | If more than one thread matches, you get buttons to choose. |
+| `/codex_status` | Show the current binding and thread state. | Includes thread id, model, workspace, sandbox, and permissions when available. |
+| `/codex_detach` | Unbind this conversation from Codex. | Stops routing plain text from this conversation into the bound thread. |
+| `/codex_stop` | Interrupt the active Codex run. | Only applies when a turn is currently in progress. |
+| `/codex_steer <message>` | Send follow-up steer text to an active run. | Example: `/codex_steer focus on the failing tests first` |
+| `/codex_plan <goal>` | Ask Codex to plan instead of execute. | The plugin relays plan questions and the final plan back into chat. |
+| `/codex_plan off` | Exit plan mode for this conversation. | Interrupts a lingering plan run so future turns go back to default coding mode. |
+| `/codex_review` | Review the current uncommitted changes in the bound workspace. | Requires an existing binding. |
+| `/codex_review <focus>` | Review with custom instructions. | Example: `/codex_review focus on thread selection regressions` |
+| `/codex_compact` | Compact the bound Codex thread. | The plugin posts progress and final context usage. |
+| `/codex_skills` | List available Codex skills for the workspace. | Adds buttons for up to eight skill shortcuts. |
+| `/codex_skills review` | Filter the skills list. | Matches skill name, description, or cwd. |
+| `/codex_experimental` | List experimental features reported by Codex. | Read-only. |
+| `/codex_mcp` | List configured MCP servers. | Shows auth state and counts for tools/resources/templates. |
+| `/codex_mcp github` | Filter MCP servers. | Matches name and auth status. |
+| `/codex_fast` | Toggle fast mode for the bound thread. | Equivalent to switching the service tier between default and fast. |
+| `/codex_fast on|off|status` | Set or inspect fast mode explicitly. | Example: `/codex_fast status` |
+| `/codex_model` | List models and show model-selection buttons. | If the conversation is not bound yet, it lists models only. |
+| `/codex_model gpt-5.4` | Set the model for the bound thread. | Requires an existing binding. |
+| `/codex_permissions` | Show account, rate-limit, and thread permission information. | Works with or without a current binding. |
+| `/codex_init ...` | Forward `/init` to Codex. | Sends the alias straight through to the App Server. |
+| `/codex_diff ...` | Forward `/diff` to Codex. | Sends the alias straight through to the App Server. |
+| `/codex_rename <new name>` | Rename the bound Codex thread. | Example: `/codex_rename approval flow cleanup` |
+| `/codex_rename --sync <new name>` | Rename the thread and try to sync the conversation/topic name too. | Requires an existing binding. |
+
+## Screenshot Placeholders
+
+- `[TODO screenshot] /codex_resume --projects` project picker
+- `[TODO screenshot] /codex_resume` thread picker with buttons
+- `[TODO screenshot] bound conversation after /codex_status`
+- `[TODO screenshot] /codex_model` button list
+
+## Plugin Config Notes
+
+The plugin schema in [`openclaw.plugin.json`](./openclaw.plugin.json) supports:
+
+- `transport`: `stdio` or `websocket`
+- `command` and `args`: the Codex executable and CLI args for `stdio`
+- `url`, `authToken`, `headers`: connection settings for `websocket`
+- `defaultWorkspaceDir`: fallback workspace for unbound actions
+- `defaultModel`: model used when a new thread starts without an explicit selection
+- `defaultServiceTier`: default service tier for new turns
+
+## Development Checks
+
+```bash
+pnpm test
+pnpm typecheck
+```

package/index.ts

@@ -0,0 +1,69 @@
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
+import { CodexPluginController } from "./src/controller.js";
+import { INTERACTIVE_NAMESPACE } from "./src/types.js";
+
+const COMMANDS = [
+  ["codex_resume", "Resume or bind an existing Codex thread."],
+  ["codex_detach", "Detach this conversation from the current Codex thread."],
+  ["codex_status", "Show the current Codex binding and thread state."],
+  ["codex_stop", "Stop the active Codex turn."],
+  ["codex_steer", "Send a steer message to the active Codex turn."],
+  ["codex_plan", "Ask Codex to produce a plan, or use 'off' to exit plan mode."],
+  ["codex_review", "Run Codex review on the current changes."],
+  ["codex_compact", "Compact the current Codex thread."],
+  ["codex_skills", "List Codex skills."],
+  ["codex_experimental", "List Codex experimental features."],
+  ["codex_mcp", "List Codex MCP servers."],
+  ["codex_fast", "Toggle Codex fast mode."],
+  ["codex_model", "List or switch the Codex model."],
+  ["codex_permissions", "Show Codex permissions and account status."],
+  ["codex_init", "Forward /init to Codex."],
+  ["codex_diff", "Forward /diff to Codex."],
+  ["codex_rename", "Rename the Codex thread and sync the channel name when possible."],
+] as const;
+
+const plugin = {
+  id: "openclaw-codex-app-server",
+  name: "OpenClaw App Server",
+  description: "Codex App Server as an OpenClaw plugin.",
+  register(api: OpenClawPluginApi) {
+    const controller = new CodexPluginController(api);
+
+    api.registerService(controller.createService());
+
+    api.on("inbound_claim", async (event) => {
+      return await controller.handleInboundClaim(event);
+    });
+
+    api.registerInteractiveHandler({
+      channel: "telegram",
+      namespace: INTERACTIVE_NAMESPACE,
+      handler: async (ctx) => {
+        await controller.handleTelegramInteractive(ctx);
+        return { handled: true };
+      },
+    });
+
+    api.registerInteractiveHandler({
+      channel: "discord",
+      namespace: INTERACTIVE_NAMESPACE,
+      handler: async (ctx) => {
+        await controller.handleDiscordInteractive(ctx);
+        return { handled: true };
+      },
+    });
+
+    for (const [name, description] of COMMANDS) {
+      api.registerCommand({
+        name,
+        description,
+        acceptsArgs: true,
+        handler: async (ctx) => {
+          return await controller.handleCommand(name, ctx);
+        },
+      });
+    }
+  },
+};
+
+export default plugin;

package/openclaw.plugin.json

@@ -0,0 +1,105 @@
+{
+  "id": "openclaw-codex-app-server",
+  "name": "OpenClaw Codex App Server",
+  "description": "Codex App Server as an OpenClaw plugin with bound Telegram and Discord conversations.",
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {
+      "enabled": {
+        "type": "boolean"
+      },
+      "transport": {
+        "type": "string",
+        "enum": [
+          "stdio",
+          "websocket"
+        ]
+      },
+      "command": {
+        "type": "string"
+      },
+      "args": {
+        "type": "array",
+        "items": {
+          "type": "string"
+        }
+      },
+      "url": {
+        "type": "string"
+      },
+      "authToken": {
+        "type": "string"
+      },
+      "headers": {
+        "type": "object",
+        "additionalProperties": {
+          "type": "string"
+        }
+      },
+      "requestTimeoutMs": {
+        "type": "number",
+        "minimum": 100
+      },
+      "inputTimeoutMs": {
+        "type": "number",
+        "minimum": 1000
+      },
+      "defaultWorkspaceDir": {
+        "type": "string"
+      },
+      "defaultModel": {
+        "type": "string"
+      },
+      "defaultServiceTier": {
+        "type": "string"
+      }
+    }
+  },
+  "uiHints": {
+    "enabled": {
+      "label": "Enabled"
+    },
+    "transport": {
+      "label": "Transport"
+    },
+    "command": {
+      "label": "Codex Command",
+      "help": "Used for stdio mode. Defaults to codex."
+    },
+    "args": {
+      "label": "Codex Args",
+      "advanced": true
+    },
+    "url": {
+      "label": "WebSocket URL"
+    },
+    "authToken": {
+      "label": "WebSocket Bearer Token",
+      "sensitive": true
+    },
+    "headers": {
+      "label": "Extra Headers",
+      "advanced": true
+    },
+    "requestTimeoutMs": {
+      "label": "Request Timeout (ms)",
+      "advanced": true
+    },
+    "inputTimeoutMs": {
+      "label": "Input Timeout (ms)",
+      "advanced": true
+    },
+    "defaultWorkspaceDir": {
+      "label": "Default Workspace Dir"
+    },
+    "defaultModel": {
+      "label": "Default Model",
+      "advanced": true
+    },
+    "defaultServiceTier": {
+      "label": "Default Service Tier",
+      "advanced": true
+    }
+  }
+}

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "openclaw-codex-app-server",
+  "version": "0.0.0",
+  "description": "OpenClaw plugin for Codex App Server conversations",
+  "license": "MIT",
+  "type": "module",
+  "openclaw": {
+    "extensions": [
+      "./index.ts"
+    ]
+  },
+  "peerDependencies": {
+    "openclaw": "*"
+  },
+  "dependencies": {
+    "ws": "^8.18.3"
+  },
+  "devDependencies": {
+    "@types/node": "^24.6.0",
+    "openclaw": "2026.3.13",
+    "typescript": "^5.9.2",
+    "vitest": "^3.2.4"
+  },
+  "scripts": {
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  }
+}