My personal OpenAI Codex assistant that runs securely in containers. Lightweight and built to be understood and customized for your own needs.
OpenClaw is an impressive project with a great vision. But I can't sleep well running software I don't understand with access to my life. OpenClaw has 52+ modules, 8 config management files, 45+ dependencies, and abstractions for 15 channel providers. Security is application-level (allowlists, pairing codes) rather than OS isolation. Everything runs in one Node process with shared memory.
NanoClaw gives you the same core functionality in a codebase you can understand in 8 minutes. One process. A handful of files. Agents run in actual Linux containers with filesystem isolation, not behind permission checks.
git clone https://github.com/chrisfrantz/nanoclaw.git
cd nanoclaw
codexThen run /setup. Codex CLI handles everything: dependencies, authentication, container setup, service configuration.
Small enough to understand. One process, a few source files. No microservices, no message queues, no abstraction layers. Have Codex CLI walk you through it.
Secure by isolation. Agents run in Linux containers (Apple Container on macOS, or Docker). They can only see what's explicitly mounted. Bash access is safe because commands run inside the container, not on your host.
Built for one user. This isn't a framework. It's working software that fits my exact needs. You fork it and have Codex CLI make it match your exact needs.
Customization = code changes. No configuration sprawl. Want different behavior? Modify the code. The codebase is small enough that this is safe.
AI-native. No installation wizard; Codex CLI guides setup. No monitoring dashboard; ask Codex what's happening. No debugging tools; describe the problem, Codex fixes it.
Skills over features. Contributors shouldn't add features (e.g. support for Telegram) to the codebase. Instead, they contribute Codex playbooks (skills) like /add-telegram that transform your fork. You end up with clean code that does exactly what you need.
Best harness, best model. This runs on the Codex CLI, which means you're running OpenAI's coding agent directly. The harness matters. A bad harness makes even smart models seem dumb, a good harness gives them superpowers.
No ToS gray areas. It uses OpenAI Codex with supported authentication flows and standard CLI tooling.
- Telegram I/O - Message Codex from your phone or desktop
- Single-owner DM - Locked to one Telegram user id (no groups)
- Persistent memory -
groups/main/MEMORY.md+ injecteddocs/SOUL.md - Local-only notes - Persistent, gitignored notes at
data/notes/main/(mounted at/workspace/notes) - Scheduled tasks - Recurring jobs that run Codex and can message you back
- Web + browser automation - shell tools +
agent-browserinside the container - Container isolation - Agents sandboxed in Apple Container (macOS) or Docker (macOS/Linux)
- Deploy keys - Persistent SSH keys at
data/ssh/main/(mounted at/home/node/.ssh)
Just message your assistant (no trigger required; @Andy is optional and stripped if present):
send an overview of the sales pipeline every weekday morning at 9am
review the git history for the past week each Friday and update the README if there's drift
every Monday at 8am, compile news on ai developments and message me a briefing
Model control:
model status
model auto
model code
model gpt-5.2-codex high
There are no configuration files to learn. Just tell Codex CLI what you want:
- "Change the trigger word to @Bob"
- "Remember in the future to make responses shorter and more direct"
- "Add a custom greeting when I say good morning"
- "Store conversation summaries weekly"
Or run /customize for guided changes.
The codebase is small enough that Codex can safely modify it.
Don't add features. Add skills.
If you want to add WhatsApp support, don't create a PR that adds WhatsApp alongside Telegram. Instead, contribute a skill file (.codex/skills/add-whatsapp/SKILL.md) that teaches Codex CLI how to transform a NanoClaw installation to use WhatsApp.
Users then run /add-telegram on their fork and get clean code that does exactly what they need, not a bloated system trying to support every use case.
Skills we'd love to see:
Communication Channels
/add-whatsapp- Add WhatsApp as channel. Should give the user option to replace Telegram or add as additional channel. Also should be possible to add it as a control channel (where it can trigger actions) or just a channel that can be used in actions triggered elsewhere/add-slack- Add Slack/add-discord- Add Discord
Platform Support
/setup-windows- Windows via WSL2 + Docker
Session Management
/add-clear- Add a/clearcommand that compacts the conversation (summarizes context while preserving critical information in the same session).
- macOS or Linux
- Node.js 20+
- Codex CLI
- Apple Container (macOS) or Docker (macOS/Linux)
Telegram (Bot API) --> SQLite --> Polling loop --> Container (Codex CLI) --> Response
Single Node.js process. Agents execute in isolated Linux containers with mounted directories. IPC via filesystem. No daemons, no queues, no complexity.
Key files:
src/index.ts- Main app: Telegram connection, routing, IPCsrc/container-runner.ts- Spawns agent containerssrc/task-scheduler.ts- Runs scheduled taskssrc/db.ts- SQLite operationsgroups/main/MEMORY.md- Long-term memory (single DM)docs/SOUL.md- Agent voice and response guidelinesdocs/DEPLOY_KEYS.md- Persistent SSH deploy keyscontainer/shell.sh- Drop into the agent container (debug)
Why Telegram and not WhatsApp/Signal/etc?
Because I use Telegram. Fork it and run a skill to change it. That's the whole point.
Why Apple Container instead of Docker?
On macOS, Apple Container is lightweight, fast, and optimized for Apple silicon. But Docker is also fully supported—during /setup, you can choose which runtime to use. On Linux, Docker is used automatically.
Can I run this on Linux?
Yes. Run /setup and it will automatically configure Docker as the container runtime. Thanks to @dotsetgreg for contributing the /convert-to-docker skill.
Is this secure?
Agents run in containers, not behind application-level permission checks. They can only access explicitly mounted directories. You should still review what you're running, but the codebase is small enough that you actually can. See docs/SECURITY.md for the full security model.
Why no configuration files?
We don't want configuration sprawl. Every user should customize it to so that the code matches exactly what they want rather than configuring a generic system. If you like having config files, tell Codex to add them.
How do I debug issues?
Ask Codex CLI. "Why isn't the scheduler running?" "What's in the recent logs?" "Why did this message not get a response?" That's the AI-native approach.
Why isn't the setup working for me?
I don't know. Run codex, then run /debug. If Codex finds an issue that is likely affecting other users, open a PR to modify the setup SKILL.md.
What changes will be accepted into the codebase?
Security fixes, bug fixes, and clear improvements to the base configuration. That's it.
Everything else (new capabilities, OS compatibility, hardware support, enhancements) should be contributed as skills.
This keeps the base system minimal and lets every user customize their installation without inheriting features they don't want.
MIT