Overview

This guide shows you how to connect OpenAI Codex to Matrix using OpenClaw. You'll configure the messaging channel, set up AI provider authentication, and deploy your assistant.

Matrix Capabilities

Direct messages
Group chats
Media support
Reactions
Thread support

OpenAI Codex Features

128K context window
Image generation and understanding
Tool/function calling
Fine-tuning available

Step 1: Configure Matrix

Create a Matrix account on your preferred homeserver
Generate an access token
Configure matrix in openclaw.json
Start the gateway
Invite the bot to rooms

Step 2: Configure OpenAI Codex

Standard API key authentication

Create an account at platform.openai.com
Navigate to API Keys section
Generate a new API key
Set OPENAI_API_KEY environment variable

Environment variable: OPENAI_API_KEY

Step 3: Combined Configuration

Add both configurations to your openclaw.json:

{
  "agents": {
    "defaults": {
      "model": {
        "primary": "openai-codex/gpt-5.2"
      }
    }
  },
  "models": {
    "providers": {
      "openai-codex": {
  "models": {
    "providers": {
      "openai-codex": {
        "apiKey": "${OPENAI_API_KEY}
    }
  },
  "channels": {
    "matrix": {
      "homeserver": "https://matrix.org",
      "accessToken": "${MATRIX_ACCESS_TOKEN}",
      "userId": "@mybot:matrix.org"
    }
  }
}
}

Step 4: Start and Test

# Start the gateway
openclaw gateway start

# Check connection status
openclaw status

# View real-time logs
openclaw logs --follow

Access Control

Matrix supports the following access control policies:

DM Policies

Policy	Description
`allowlist`	Only senders in allowFrom list are processed
`pairing`	Unknown senders receive a pairing code; admin must approve
`open`	All DMs are processed (requires allowFrom: ["*"])