What You'll Learn

This tutorial walks you through setting up Gandalf, OpenClaw's team member AI agent, from initial configuration through production deployment. You'll learn how to architect an intelligent agent system, integrate it with your development workflow, configure knowledge bases, and troubleshoot common integration challenges.

Introduction: Building Your AI Team Member

Gandalf represents a paradigm shift in how development teams augment their capacity—moving beyond simple chatbots to purpose-built AI agents that understand your codebase, team processes, and project context. The Lerian Studio team engineered Gandalf as a practical solution to autonomous task execution within development environments, not as theoretical research.

This setup guide is based on the implementation process documented by Lerian Studio, adapted for teams starting from zero. Whether you're building a single-domain agent or a multi-agent system, the architectural principles and configuration patterns remain consistent.

Prerequisites

• Development environment: Linux, macOS, or Windows with Docker installed (version 20.10+)
• Programming knowledge: Familiarity with Python 3.9+ and REST APIs; experience with LLM frameworks helpful but not required
• Infrastructure access: Cloud environment (AWS, GCP, or Azure) or local compute with minimum 4GB RAM, 10GB disk space
• AI foundation: Understanding of LLM concepts (tokenization, embeddings, context windows) at conceptual level
• Team coordination: Access to your team's codebase, documentation repositories, and decision-making processes you want to automate
• Required packages: pip, git, curl/Postman for API testing

Learning Objectives

• Design and configure a specialized AI agent tailored to your team's workflow
• Integrate Gandalf with your codebase, documentation, and communication tools
• Implement prompt engineering and context injection for domain-specific tasks
• Deploy the agent in containerized environments with proper monitoring and logging
• Troubleshoot agent hallucinations, context limitations, and integration failures
• Scale from single-task automation to multi-agent coordination

Step 1: Architecture Planning and Requirements Gathering

Before deploying Gandalf, define exactly what you need your AI agent to accomplish. Vague goals like "help with development" create ambiguous agents that perform poorly across multiple domains. Instead, decompose your needs into discrete, measurable capabilities.

Define Agent Responsibilities

Create a responsibility matrix for your Gandalf instance. Ask: What tasks is this agent exclusively responsible for? What information does it need access to? What decisions should it never make autonomously?

Example matrix from Lerian Studio's implementation:

• Responsibility: Code review assistance → Autonomy level: Suggestion only (no auto-commit)
• Responsibility: Documentation generation → Autonomy level: Draft creation (requires human approval)
• Responsibility: Issue triage and categorization → Autonomy level: Automatic for clear-cut cases
• Responsibility: Production deployment decisions → Autonomy level: No autonomy (alerts only)

This prevents scope creep and dangerous autonomous behaviors. Each responsibility should map to a specific workflow in your team's existing process.

Identify Required Knowledge Sources

Gandalf operates only on information you provide. Identify your knowledge architecture:

• Codebase: Which repositories, branches, or directories? (Entire monorepo or specific services?)
• Documentation: Team wikis, README files, API documentation, architectural decision records (ADRs)
• Team context: Communication patterns, naming conventions, tool preferences, deployment procedures
• Real-time data: Current deployments, CI/CD pipeline status, incident channels

Knowledge gaps directly cause agent failures. If your agent doesn't know your team names your microservices by animal type, it can't write coherent suggestions.

Step 2: Environment Setup and Base Installation

Set up your Gandalf runtime environment with proper isolation and monitoring from the start.

Create Isolated Python Environment

Use virtual environments to avoid dependency conflicts with your existing development setup:

python3 -m venv gandalf-env
source gandalf-env/bin/activate  # On Windows: gandalf-env\Scripts\activate

Create a requirements.txt file with core dependencies. The Lerian Studio implementation uses these base packages:

langchain==0.1.0
openai==1.0.0
pydantic==2.0.0
fastapi==0.104.0
uvicorn==0.24.0
python-dotenv==1.0.0
redis==5.0.0
pytest==7.4.0

Install the dependencies:

pip install -r requirements.txt

Configure Environment Variables

Never hardcode API keys or configuration. Create a .env file in your project root (add to .gitignore immediately):

OPENAI_API_KEY=sk-your-key-here
GANDALF_ENVIRONMENT=development
CODEBASE_PATH=/path/to/your/repo
DOC_INDEX_URL=https://your-docs-server
SLACK_BOT_TOKEN=xoxb-your-token
LOG_LEVEL=INFO

Load these in your application using python-dotenv. This separation of configuration from code is non-negotiable for security.

Step 3: Building Your Knowledge Base

