OpenClaw is an open-source AI agent framework that converts large language models into persistent, autonomous workers capable of long-term planning, tool orchestration, and memory-intensive workflows. The v2026.4.11-beta.1 release introduces Dreaming/memory-wiki capabilities with ChatGPT import ingestion, allowing agents to absorb years of conversation history into structured memory palaces. This guide walks you through building a production-ready agent with imported insights, embedded video generation, and secure local deployment.
You will construct an agent that ingests your ChatGPT export, organizes memories into the new Memory Palace diary structure, and generates video content using the updated tools/video_generate provider with URL-only delivery. By the end, you will have a fully configured OpenClaw instance running the beta release with persistent memory-wiki storage and plugin activation descriptors for secure tool management.
What You’ll Build Today with OpenClaw
You are building a persistent AI agent with long-term memory capabilities using OpenClaw v2026.4.11-beta.1. The finished system imports your ChatGPT conversation history via the new ingestion pipeline, stores vectors in a local memory-wiki database, and exposes three specialized interfaces: Imported Insights for raw chat inspection, compiled wiki pages for semantic retrieval, and the Memory Palace diary for temporal narrative reconstruction. This setup enables your agent to leverage your personal conversational history for more nuanced and contextually aware interactions.
Your agent will support video generation with typed providerOptions and reference audio inputs, configured through plugin manifests that declare activation descriptors for authorization flows. The Control UI renders assistant media through structured chat bubbles using the new [embed ...] rich output tag, with external URLs gated behind security configurations. You will also configure Ollama caching for local LLM discovery and set up Feishu document comment sessions with reaction support, demonstrating OpenClaw’s extensive integration capabilities.
Prerequisites for OpenClaw Development
To get started with OpenClaw, you need Node.js 20.11.0 or later and Python 3.11+ installed system-wide. For production-grade memory-wiki storage, install PostgreSQL 14+ with the pgvector extension. Alternatively, for development deployments, ensure SQLite 3.45+ is available. If you plan to test the import ingestion feature, a ChatGPT export file (specifically conversations.json) is essential.
For local LLM support, install Ollama 0.3.0+. Have Docker 25+ ready for containerized deployment options, which can streamline your setup. You need a minimum of 8GB free RAM, with 16GB recommended, especially for memory-intensive tasks like video generation workflows. A valid API key for OpenAI, Anthropic, or your chosen local provider is required depending on your provider choice. For Teams integration, prepare Azure AD credentials with delegated OAuth permissions to enable full functionality.
Installing OpenClaw v2026.4.11-beta.1
To begin, install the beta CLI globally using npm. This beta channel provides access to the latest Dreaming/memory-wiki features and the unified execution model, which significantly improves upon the legacy nodesrun architecture. This ensures you are working with the most current and performant version of OpenClaw.
npm install -g @openclaw/cli@beta
openclaw --version
# Expected: 2026.4.11-beta.1Next, initialize your project directory with the new template structure. This command automatically creates the memory-wiki/ directory for vector storage and the diary/ subdirectory for Memory Palace entries, setting up the foundational components for your agent’s long-term memory.
mkdir ~/openclaw-agent && cd ~/openclaw-agent
openclaw init --template=memory-palace --betaFinally, verify your installation by checking for the new subtabs configuration. The CLI should generate config/dreaming.yaml with sections for imported_insights and memory_palace enabled by default, confirming that your OpenClaw environment is correctly set up and ready for advanced memory management.
Understanding the Dreaming Architecture in OpenClaw
Dreaming is OpenClaw’s robust, persistent memory system designed to go beyond basic Retrieval Augmented Generation (RAG) by maintaining temporal context and narrative coherence across multiple sessions. This sophisticated architecture is structured into three distinct layers, each playing a critical role in how your agent processes, stores, and retrieves information. This multi-layered approach allows for a deeper understanding and utilization of conversational history.
The first layer is the ingestion layer, responsible for processing incoming data, including ChatGPT imports and live chat interactions. This raw data is then passed to the compilation layer, which transforms these raw conversations into structured wiki pages complete with semantic embeddings. These embeddings are crucial for efficient and contextually accurate retrieval. The final layer is the palace layer, which reconstructs chronological narratives, forming the basis for diary entries. This comprehensive system ensures that your agent not only remembers facts but also understands the context and flow of past interactions.
The memory-wiki stores vector embeddings in PostgreSQL with the pgvector extension, while associated metadata resides in relational tables for structured access. When your agent “dreams,” it queries the palace layer to reconstruct context from imported insights, then consults compiled wiki pages for factual grounding. This process significantly differs from standard RAG because it preserves the conversational flow and emotional context from your ChatGPT history, providing a richer, more human-like memory, rather than just isolated facts.
Configuring ChatGPT Import Ingestion
To leverage your past conversations, place your conversations.json export file, obtained directly from ChatGPT, into the imports/ directory within your OpenClaw project. A key feature of OpenClaw is its commitment to data privacy: the framework processes this data locally, ensuring that no sensitive information is sent to external APIs during the ingestion process. This local processing offers a secure way to integrate your personal data.
mkdir -p imports
cp ~/Downloads/conversations.json imports/
openclaw import chatgpt --file=imports/conversations.json --sanitizeThe --sanitize flag is crucial as it triggers PII (Personally Identifiable Information) redaction, using local regex patterns to remove sensitive data before it is stored. This adds an extra layer of privacy protection. You can further fine-tune the ingestion behavior by configuring parameters in config/dreaming.yaml, allowing you to control aspects like batch size and embedding models.
ingestion:
batch_size: 100
embedding_model: "text-embedding-3-small"
palace_integration: true
sanitize_imports: trueThe import process generates three distinct data structures: raw source chats, which are accessible via Imported Insights; compiled wiki pages, which consist of chunked embeddings for efficient retrieval; and full source pages, preserved for verbatim retrieval. The processing time for ingestion scales linearly with the number of conversations; typically, you can expect about 2 minutes per 10,000 messages on standard hardware, making it a scalable solution for large datasets.
Setting Up Memory-Wiki Persistence
Establishing robust persistence for your memory-wiki is a critical step in building a reliable OpenClaw agent. Begin by configuring your vector database connection, which will store the intricate embeddings that power your agent’s memory. For local development, you have the flexibility to use SQLite, ensuring you specify the correct vec0 extension path. For production environments, the recommended approach is to utilize PostgreSQL with the pgvector extension for enhanced performance and scalability.
# config/database.yaml
memory_wiki:
provider: postgres
host: localhost
port: 5432
database: openclaw_memory
vector_dimension: 1536
# Caching for Ollama model metadata
ollama_cache_ttl: 3600Once your database configuration is set, you need to initialize the schema using the OpenClaw CLI. This action creates the necessary tables for imported insights, wiki pages, and palace diary entries, along with proper indexing to optimize retrieval performance. This ensures that your agent can efficiently store and access its long-term memories.
openclaw db migrate --target=dreaming
openclaw db verify --check=pgvectorThe migration process specifically adds the imported_insights and memory_palace subtabs to your database schema. These additions are fundamental as they enable the new UI components introduced in OpenClaw v2026.4.11-beta.1, providing a visual interface for managing and exploring your agent’s comprehensive memory system.
Navigating Imported Insights Subtabs
The Control UI in OpenClaw v2026.4.11-beta.1 features a dedicated subtab for rendering your imported ChatGPT conversations, providing a streamlined way to review your historical interactions. You can access this view directly through the web interface at http://localhost:3000/dreaming/insights, or if you prefer a command-line approach, you can use the CLI for inspection.
openclaw diary inspect --source=imported --limit=50The Imported Insights view presents your original ChatGPT threads with all their associated metadata preserved. This includes timestamps, the model versions used, and any custom instructions that were part of the conversation. You can efficiently filter these conversations by date range or perform searches using vector similarity, allowing for precise retrieval of relevant information. The UI enhances readability by rendering these as structured chat bubbles, now with support for the new [embed ...] tag, which displays rich media that may have been present in your original conversations.
For programmatic access to these insights, your agent can query them directly through its context. This allows for dynamic retrieval and integration of past conversations into the agent’s current reasoning and planning processes, making its responses more informed and contextually relevant.
const insights = await agent.memory.query({
source: "imported",
timeframe: "2025-01-01/2025-12-31",
similarity_threshold: 0.85
});This programmatic interface ensures that your agent can seamlessly integrate historical context into its current operations, enabling more intelligent and personalized interactions.
Building Your First Memory Palace Diary
The Memory Palace diary is a powerful OpenClaw feature that transforms your disparate imported insights into a coherent, chronological narrative, providing your agent with a structured way to traverse its past experiences. To begin, you can initialize your first palace entry, strategically linking it to specific imported conversations to create a focused narrative.
openclaw palace create --title="Q1 2026 Project Context" \
--sources=imports/conversations.json \
--tags="work,planning,architecture"This action creates a new diary subtab entry that aggregates multiple imported chats into a single, coherent narrative thread. This structured approach allows your agent to reference these palace entries during its planning phases, ensuring continuity and consistency with your historical decision-making patterns. The agent can then draw upon this rich context to inform its current actions and recommendations, making its behavior more aligned with your past preferences and strategies.
You can further enhance the Memory Palace by configuring auto-compilation in config/palace.yaml. This enables the system to automatically generate and merge diary entries based on predefined criteria, ensuring that your agent’s memory remains current and organized without manual intervention.
compilation:
auto_generate: true
merge_window: "7d"
narrative_style: "chronological"The Memory Palace supports sophisticated cross-referencing capabilities between wiki pages (which typically store factual information) and diary entries (which capture experiential knowledge). This distinction allows agents to differentiate between what you know and how you learned it, providing a more nuanced understanding of your cognitive landscape. This dual-layered memory system enhances the agent’s ability to reason, adapt, and interact in a more human-like manner.
Implementing the Control UI with Embed Tags
The OpenClaw v2026.4.11-beta.1 Control UI significantly enhances how assistant outputs are presented, utilizing structured chat bubbles that now fully support the new [embed ...] rich output tag. This innovative feature empowers agents to reference external media resources directly within the chat interface without the need to load heavy assets directly into the chat context, optimizing performance and user experience.
To ensure security and control over external content, it is crucial to configure embed security within config/control.yaml. This configuration allows you to define strict rules regarding which domains are permitted to serve embedded content, preventing potential security vulnerabilities or data exfiltration attempts.
ui:
embed:
enabled: true
allowed_domains: ["cdn.openclaw.io", "localhost:8080"]
require_signed_urls: trueOnce configured, your agent can seamlessly use the embed tag within its skill definitions to display various media types. For instance, an agent can share an analysis complete with a visual representation, directly embedding an image with a descriptive title.
agent.say("Analysis complete. [embed url=\"https://cdn.openclaw.io/viz-123.png\" type=\"image\" title=\"Resource Graph\"]");The UI intelligently gates external embed URLs, validating them against your security configuration before rendering. This proactive measure prevents malicious agent outputs from introducing unauthorized content. Furthermore, media directives are rendered as collapsible bubbles, and when audio references are attached, they include integrated voice playback controls, offering a rich and interactive user experience. This comprehensive approach to embeds balances functionality with robust security.
Configuring Video Generation Tools
The updated video_generate tool in OpenClaw introduces significant enhancements designed to improve efficiency and flexibility for creating dynamic content. A key improvement is the support for URL-only asset delivery, a feature that prevents memory bloat by eliminating the need to download large video files directly into the agent’s memory. Instead, only the reference URL is returned, making the process much more lightweight.
This tool also now supports typed providerOptions for vendor-specific parameters, allowing for precise control over video generation settings. Additionally, it integrates reference audio inputs, which are particularly useful for advanced workflows like lip-sync, ensuring that generated video content is perfectly synchronized with accompanying audio.
You can configure a video generation skill within skills/video.yaml, specifying parameters like the provider, delivery mode, and various provider-specific options.
tools:
video_generate:
provider: "runway-ml"
delivery: "url-only" # Prevents large file downloads
providerOptions:
resolution: "1080p"
duration: 10
adaptive: true # New aspect-ratio support
reference_audio:
enabled: true
input_role: "voice_over"The URL-only delivery mode ensures that all generated assets are stored at the provider’s Content Delivery Network (CDN), with your agent receiving only the reference URL. This design keeps memory usage consistently low regardless of the video’s length or complexity. The adaptive aspect-ratio support is another notable addition, automatically adjusting the video format (vertical, horizontal, or square) based on an intelligent analysis of the input images, providing greater flexibility and responsiveness to various display requirements.
Setting Up Plugin Manifests with Activation Descriptors
A significant advancement in OpenClaw v2026.4.11-beta.1 is the introduction of activation descriptors within plugin manifests. This feature streamlines the process of integrating plugins by allowing them to declare their activation and setup requirements directly in manifest.json. This eliminates the need for hardcoded core special cases for authorization flows, making plugin management more modular and transparent.
To illustrate, consider creating a plugin manifest for a hypothetical feishu-connector:
{
"name": "feishu-connector",
"version": "2.1.0",
"activation": {
"type": "oauth2",
"auth_url": "https://open.feishu.cn/open-apis/authen/v1/index",
"scopes": ["docs:document:read", "im:chat:read"]
},
"setup": {
"steps": [
{"field": "app_id", "type": "string", "required": true},
{"field": "app_secret", "type": "secret", "required": true}
]
}
}When you install a plugin using the new descriptor-aware flow, the OpenClaw CLI intelligently reads the manifest.json. It then automatically prompts you for any required credentials, such as app_id and app_secret in the Feishu example, before completing the activation process.
openclaw plugin install ./feishu-connector --activateThis process ensures that all necessary authentication details are securely handled and stored. If configured, credentials are saved in the Rust-based OneCLI vault, providing a robust and secure storage solution for sensitive information. This structured approach simplifies plugin integration, enhances security, and improves the overall developer experience within OpenClaw.
Optimizing Ollama Model Discovery
The beta release of OpenClaw introduces crucial optimizations for Ollama model discovery, significantly enhancing the user experience when working with local language models. One of the primary improvements is the caching of /api/show context-window and capability metadata during model discovery. This innovation eliminates redundant fetches when refreshing the model picker, leading to a much faster and more responsive interface.
You can configure Ollama caching within config/providers.yaml to tailor its behavior to your specific needs. This configuration allows you to set the cache’s time-to-live (TTL) and define invalidation strategies, ensuring that your agent always accesses up-to-date model information without unnecessary delays.
providers:
ollama:
base_url: "http://localhost:11434"
cache_ttl: 3600
cache_invalidation: "digest" # Invalidates when model digest changes
# Retry logic for empty responses
retry:
max_attempts: 3
backoff: "exponential"This caching mechanism prevents the UI from freezing or becoming sluggish, which can often occur when enumerating a large number of local models (e.g., 20+ models). The cache invalidates automatically whenever Ollama reports a changed model digest. This ensures that you consistently see the most current context window sizes and capability flags (such as vision, tools, or json_mode) for all your models. The added retry logic also improves resilience against transient network issues or temporary unavailability of the Ollama server, making your local LLM setup more robust.
Debugging OpenAI-Compatible Endpoints
When working with local or proxy OpenAI-compatible endpoints, OpenClaw v2026.4.11-beta.1 provides enhanced debugging capabilities to help diagnose routing and configuration issues. The framework now surfaces detailed classification metadata directly within embedded-agent debug logs, offering valuable insights into how your endpoints are being interpreted and utilized.
To leverage this feature, you need to enable debug logging with a sufficiently verbose level. This will allow you to capture the granular details necessary for effective troubleshooting.
openclaw agent run --debug --log-level=traceOnce debug logging is active, you can look for specific entries in the logs that provide endpoint classification details. These entries will clearly indicate the provider type, the routing mechanism being used, the capabilities detected for the endpoint (e.g., chat, embeddings), and the authentication method employed.
[DEBUG] Endpoint classification: provider=openai-compatible,
routing=local-proxy, capabilities=[chat, embeddings],
auth_method=bearer_tokenThis detailed information is instrumental in identifying common issues, such as when your local LLM is being mistakenly treated as a cloud provider, or when proxy routing is misconfigured. The logs also distinguish between application-auth paths (often used for integrations like Teams reactions) and delegated-auth paths, clearly showing which OAuth flow is active for each request. This level of transparency significantly simplifies the debugging process for complex LLM setups.
Integrating Feishu Document Comments
OpenClaw’s Feishu integration has been significantly enhanced to treat document comments as full-fledged chat conversations, enriching the agent’s ability to interact with and understand collaborative workflows. This integration now includes comprehensive rich context parsing, allowing your agent to grasp the nuances of discussions surrounding documents. Furthermore, it supports reaction functionality and provides typing feedback, making agent interactions within Feishu feel more natural and responsive.
To activate these advanced features, you need to configure the Feishu connector within your OpenClaw setup. This involves specifying your app_id and app_secret and enabling the desired features in your configuration file.
integrations:
feishu:
app_id: "${FEISHU_APP_ID}"
app_secret: "${FEISHU_APP_SECRET}"
features:
document_comments: true
comment_reactions: true
typing_indicators: trueWith this configuration, your agent will receive document comments as message threads, complete with the full document context attached. This context includes the specific text block that was commented on, as well as surrounding paragraphs, providing the agent with a comprehensive understanding of the discussion’s subject. The agent can then reply directly to these comments, and its responses will appear as threaded replies in Feishu, supporting proper reaction emojis for expressive feedback. The inclusion of typing feedback further enhances the user experience, indicating when the agent is actively processing complex document queries, making its presence more transparent and engaging.
Adding Microsoft Teams Reaction Support
The Microsoft Teams integration in OpenClaw has been significantly upgraded to include comprehensive reaction support, enhancing the agent’s ability to engage more dynamically within team communications. This feature is meticulously designed with delegated OAuth setup, which allows the agent to send reactions while maintaining robust application-auth for read paths. This dual authentication strategy ensures both security and flexibility in interactions.
To enable and configure these advanced reaction capabilities, you need to define the authentication method and specific policies within your OpenClaw configuration for Microsoft Teams. This setup ensures that the agent has the appropriate permissions to interact with message reactions.
integrations:
microsoft_teams:
auth_method: "delegated_oauth" # For reactions
graph_pagination: true
reaction_policy: "read_write"Once configured, your agent can seamlessly use the reaction API to interact with messages in Teams. For example, an agent can add a “like” reaction to a specific message, making its presence felt and providing immediate feedback.
await teams.addReaction({
messageId: msg.id,
reactionType: "like",
channelId: channel.id
});The integration also features robust Graph pagination support, which is critical for handling large channel histories without encountering rate limits. This ensures that the agent can process extensive message archives efficiently. While application-auth remains available for read-only monitoring scenarios, delegated auth specifically unlocks interactive features like emoji reactions to user messages, transforming the agent from a passive observer into an active, responsive participant in team discussions.
Securing External Embed URLs
Securing external embed URLs is a critical aspect of maintaining the integrity and safety of your OpenClaw environment, especially when dealing with AI agents that might generate content. It is essential to gate these URLs behind stringent configuration rules to prevent malicious agents from exfiltrating sensitive data through seemingly innocuous image requests or tracking pixels. This proactive security measure is fundamental to protecting your system from various forms of attack, including prompt injection.
To achieve this, you should implement Content Security Policy (CSP) headers and maintain a strict domain allowlist within your OpenClaw security configuration. This approach ensures that only trusted sources are permitted to embed content, significantly reducing the attack surface.
security:
embeds:
mode: "allowlist"
allowed_schemes: ["https"]
allowed_hosts: ["*.openclaw.io", "localhost:*"]
max_redirects: 0
content_security_policy: "default-src 'none'; img-src 'self' https:;"The [embed ...] tag, when used by your agent, will automatically validate any URLs against this meticulously defined security configuration before rendering the content. Any attempt to embed content from untrusted domains will immediately trigger a security exception, which will be prominently visible in the agent’s logs. This robust validation mechanism is specifically designed to thwart prompt injection attacks that aim to leak confidential conversation history by manipulating the agent into requesting malicious external resources or loading tracking images. By enforcing strict embed policies, OpenClaw helps ensure that your data remains secure and private.
Troubleshooting Common OpenClaw Issues
When working with a sophisticated framework like OpenClaw, encountering issues is a normal part of the development process. Here are some common problems you might face and their solutions, especially when migrating or setting up new features.
If you are migrating from v2026.3.x and encounter an error message indicating “nodesrun not found,” this is likely due to the architectural changes in the new version. The unified execution model in v2026.4.11-beta.1 removes the legacy nodesrun architecture. To resolve this, you need to update your agent’s configuration to use the new unified execution mode.
openclaw config set execution.mode=unified
openclaw doctor --fix-executionMemory-wiki synchronization failures often point to an issue with the PostgreSQL setup, specifically a missing pgvector extension. The pgvector extension is crucial for handling vector embeddings, which form the backbone of the memory-wiki system. You can verify its presence in your PostgreSQL database with a simple SQL query.
psql -d openclaw_memory -c "SELECT * FROM pg_extension WHERE extname='vector';"If ChatGPT imports are failing with JSON parse errors, it typically suggests that the export file format has changed or is corrupted. Ensure your conversations.json file is correctly encoded (usually UTF-8) and that its structure matches what OpenClaw expects. The --sanitize flag can help with some parsing issues, and the --validate-only option allows you to check the file without performing a full import.
file -i imports/conversations.json # Should be utf-8
openclaw import chatgpt --validate-only --file=imports/conversations.jsonFinally, it’s crucial to stay updated with OpenClaw releases for security patches. WebSocket hijacking vulnerabilities, for instance, were patched in v2026.3.11. Always verify your OpenClaw CLI version using openclaw --version and upgrade if you are running a version older than 2026.3.11 to ensure your system is secure against known exploits. Regular updates are key to maintaining a robust and secure AI agent environment.
Frequently Asked Questions
What is OpenClaw and how does it differ from other AI agent frameworks?
OpenClaw is an open-source framework that transforms LLMs into autonomous agents capable of persistent memory, tool use, and multi-step reasoning. Unlike AutoGPT or other alternatives, OpenClaw features native Dreaming/memory-wiki capabilities for long-term context retention, structured plugin manifests with activation descriptors, and a unified execution model that eliminates the legacy nodesrun architecture. It supports both cloud and local LLM deployments through Ollama integration, with built-in security features like ClawShield for production deployments.
How does the ChatGPT import ingestion feature handle data privacy?
The ChatGPT import feature processes your conversations.json export locally before storage. Data never hits external APIs during ingestion unless explicitly configured. The framework shards imported insights across your local PostgreSQL vector store or encrypted SQLite depending on your deployment. You can configure automatic PII redaction via the memory.sanitize_imports config flag. For enterprise deployments, the Memory Palace diary supports role-based access control, ensuring imported conversations are only visible to authorized agent personas.
Can I run OpenClaw entirely with local LLMs without cloud dependencies?
Yes. OpenClaw v2026.4.11-beta.1 includes enhanced Ollama integration with cached /api/show metadata for faster model discovery. You can configure provider: ollama in your agent.yaml and point to local endpoints. The Dreaming/memory-wiki system works with local embedding models like nomic-embed-text. Video generation tools support URL-only asset delivery to avoid memory bloat with local providers. The only requirement is initial npm install; all runtime inference can stay on your machine.
What hardware is required for the Dreaming/memory-wiki features?
Memory-wiki requires PostgreSQL 14+ with pgvector extension for production use, or SQLite with vec0 for development. Minimum 8GB RAM for the vector store and agent runtime combined. For the ChatGPT import feature, plan 2-3x your export file size in database storage due to vector indexing. The Memory Palace UI runs in the Control interface and requires no additional resources beyond standard OpenClaw deployment. GPU acceleration helps for embedding generation but is not mandatory.
How do I migrate existing agents from v2026.3.x to v2026.4.11-beta.1?
First, backup your state using openclaw backup --archive which creates a local state archive. Update your CLI with npm install -g @openclaw/cli@beta. The unified execution model in v2026.4.11-beta.1 removes nodesrun, so update your agent configs to use the new execution.mode: unified setting. Migrate plugin manifests to include activation descriptors if you have custom plugins. Run openclaw doctor to verify ChatGPT import tables and Memory Palace schema migrations completed successfully.