Python 打造极简 OpenClaw Agent：openclaw-mini 架构解析
如果你关注过 OpenClaw 这个项目，可能会觉得它功能完整但结构相对复杂，而且不是用 Python 实现。对于很多想快速搭建一个本地运行的 Discord AI 助手的开发者来说，可能更希望有一个架构更简单、全 Python 实现、不需要自己封装 OpenAI API 且本地运行即可的方案。
这时候，我非常推荐看看这个项目：openclaw-mini。它是一个 OpenClaw 风格的'极简版本'，专注在一个清晰的路径上：Discord + 本地 Codex CLI + Markdown 驱动的行为定义。
openclaw-mini 是什么？
openclaw-mini 是一个最小可用的 OpenClaw 风格 Agent，专注做三件事：
- 使用 Discord 作为输入输出通道
- 使用本地 Codex CLI 执行模型推理
- 使用
SOUL.md+skills/*.md定义行为
没有复杂的多 Agent 管理，没有庞大的中间层抽象。它的核心目标是做一个你能在一个下午完整读懂的 AI Agent 架构。
运行机制：非常干净的一条主线
读过代码之后，你会发现整个控制流非常清晰。
1. 启动入口：main.py
加载环境变量，启动 Discord 客户端。没有额外框架，没有复杂生命周期管理。
2. bot.py：处理消息
当收到 Discord 消息时，它会过滤 bot 自己发的消息，并处理内置命令：
/help/skills/soul
如果不是命令，则进入模型处理流程。
3. 构造提示词（Prompt 拼接）
普通消息会被封装为一个完整 instruction，包含：
SOUL.md的内容（Agent 的人格和行为原则）skills/*.md的所有技能卡片内容- 用户原始消息
它的思路是用 Markdown 驱动行为，而不是在代码里写大量逻辑。这是一种非常干净的'提示工程驱动架构'。
4. llm.py：调用本地 Codex CLI
这里是最有意思的设计。它不在 Python 里直接调用 OpenAI API，而是调用：
codex exec --json --output-last-message
然后读取模型的最终输出。也就是说，Python 只负责 I/O 和流程，模型会话由 Codex CLI 管理，对话状态由 Codex CLI 线程维护。
本地 Codex 会话的设计：非常聪明
每一个 Discord 会话会映射到一个持久化 Codex thread ID。线程信息保存在 .codex-discord-sessions.json，并支持 TTL 过期控制（CODEX_SESSION_TTL_SEC）、超时自动重建以及会话持续上下文。
这样做的好处是：
- 不需要自己实现对话历史拼接
- 不需要维护 token 限制逻辑
- 不需要管理复杂的 API session
全部交给 Codex CLI。
为什么这个设计很实用？
对于个人开发者或小团队，这种架构有几个明显优势。
可读性极高
整个代码量很小，逻辑线性。你可以在一个晚上完全理解消息如何进来、Prompt 如何构造、模型如何调用以及会话如何持久化。
本地迭代极快
你只需要安装 openAI Codex CLI，配置 Discord Token，修改 Markdown 文件。改完 SOUL.md 或某个 skill 文件，重启即可生效。
运维非常轻量
项目已经包含 systemd 模板、launchd 模板以及环境变量控制参数（如 CODEX_SANDBOX、approval 策略、超时时间、模型选择）。这意味着它是'最小可生产部署'的结构。
它适合什么人？
如果你想做一个 Discord 专用 AI 助手、一个本地可控的 Agent、一个可以完全理解其内部机制的系统，或者一个纯 Python 技术栈项目，那么 openclaw-mini 是非常合适的起点。
和完整 OpenClaw 的区别
| 对比项 | OpenClaw | openclaw-mini |
|---|---|---|
| 架构复杂度 | 高 | 低 |
| 语言 | 非 Python | ✅ Python |
| 多 Agent 支持 | 强 | 简化 |
| 上手难度 | 偏高 | ✅ 非常友好 |
| 适合人群 | 进阶构建者 | ✅ 快速原型开发者 |
如果你觉得 OpenClaw 太重、太抽象、太工程化，openclaw-mini 是一个非常好的'轻量入口'。
总结
openclaw-mini 做了一件很聪明的事情：把复杂性留给 Codex CLI，把结构简化到最小。Discord 负责输入输出，Markdown 负责行为定义，Codex 负责推理，Python 负责连接。这是一种非常'Unix 哲学'的设计方式：每个组件做好一件事。
如果你正在考虑做一个本地 AI Discord Agent，我建议从它开始，而不是一上来就搭一个复杂框架。