The quality of your knowledge base directly determines agent performance. This is where most implementations fail—treating knowledge engineering as an afterthought.

Ingest and Structure Your Codebase

Create a code embeddings index so Gandalf understands your architecture:

from langchain.document_loaders import DirectoryLoader
from langchain.text_splitter import Language, RecursiveCharacterTextSplitter
from langchain.embeddings.openai import OpenAIEmbeddings
from langchain.vectorstores import Redis

Load all Python files from your repository
loader = DirectoryLoader(
    path="./your-repo",
    glob="**/*.py",
    loader_cls=TextLoader
)
documents = loader.load()
Split code into manageable chunks (important: preserve context)
splitter = RecursiveCharacterTextSplitter(
    language=Language.PYTHON,
    chunk_size=1000,
    chunk_overlap=200  # Overlap prevents breaking class/function definitions
)
split_docs = splitter.split_documents(documents)
Create embeddings and store in vector database
embeddings = OpenAIEmbeddings()
vector_store = Redis.from_documents(
    split_docs,
    embeddings,
    redis_url="redis://localhost:6379"
)

The chunk_overlap parameter is crucial—it prevents your agent from losing context when retrieving related code sections.

Index Documentation and Architecture Decisions

Add human-readable documentation to the same vector store:

doc_loader = DirectoryLoader(
    path="./docs",
    glob="**/*.md"
)
doc_documents = doc_loader.load()

Add metadata to track document source and version
for doc in doc_documents:
    doc.metadata["source_type"] = "documentation"
    doc.metadata["retrieval_priority"] = "high"
split_docs = splitter.split_documents(doc_documents)
vector_store.add_documents(split_docs)

Metadata enables filtering—your agent can prioritize recent ADRs over outdated blog posts.

Create Context Injection Rules

Not all knowledge is equally useful at query time. Create rules for context injection:

CONTEXT_RULES = 

This prevents token overflow and ensures the agent retrieves contextually appropriate information for each task type.

Step 4: Configuring the Agent Personality and Behavior

Gandalf needs explicit instructions about how to operate within your team's culture and constraints. This isn't decoration—it's critical infrastructure.

Write System Prompts

Create system prompts that define your agent's role, constraints, and communication style:

GANDALF_SYSTEM_PROMPT = """
You are Gandalf, an AI team member for the Lerian Studio engineering team.

YOUR ROLE:

Assist with code review, focusing on security, performance, and architectural consistency
Generate and refine documentation based on code and team decisions
Triage incoming issues and suggest categorization
Explain complex architectural decisions to new team members

CRITICAL CONSTRAINTS:

NEVER make autonomous production deployments
NEVER delete code or documentation without explicit human confirmation
NEVER suggest breaking changes without analyzing downstream impact
Always cite your sources when referencing code or documentation
Admit uncertainty: if you're unsure about team conventions, ask clarifying questions

COMMUNICATION STYLE:

Professional but personable (we use first names, casual technical language)
Concise (3-4 sentences max per response unless detailed explanation requested)
Evidence-based (back recommendations with specific code references)

WHEN UNCERTAIN:

Recommend human review of your suggestions
Provide reasoning for your recommendations
Suggest additional context that would improve your confidence
"""

These constraints prevent the agent from behaving recklessly. The Lerian Studio team found that explicit "NEVER" rules reduced risky autonomous actions by 94% in early testing.

Define Response Schemas

Use Pydantic to structure agent responses consistently:

from pydantic import BaseModel, Field
from typing import Optional, List

class CodeReviewResponse(BaseModel):
    severity: str = Field(..., description="critical|high|medium|low|info")
    category: str = Field(..., description="performance|security|style|architecture")
    code_location: str = Field(..., description="file path and line number")
    suggestion: str = Field(..., description="specific improvement recommendation")
    confidence: float = Field(..., ge=0, le=1, description="0.0 to 1.0")
    requires_human_review: bool = Field(
        ...,
        description="True if suggestion affects critical paths"
    )
    related_code_sections: List[str] = Field(
        default_factory=list,
        description="Other files affected by this change"
    )
class ReviewBatch(BaseModel):
    findings: List[CodeReviewResponse]
    summary: str
    estimated_review_time: str

Structured responses enable downstream automation—you can filter findings by severity, route high-confidence suggestions automatically, and integrate with CI/CD pipelines.

Step 5: Integration with Development Workflows

Gandalf's value multiplies when integrated into your existing workflow, not as a separate tool.

Connect to CI/CD Pipelines

Create a GitHub Actions or GitLab CI job that triggers Gandalf on pull requests:

