v1.5.2 — PDF text extraction via pypdf

Fixed

• PDF content unreadable (root cause found) — the ~1.3 MB base64-encoded PDF body was exceeding OpenClaw's internal gateway body limit, causing an immediate TCP reset caught as ReadError → 502 in under 100 ms. Replaced base64 binary forwarding with server-side text extraction using pypdf: Claude now receives the extracted text content of the PDF as a plain text block, which is 10–100× smaller and actually readable.

Added

• pypdf>=4.0.0 dependency for PDF text extraction

Notes

• Scanned/image-only PDFs (no extractable text layer) will receive a (no extractable text — may be a scanned image) placeholder
• Encrypted or corrupted PDFs fall back to (could not parse)

🤖 Generated with Claude Code

v1.5.1 — Telegram PDF + timeout fixes

Fixed

• PDF content unreadable by Claude — changed PDF content block to Anthropic-native "document" format; Claude was ignoring the previous "file" block and saying it couldn't see the attachment
• send_response ConnectTimeout — explicit httpx.Timeout(connect=10s, read=30s) on Telegram sendMessage calls; eliminates connection timeouts sending replies back to users
• Video/unsupported binary silent drop — sends [video: filename] text placeholder instead of silently omitting content
• httpx.ReadError unhandled — _forward_to_upstream now catches ReadError gracefully (was causing HTTP 500 → Telegram infinite retry loop)
• Replay protection returning 409 — changed to 200 so Telegram marks webhook delivered and moves on instead of retrying indefinitely
• File download read timeout — increased from default 5 s to 120 s for large files

🤖 Generated with Claude Code

v1.5.0 - Telegram File Attachment Support

What's New

Added

• Telegram file attachment support — the bot now processes images, PDFs, documents, audio, voice messages, video, and stickers instead of silently ignoring them
  • Two-step Telegram API download (getFile → binary fetch) with 20 MB cap pre- and post-download
  • Attachments forwarded to the upstream LLM as OpenAI multimodal content blocks (image_url, input_audio, file)
  • Captions on media messages are treated as the message text
  • download_file() and build_attachments() methods on TelegramRelay; individual download failures are skipped gracefully
  • AttachmentType enum and Attachment dataclass in src/webhook/models.py
  • WEBHOOK_FILE_DOWNLOAD audit event type for per-file download telemetry

Fixed

• Attachment filename prompt injection (P1) — filenames from the Telegram payload are now sanitized through PromptSanitizer before entering conversation history; injected filenames fall back to their generic type label
• Silent drop on all-download-failure (P2) — when all attachment downloads fail on a file-only message, the bot now sends the user an actionable error instead of silently returning HTTP 200
• Body size check accuracy — size limit now uses exact base64-encoded byte count (n + 2) // 3 * 4 (was ~33% under-counted)
• Dead code removed — _attachment_summary() module-level function deleted

Stats

• 10 files changed, +976 lines
• 570 tests passing

v1.4.2 - Multi-turn Conversation History

What's Changed

Added

• Per-session conversation history (src/webhook/history.py) — multi-turn Telegram/WhatsApp conversations now accumulate message context sent on every upstream request; previously each relay was a cold single-message call
  • In-memory ConversationHistory store keyed by {source}:{sender_id} to prevent cross-channel ID collisions (Telegram vs WhatsApp)
  • Configurable max_turns truncation to bound prompt size
  • TTL-based session eviction (default 24 h) to prevent unbounded memory growth from sender churn

Fixed

• Docker Compose paths — corrected build.context and config/ volume path in deploy/hybrid/docker-compose.hybrid.yml
• Reproducible Docker builds — uv.lock is now tracked in git (was gitignored), preventing COPY pyproject.toml uv.lock ./ failures in Docker builds

Full Changelog: https://github.com/yi-john-huang/openclaw-secure-stack/blob/master/CHANGELOG.md

v1.4.1 - Hybrid Deployment Bugfixes

What's Changed

Added

• plugins/prompt-guard/openclaw.plugin.json manifest added to source tree (required id and configSchema fields)
• Telegram Bot Setup documentation — new Part 5 in docs/openclaw-cloudflare-tunnel-setup.md covering BotFather registration, .env configuration, service restart, and setWebhook with secret_token
• Installer health checks — port-binding readiness check (ss :3000) and end-to-end proxy→OpenClaw connectivity test

