用 Python 打造一个极简OpenClaw Agent —— openclaw-mini

如果你关注过 OpenClaw 这个项目，可能会觉得它功能完整但结构相对复杂，而且不是用 Python 实现。

对于很多想快速搭建一个 本地运行的 Discord AI 助手 的开发者来说，可能更希望有一个：

• 架构更简单
• 全 Python 实现
• 不需要自己封装 OpenAI API
• 本地运行即可

这时候，我非常推荐看看这个项目：

👉 openclaw-mini
Repo: https://github.com/robotlearner001/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。

为什么这个设计很实用？

对于个人开发者或小团队，这种架构有几个明显优势：

✅ 1. 可读性极高

整个代码量很小，逻辑线性。

你可以在一个晚上完全理解：

• 消息如何进来
• Prompt 如何构造
• 模型如何调用
• 会话如何持久化

✅ 2. 本地迭代极快

你只需要：

1. 安装 openAI Codex CLI
2. 配置 Discord Token
3. 修改 Markdown 文件

改完 SOUL.md 或某个 skill 文件，重启即可生效。

✅ 3. 运维非常轻量

项目已经包含：

• systemd 模板
• launchd 模板
• 环境变量控制参数：
  • CODEX_SANDBOX
  • approval 策略
  • 超时时间
  • 模型选择

这意味着：

它是“最小可生产部署”的结构。

它适合什么人？

如果你想做：

• 🎯 一个 Discord 专用 AI 助手
• 🧠 一个本地可控的 Agent
• 🛠 一个可以完全理解其内部机制的系统
• 🐍 一个纯 Python 技术栈项目

那么 openclaw-mini 是非常合适的起点。

和完整 OpenClaw 的区别

如果你觉得 OpenClaw 太重、太抽象、太工程化，
openclaw-mini 是一个非常好的“轻量入口”。

总结

openclaw-mini 做了一件很聪明的事情：

把复杂性留给 Codex CLI，把结构简化到最小。

Discord 负责输入输出，
Markdown 负责行为定义，
Codex 负责推理，
Python 负责连接。

这是一种非常“Unix 哲学”的设计方式：
每个组件做好一件事。

如果你正在考虑做一个本地 AI Discord Agent，
我建议从它开始，而不是一上来就搭一个复杂框架。

Repo

🔗 https://github.com/robotlearner001/openclaw-mini

如果你已经在用 OpenClaw 或在做自己的 Agent 框架，也欢迎交流思路。
极简架构，有时候反而是最强的起点。

英文参考

OpenClawAgent