name: Gandalf Code Review
on:
  pull_request:
    paths:
      - '**.py'
      - '**.js'
      - '**.ts'
jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Invoke Gandalf Review
        run: |
          curl -X POST http://gandalf-api:8000/review \
            -H "Content-Type: application/json" \
            -d '{"pr_number": ${{ github.event.pull_request.number }}, "repo": "${{ github.repository }}"}'
      - name: Comment Results
        run: |
          # Parse Gandalf response and post to PR
          python scripts/post_review.py

This puts Gandalf's suggestions directly where developers see them—reducing friction compared to running separate tools.

Slack Integration for Team Notifications

Route important agent insights to team channels:

from slack_sdk import WebClient
from slack_sdk.errors import SlackApiError

def notify_team(message: str, channel: str, severity: str = "info"):
    client = WebClient(token=os.getenv("SLACK_BOT_TOKEN"))
    emoji = {"critical": "🚨", "high": "⚠️", "medium": "📌", "info": "ℹ️"}
try:
    response = client.chat_postMessage(
        channel=channel,
        text=f"{emoji.get(severity, '')} {message}",
        thread_ts=None  # Set to parent message ID to reply in thread
    )
except SlackApiError as e:
    logger.error(f"Slack notification failed: {e.response['error']}")</code></pre>

Team members should see Gandalf as a helpful peer who surfaces insights in their normal workflow, not as an intrusive external service.

Step 6: Deploying Gandalf
Containerize your agent for reproducible, scalable deployment.

Create Dockerfile
FROM python:3.11-slim

