OpenClaw/Codex Read-only MCP

A local-first Model Context Protocol server for inspecting OpenClaw and Codex operations without changing them.

The server exposes 22 deterministic read-only tools for status, tasks, sessions, schedules, logs, Git changes, and approved workspace files. Outputs use opaque references, credential redaction, bounded reads, and path allowlists so an MCP client can help with maintenance and incident triage without receiving raw runtime identifiers or unrestricted filesystem access.

Why this exists

Maintainers often need the same context in several places: service health, recent agent work, scheduled automation, repository changes, and the public parts of task transcripts. This project packages those reads behind a stable MCP surface while keeping mutation, deployment, and approval decisions outside the server.

Typical uses include:

• diagnose a failed OpenClaw automation from sanitized status and logs;
• inspect the public progress and Git changes of a Codex task;
• review scheduled jobs without enabling, editing, or running them;
• search approved project files while excluding credentials and runtime stores;
• build maintainer dashboards and release checks from bounded JSON responses.

Safety properties

• Read-only by construction: there are no tools for writes, task cancellation, cron mutation, Git mutation, deployment, or external sending.
• Loopback by default: the HTTP server binds to 127.0.0.1 unless explicitly configured otherwise.
• Authenticated remote binding: non-loopback binding requires both an explicit opt-in and a bearer token of at least 32 characters.
• Explicit project roots: Codex task file and Git inspection stays disabled until allowed roots are configured.
• Protected paths: .git, .ssh, secrets, environment files, credential files, dependencies, binary files, symlinks, and oversized files are denied.
• Privacy filtering: system/developer prompts, internal reasoning, credential-shaped values, email addresses, phone numbers, IP addresses, and local paths are removed or redacted.
• Bounded output: list, transcript, file, search, and diff responses have fixed limits.

See SECURITY.md for the threat model and deployment boundary.

Requirements

• Node.js 20 or newer
• an OpenClaw installation with JSON-capable CLI commands
• a local Codex state database for Codex task tools
• sqlite3 and rg available on PATH, or configured with environment variables

Some OpenClaw task and flow commands are extension-dependent. Unsupported commands fail only their individual MCP call and return a sanitized error.

Quick start

npm ci
cp .env.example .env
# Edit .env for your local OpenClaw/Codex paths.
npm test
npm run verify:public
npm run start:env

The endpoints are:

• GET /health for a non-sensitive health response;
• POST /mcp for Streamable HTTP MCP requests.

When OPENCLAW_CODEX_MCP_BEARER_TOKEN is set, MCP requests must send Authorization: Bearer <token>.

Configuration

The server reads configuration from environment variables. It does not load .env automatically unless started with npm run start:env.

Variable	Default	Purpose
OPENCLAW_HOME	~/.openclaw	OpenClaw state root
OPENCLAW_WORKSPACE	$OPENCLAW_HOME/workspace	Approved OpenClaw workspace
OPENCLAW_CONFIG_PATH	$OPENCLAW_HOME/openclaw.json	OpenClaw configuration file
CODEX_HOME	~/.codex	Codex state root
CODEX_STATE_DB	$CODEX_HOME/state_5.sqlite	Codex task database
OPENCLAW_CODEX_MCP_ALLOWED_ROOTS	empty	Project roots allowed for Codex file/Git tools, separated with the platform path delimiter
OPENCLAW_BIN	openclaw	OpenClaw CLI executable
PYTHON_BIN	python3	Python executable for optional integrations
SQLITE_BIN	sqlite3	SQLite CLI executable
RG_BIN	rg	ripgrep executable
GIT_BIN	git	Git executable
PS_BIN	ps	process-list executable
OPENCLAW_MEMORY_SEARCH_SCRIPT	empty	Optional JSON memory-search adapter
CODEX_AUDIT_SCRIPT	empty	Optional JSON Codex audit adapter
OPENCLAW_CODEX_MCP_HOST	127.0.0.1	HTTP bind host
OPENCLAW_CODEX_MCP_PORT	19112	HTTP bind port
OPENCLAW_CODEX_MCP_BEARER_TOKEN	empty	Optional loopback auth; required for remote binding
OPENCLAW_CODEX_MCP_ALLOW_REMOTE	false	Explicit opt-in for non-loopback binding

Use absolute paths for configured roots and scripts. Keep tokens in a local secret manager or service environment, never in .env.example or Git.

Tool groups

OpenClaw tools cover:

• status, inventory, and credential-redacted configuration;
• durable tasks and task details;
• sessions and paginated operational transcripts;
• scheduled jobs and run history;
• sanitized logs and optional memory search;
• approved workspace listing, line-range reads, and literal search.

Codex tools cover:

• process and optional local-state audit status;
• task listing, task details, and paginated operational transcripts;
• task-workspace Git status and bounded diffs;
• approved workspace listing, line-range reads, and literal search.

See docs/TOOLS.md for the complete tool list and capability notes.

Optional adapter contracts

OPENCLAW_MEMORY_SEARCH_SCRIPT must accept --query <text> --json and print one JSON object. If it has a results array, the MCP server applies the requested result limit before redaction.

CODEX_AUDIT_SCRIPT must accept --json and print one JSON object. Without it, the Codex status tool still reports process presence and marks the extended audit unavailable.

Verification

npm test
npm run verify:public

The public-readiness check verifies required governance files, rejects private package configuration, and scans the working tree for known private deployment markers and fixed machine-specific executable paths. CI runs the same verification on every pull request and push to main.

Project boundaries

Deployment-specific service files, reverse tunnels, SSH policy, tokens, production hostnames, and machine-local paths do not belong in this repository. A Git merge never authorizes or performs deployment.

Codex local state formats and some OpenClaw extensions can evolve. Compatibility fixes should preserve the read-only, allowlisted, redacted interface and add regression tests for every newly supported shape.

Contributing

See CONTRIBUTING.md. Security reports should follow SECURITY.md.

Release history is recorded in CHANGELOG.md.

License

MIT