日期: 2026-03-28
问题类型: 环境配置 + 记忆系统
影响范围: Calibre 同步脚本 + 用户信任
一、问题回顾：一场持续 5 轮的"拉扯"
时间线
用户成本: 反复确认 5 次，耗时约 2 小时，信任度下降
二、技术层面：OpenClaw 的 Python 环境现状
2.1 环境清单
# 系统 Python（uv 管理）
~/.local/bin/python3 → Python 3.12.11
# uv Python（项目使用）
uv run python3 → Python 3.13.5
# 项目 venv（未使用）
~/.openclaw/workspace/.venv/ → 存在但未激活
2.2 脚本 shebang 统计
72 个脚本：#!/usr/bin/env python3 → 系统 Python
1 个脚本：#!/usr/bin/env uv run python3 → uv Python
2.3 模块安装位置
| | |
pip3 install | | |
uv pip install | | |
核心矛盾: sync-calibre-to-obsidian.py 使用 uv run python3，但 html2text 被安装在系统 Python
三、记忆系统层面：为什么每次都给出不同答案？
3.1 我的记忆架构
┌─────────────────────────────────────────────────────────┐
│ 对话上下文 (Conversation Context) │
│ - 仅在当前会话有效 │
│ - 会话结束即丢失 │
│ - 容量有限，早期内容可能被截断 │
├─────────────────────────────────────────────────────────┤
│ HEARTBEAT.md (持久化记忆) │
│ - 每次 heartbeat 都会读取 │
│ - 手动更新，不会自动记录 │
│ - 本次问题发生前，没有 Python 环境相关记录 │
├─────────────────────────────────────────────────────────┤
│ 工具执行结果 (Tool Output) │
│ - 每次 exec 都是独立执行 │
│ - 不保留历史执行记录 │
│ - 环境变化无法追溯 │
└─────────────────────────────────────────────────────────┘
3.2 为什么答案会冲突
| | |
| 无持久化环境记录 | HEARTBEAT.md 未记录 Python 配置 | |
| 工具执行独立性 | python3 -c "import x" vs uv run python3 -c "import x" | |
| 会话不连续 | | |
| 环境动态变化 | | |
3.3 根本问题
OpenClaw 没有"环境配置清单"机制
❌ 没有记录：
- 项目使用哪个 Python 解释器
- 已安装哪些模块
- 每个脚本的运行时环境
❌ 导致：
- 每次排查都要重新检查
- 无法追溯环境变化
- 用户需要反复确认同一问题
四、对比其他项目：成熟框架的做法
4.1 Poetry (Python 项目管理)
# pyproject.toml
[tool.poetry]
python = "^3.12"
[tool.poetry.dependencies]
html2text = "^2025.4.15"
特点:
- • ✅
poetry install 一次性安装所有依赖
4.2 Node.js (package.json)
{
"engines":{"node":">=20.0.0"},
"dependencies":{"html2text":"^1.0.0"}
}
特点:
4.3 OpenClaw 现状
❌ 无 pyproject.toml
❌ 无 requirements.txt
❌ 无 Python 版本声明
❌ 脚本 shebang 不统一
❌ 模块安装位置不明确
五、解决方案：三层改进
5.1 短期修复（已完成）
| | |
| | #!/usr/bin/env uv run python3 |
| | uv pip install html2text |
| | |
5.2 中期改进（建议实施）
A. 创建项目依赖文件
# /Users/pansinliu/.openclaw/workspace/pyproject.toml
[project]
name = "openclaw-workspace"
version = "1.0.0"
requires-python = ">=3.12"
dependencies = [
"html2text>=2025.4.15",
# 其他依赖...
]
[tool.uv]
dev-dependencies = []
B. 统一脚本 shebang
# 批量修改所有脚本
find scripts/ -name "*.py" -exec sed -i '''1s|^#!/usr/bin/env python3$|#!/usr/bin/env uv run python3|' {} \;
C. 创建环境检查脚本
#!/usr/bin/env uv run python3
# scripts/check-environment.py
import sys
import importlib
REQUIRED_MODULES = ['html2text', 'fitz', 'pptx']
print(f"Python: {sys.executable}")
print(f"Version: {sys.version}")
for module in REQUIRED_MODULES:
try:
m = importlib.import_module(module)
print(f"✅ {module}: {getattr(m, '__version__', 'unknown')}")
except ImportError:
print(f"❌ {module}: 未安装")
5.3 长期改进（架构层面）
A. OpenClaw 环境配置规范
# 建议添加到 OpenClaw 文档
## Python 环境配置
1.**统一使用 uv 管理 Python 环境**
- 项目根目录创建 `pyproject.toml`
- 所有脚本使用 `#!/usr/bin/env uv run python3`
- 模块安装使用 `uv pip install`
2.**环境检查命令**
```bash
# 检查 Python 版本
uv run python3 --version
# 检查模块
uv run python3 -c "import module"
# 安装模块
uv pip install module
- • 在 HEARTBEAT.md 顶部记录环境配置
#### B. 记忆系统改进建议
| 改进项 | 当前状态 | 建议状态 |
|--------|----------|----------|
| 环境配置 | 无记录 | HEARTBEAT.md 固定章节 |
| 模块清单 | 无记录 | `requirements.txt` 或 `pyproject.toml` |
| 变更历史 | 无追溯 | 环境变更日志 |
| 检查工具 | 手动执行 | `scripts/check-environment.py` |
---
## 六、本次教训：给未来的自己
### 6.1 排查问题的正确顺序
- 1. 确认脚本 shebang → 使用哪个 Python
- 2. 检查模块安装位置 → uv pip list vs pip3 list
- 3. 验证导入 → uv run python3 -c "import module"
- 4. 记录结论 → 更新 HEARTBEAT.md
### 6.2 避免重复问题的检查清单
- [ ] 脚本 shebang 是否统一？
- [ ] 模块安装在哪个 Python 环境？
- [ ] 是否有依赖管理文件？
- [ ] 环境配置是否持久化记录？
- [ ] 是否有环境检查工具？
### 6.3 给用户的建议
```bash
# 1. 创建项目依赖文件
cd /Users/pansinliu/.openclaw/workspace
uv init --no-workspace
uv add html2text fitz pymupdf python-pptx
# 2. 统一脚本 shebang
find scripts/ -name "*.py" -type f -exec sed -i '' '1s|.*|#!/usr/bin/env uv run python3|' {} \;
# 3. 创建环境检查脚本
# (见 5.2.C)
# 4. 更新 HEARTBEAT.md
# (已完成)
七、总结
问题本质
已完成的改进
- • ✅ HEARTBEAT.md 已记录环境配置规范
待实施的改进
最后的话:
这次问题表面是"html2text 是否安装"，实质是OpenClaw 缺乏 Python 环境管理规范。
技术债务不会自动消失，只会越积越多。今天花 1 小时创建 pyproject.toml，明天就能避免 5 小时的反复排查。
行动建议: 立即创建项目依赖文件，统一 Python 环境。