WORKDIR /app
Install system dependencies
RUN apt-get update && apt-get install -y 
    git curl 
    && rm -rf /var/lib/apt/lists/*
Copy requirements first (enables Docker layer caching)
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
Copy application code
COPY . .
Create non-root user for security
RUN useradd -m gandalf && chown -R gandalf:gandalf /app
USER gandalf
EXPOSE 8000
CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000"]

Docker Compose for Local Development
version: '3.8'
services:
  gandalf:
    build: .
    ports:
      - "8000:8000"
    environment:
      - OPENAI_API_KEY=${OPENAI_API_KEY}
      - GANDALF_ENVIRONMENT=development
      - REDIS_URL=redis://redis:6379
    depends_on:
      - redis
    volumes:
      - ./:/app  # Hot reload for development

  redis:
    image: redis:7-alpine
    ports:
      - "6379:6379"
    volumes:
      - redis_data:/data
volumes:
  redis_data:

Start the full stack locally:
docker-compose up --build

Production Deployment Considerations
For production, use managed container services (AWS ECS, Google Cloud Run, or Kubernetes):

Resource limits: Cap memory and CPU to prevent runaway costs. Typical baseline: 1GB RAM, 0.5 CPU cores per agent instance
Auto-scaling: Configure horizontal scaling based on request latency (target: <2 second response time)
API rate limits: Implement token bucket rate limiting to prevent hitting OpenAI quota
Request timeouts: Set 30-second timeouts per request. Complex analysis queries need optional async processing
Logging and tracing: Send all requests to centralized logging (CloudWatch, Datadog, or self-hosted ELK)
Health checks: Implement /health endpoint that verifies Redis connectivity, API key validity, and knowledge base accessibility


Step 7: Testing and Validation
Don't deploy to production without rigorous testing. Agent systems have failure modes traditional code doesn't.

Create Test Cases for Agent Behavior
import pytest
from gandalf.agent import CodeReviewAgent

@pytest.fixture
def agent():
    return CodeReviewAgent()
def test_rejects_risky_suggestions(agent):
    """Ensure agent refuses to suggest breaking changes without verification"""
    code_sample = "def init(self, arg1, arg2, arg3): ..."
    response = agent.review(code_sample)
if "remove arg3" in response.suggestion.lower():
    assert response.requires_human_review == True
    assert response.confidence < 0.9

def test_cites_sources(agent):
    """Verify agent backs up recommendations with code references"""
    response = agent.review("any code sample")
    assert len(response.related_code_sections) > 0
for section in response.related_code_sections:
    assert section.startswith("path/to/file")  # Validate format

def test_context_window_respected(agent):
    """Ensure responses fit within expected token limits"""
    response = agent.review("large code file")
    token_count = count_tokens(response.suggestion)
    assert token_count < 2000

Benchmarking Against Known Issues
Create a corpus of real issues from your codebase and measure detection accuracy:
def test_detection_accuracy():
    """Benchmark against real past security issues"""
    test_cases = [
        {"code": sql_injection_example, "expected": "security"},
        {"code": n_plus_one_example, "expected": "performance"},
        {"code": style_violation, "expected": "style"},
    ]
    
correct = 0
for case in test_cases:
    response = agent.review(case["code"])
    if response.category == case["expected"]:
        correct += 1

accuracy = correct / len(test_cases)
assert accuracy > 0.85  # Expect 85%+ accuracy before production</code></pre>

Troubleshooting Common Issues

Agent Hallucinations and False Positives
Problem: Gandalf suggests code changes that don't exist or makes incorrect recommendations.
Root cause: Insufficient context, conflicting information in knowledge base, or prompt that doesn't enforce citation requirements.
Solution:

Reduce context window size—LLMs perform worse with too much information
Add "cite your source" requirement to all responses
Implement confidence scoring; only present suggestions above 0.8 confidence
Add test cases for common hallucination patterns your team observes


High Latency and Token Costs
Problem: API calls take 10+ seconds or monthly costs exceed budget.
Root cause: Overly large context windows, unnecessary API calls, or inefficient chunking strategy.
Solution:

Implement request caching—identical questions should hit Redis cache (TTL: 24 hours)
Use smaller, task-specific models (GPT-3.5 instead of GPT-4 for simple tasks)
Pre-compute responses for common queries (FAQ mode)
Implement async processing for non-urgent tasks


Agent Fails to Access Knowledge Base
Problem: "No relevant documents found" even though information exists.
Root cause: Vector store not initialized, poor query expansion, or semantic similarity threshold too high.
Solution:
# Check vector store health
def verify_knowledge_base():
    query = "sample query from your domain"
    results = vector_store.similarity_search(query, k=5)
    
if len(results) == 0:
    raise ValueError("Vector store not populated or inaccessible")

# Verify metadata is attached
for result in results:
    assert "source" in result.metadata
    print(f"Found: {result.metadata['source']} (similarity: {result.similarity})")</code></pre>

Memory Leaks or OOM Errors
Problem: Container crashes after running for hours.
Root cause: Unbounded conversation history, cached embeddings not cleared, or recursive function calls.
Solution:

Implement conversation session timeout (15 minutes)
Clear Redis cache periodically (cron job every 6 hours)
Monitor memory usage with Prometheus/Grafana
Add max iteration limits to agent loops


Best Practices

Start Narrow, Expand Carefully
Launch Gandalf with one specific responsibility (e.g., code review only). Add capabilities only after the core system is stable and trusted. Lerian Studio spent 4 weeks on code review before adding documentation generation—this wasn't wasted time, it was foundational.

Human Review Gates Are Not Optional
Require human approval for any action that affects production, security, or team communication. "Supervised autonomy" isn't a limitation—it's the entire point. The goal is to amplify human judgment, not replace it.

Document Decision Rationale
When Gandalf makes a suggestion, include reasoning: "I recommend this because [specific evidence from your codebase]." This builds trust and helps your team learn.

Monitor Accuracy Metrics
Track how often team members accept vs. reject Gandalf's suggestions. Acceptance rate below 60% means your system needs retraining.

Version Control Your Prompts
Treat system prompts and context rules like code—version them, test changes before deployment, maintain a changelog. A small prompt modification can dramatically change behavior.

Implement Feedback Loops
When developers reject suggestions, log the reason. Feed this data back into retraining batches. After 100 rejections for a particular error category, investigate and fix the root cause.

Next Steps
After successful deployment:

Week 1-2: Iterate on prompt engineering based on team feedback
Week 3-4: Add second capability (documentation or issue triage)
Month 2: Evaluate ROI—measure time saved, bugs prevented, and cycle time improvements
Month 3+: Consider multi-agent system if single agent reaches saturation (separate agents for code, docs, DevOps)
Ongoing: Build fine-tuned models on your proprietary data for better accuracy and lower costs


Summary
Gandalf represents a practical approach to AI-augmented development teams. Success requires three things: (1) clear responsibility boundaries that prevent reckless autonomy, (2) comprehensive knowledge engineering that gives the agent meaningful context, and (3) human oversight gates that preserve team trust.
The Lerian Studio implementation demonstrates that specialized agents outperform general-purpose models by 3-5x on domain-specific tasks. Your investment in knowledge base construction and prompt engineering pays dividends across the lifetime of your system.
Start with code review, validate the system, then expand methodically. Gandalf should feel like a helpful team member who asks good questions and catches edge cases—not a black box that makes mysterious suggestions.



Attribution: This tutorial is adapted from the Lerian Studio implementation guide, originally documented in Portuguese. Source: Gandalf AI Team Member setup presentation, Lerian Studio YouTube channel (501 views, 63 likes).