Fixed

• systemd service — use gateway run (foreground process) instead of gateway start (daemon installer) in ExecStart
• Plugin config type — write plugins config as PluginsConfig object (not array); wrong type crashed the gateway on startup
• Gateway token — installer now reads the actual generated token from openclaw.json after onboarding instead of using a placeholder
• Dockerfile multi-arch — removed arm64-pinned digest (broke x86_64 builds); switched to named FROM stage for BuildKit compatibility

Full Changelog: https://github.com/yi-john-huang/openclaw-secure-stack/blob/master/CHANGELOG.md

v1.4.0 - Hybrid Deployment Architecture

🚀 What's New

Hybrid deployment architecture is now the primary and recommended deployment method, combining the best of both native and containerized approaches.

Architecture

Internet → Cloudflare Edge (optional) → Proxy (Docker) → OpenClaw (systemd) → LLM APIs

• OpenClaw Gateway: Native (systemd) for better OAuth and plugin support
• Security Proxy: Docker container for isolation and easy updates
• Cloudflare Tunnel: Optional public HTTPS access without port forwarding

---

✨ Key Features

One-Click Installer

• 11 automated phases from prerequisites to verification
• Integrated Cloudflare Tunnel setup (optional, interactive)
• OpenAI OAuth authentication flow
• Stable release strategy using Git tags
• Multi-architecture support (amd64 + arm64)

Usage

# Sync repository to server
rsync -avz --exclude='.git' --exclude='.venv' --exclude='node_modules' \
  openclaw-secure-stack/ user@server:/tmp/openclaw-secure-stack/

# Run one-click installer
ssh -t user@server \
  "cd /tmp/openclaw-secure-stack && sudo bash deploy/hybrid/install-hybrid.sh"

---

📦 What's Included

Added

• deploy/hybrid/install-hybrid.sh - One-click installer (609 lines)
• deploy/hybrid/docker-compose.hybrid.yml - Proxy configuration
• deploy/hybrid/README.md - Deployment guide
• docs/openclaw-cloudflare-tunnel-setup.md - Full tutorial (18 pages)
• docs/openclaw-quick-reference.md - Command reference (3 pages)

Changed

• README.md - Updated deployment documentation
• CHANGELOG.md - Full v1.4.0 changelog
• pyproject.toml - Version bump to 1.4.0

Removed

• deploy/native/ - Superseded by hybrid architecture (17 files, 2,533 lines)

---

🔧 Bug Fixes

Critical (P0-P1)

1. Audit logging enabled - Added AUDIT_LOG_PATH to docker-compose
2. OAuth permissions fixed - Recursive chown for .openclaw directory
3. HDD mount substitution - Custom paths properly honored
4. Hardcoded paths removed - Respects user configuration

Medium (P2)

5. rsync prerequisite - Added to package install list
6. ARM64 support - Architecture detection for cloudflared

Low (P3)

7. Documentation accuracy - Corrected interactive prompt claims

---

⚠️ Breaking Changes

Native deployment removed - The fully-native deployment option has been superseded by the hybrid architecture.

Migration Path

If you're on v1.3.0 native deployment:

# 1. Backup existing data
sudo tar -czf ~/openclaw-backup.tar.gz \
  /var/lib/openclaw \
  /var/lib/openclaw-proxy \
  /etc/openclaw-secure-stack

# 2. Stop old services
sudo systemctl stop openclaw openclaw-proxy caddy

# 3. Run hybrid installer
cd /tmp/openclaw-secure-stack
sudo bash deploy/hybrid/install-hybrid.sh

# 4. Restore configuration if needed

---

📊 Statistics

• 23 files changed: +1,727 / -2,647 lines
• Net reduction: -920 lines (more functionality with less code)
• Code review: 8 issues addressed (2 from automated review, 6 from manual)
• Architecture: Hybrid (native + Docker)
• Multi-arch: amd64 + arm64

---

📖 Documentation

• Cloudflare Tunnel Setup Guide
• Quick Reference
• Hybrid Deployment README
• CHANGELOG

---

🙏 Credits

This release was developed with assistance from Claude Sonnet 4.5.

Full Changelog: v1.3.0...v1.4.0

v1.3.0 - Native Deployment for Ubuntu 24.04 LTS

🎉 What's New in v1.3.0

Native Deployment for Ubuntu 24.04 LTS

This release introduces native systemd deployment as a lightweight alternative to Docker Compose, perfect for resource-constrained environments like VPS or edge devices.

✨ New Features

• 🚀 Interactive Installer (deploy/native/install-native.sh)

  • One-command deployment with guided configuration
  • Automatic dependency installation (Python 3.12, Node.js, Caddy, uv)
  • Configurable HDD mount point for backups and audit logs
  • Optional Telegram and WhatsApp webhook setup

• 🔒 Security Hardening

  • systemd sandboxing (ProtectSystem=strict, NoNewPrivileges)
  • Minimal file permissions (separate users: openclaw, ocproxy)
  • Read-only filesystems with explicit write paths
  • Capability dropping and namespace restrictions

• 🌐 Caddy Reverse Proxy

  • Automatic HTTPS with Let's Encrypt (domain mode)
  • Self-signed TLS for localhost testing
  • HTTP/2 and WebSocket support

• 📊 Operational Tools

  • Health check script (openclaw-health-check) for monitoring
  • Daily automated backups to configurable location (30-day retention)
  • Uninstaller for clean removal

• 📖 Comprehensive Documentation

  • Deployment guide (deploy/native/DEPLOYMENT.md)
  • Docker vs native comparison (deploy/native/COMPARISON.md)
  • Verification checklist for production readiness

🐛 Bug Fixes

Fixed 3 critical installer issues discovered in code review (PR #9):

1. Missing /etc/caddy/ directory - Installer now creates directory before copying Caddyfile (was crashing at Phase 8)
2. Missing caddy.service - Added systemd unit file for manually-installed Caddy binary (was failing systemctl enable caddy)
3. Hardcoded /mnt/data paths - Replaced with ${HDD_MOUNT} template variable with sed substitution during installation (was causing silent audit log data loss)

All files now use proper templating with runtime configuration substitution.

📦 Installation

Docker Compose (existing):

git clone https://github.com/yi-john-huang/openclaw-secure-stack.git
cd openclaw-secure-stack
docker compose up -d

Native systemd (new):

git clone https://github.com/yi-john-huang/openclaw-secure-stack.git
cd openclaw-secure-stack
sudo ./deploy/native/install-native.sh

See deploy/native/DEPLOYMENT.md for detailed instructions.

📊 Test Coverage

✅ 529 tests passing (100% pass rate)

• 47 integration tests
• 482 unit tests
• Full coverage for proxy, governance, webhooks, and security scanner

🔗 Full Changelog

See CHANGELOG.md for complete details.

---

Upgrading from v1.2.0?

This release is additive (new deployment option). Existing Docker Compose deployments continue to work without changes. No breaking changes to APIs or configuration.

v1.1.0 - Pre-execution Governance Layer

🎉 Pre-execution Governance Layer

This release introduces a comprehensive security framework for controlling LLM tool execution before it happens.

✨ New Features

Governance Components:

• Intent Classifier — Categorizes tool calls into risk categories (file read/write, network, code execution, system)
• Plan Generator — Creates execution plans with risk assessment scores
• Policy Validator — Evaluates plans against configurable rules:
  • Action policies (category-based allow/deny/require approval)
  • Resource policies (path/URL pattern matching)
  • Sequence policies (forbidden action combinations)
  • Rate policies (session-based limits)
• Approval Gate — Human-in-the-loop approval for high-risk operations
• Execution Enforcer — Validates tool calls against approved plans
• Session Manager — Tracks multi-turn conversations with rate limiting

Configuration:

• config/governance-policies.json — Policy rules
• config/intent-patterns.json — Intent classification patterns

🔒 Security Improvements

• TOCTOU race condition prevention via atomic SQL operations
• HMAC-signed plan tokens with constant-time comparison
• Atomic compare-and-swap for approval state transitions
• Session-based rate limiting

📊 Stats

• 214 new tests added (389 total)
• 9,900+ lines of new code
• 29 files changed

📖 Documentation

• Updated README with governance architecture
• Added SDD specification in .spec/specs/governance-layer/

---

Full Changelog: v1.0.1...v1.1.0