OpenClaw Document Writer Agent¶

An autonomous AI-powered documentation agent that clones Git repositories, analyzes code, generates comprehensive documentation, and commits changes back to the repository. Built with OpenClaw, this agent demonstrates advanced autonomous task execution.

What It Does¶

The Document Writer Agent:

• Clones Git repositories (public or private with credentials)
• Analyzes code structure, dependencies, and patterns
• Generates comprehensive documentation using LLM
• Creates or updates README, API docs, tutorials, and changelogs
• Commits and pushes changes back to the repository
• Streams progress updates to the user

Installation¶

1. Prerequisites¶

Install required components:

./cli ai-agent openclaw install      # OpenClaw bridge server
./cli ai-gateway litellm install     # LiteLLM for model access
./cli gui-app openwebui install      # Open WebUI for interaction

2. Configure Environment Variables¶

Add to .env.local (via ./cli configure):

# Required
LITELLM_API_KEY=sk-1234567890abcdef

# Optional: Git credentials for pushing changes
OPENCLAW_DOC_WRITER_GIT_USERNAME=your-github-username
OPENCLAW_DOC_WRITER_GIT_TOKEN=ghp_your_github_token

# Optional: Observability
LANGFUSE_PUBLIC_KEY=pk-lf-xxx
LANGFUSE_SECRET_KEY=sk-lf-xxx

3. Install Agent¶

./cli openclaw doc-writer install

This will:

1. Deploy the agent as a Kubernetes Deployment
2. Create a Service at http://doc-writer.openclaw:8080
3. Automatically register the pipe function in Open WebUI

Verification¶

Check the deployment:

# Check pods
kubectl get pods -n openclaw -l app=doc-writer

# Check service
kubectl get svc -n openclaw doc-writer

# Check logs
kubectl logs -n openclaw -l app=doc-writer

# Test health endpoint
kubectl port-forward -n openclaw svc/doc-writer 8080:8080
curl http://localhost:8080/health

How It Works¶

Agent Workflow¶

graph LR
    A[User Request] --> B[Clone Repo]
    B --> C[Analyze Code]
    C --> D[Generate Docs]
    D --> E[Commit Changes]
    E --> F[Push to GitHub]
    F --> G[Stream Response]

1. Clone: Downloads the repository using Git credentials
2. Analyze: Reads code files, understands project structure
3. Generate: Uses LLM to create comprehensive documentation
4. Commit: Stages and commits changes with descriptive message
5. Push: Pushes changes to the remote repository
6. Stream: Sends progress updates and final result to user

Git Configuration¶

The agent is pre-configured with:

git config --system user.name "OpenClaw Doc Writer"
git config --system user.email "openclaw-doc-writer@noreply"

Open WebUI Integration¶

The pipe function is automatically registered during installation.

Using the Agent¶

1. Open Open WebUI
2. Start a new chat
3. Select OpenClaw - Document Writer from the model dropdown
4. Send documentation requests:

Example 1: Generate README

Write a comprehensive README for https://github.com/myorg/myproject

Include:
- Project overview
- Installation instructions
- Usage examples
- API documentation
- Contributing guidelines

Example 2: Update API Docs

Update the API documentation in https://github.com/myorg/api-server

Document all REST endpoints with:
- Request/response formats
- Authentication requirements
- Error codes
- Rate limiting

Example 3: Create Changelog

Generate a CHANGELOG.md for https://github.com/myorg/project

Based on recent commits, document:
- New features
- Bug fixes
- Breaking changes
- Deprecations

Configuration¶

Environment Variables¶

config.json¶

{
  "examples": {
    "openclaw": {
      "doc-writer": {
        "env": {
          "LITELLM_MODEL_NAME": "bedrock/claude-4.5-sonnet",
          "OPENCLAW_GATEWAY_TOKEN": "openclaw-gateway-token"
        }
      }
    }
  }
}

Example Tasks¶

Git Credentials (Optional)¶

The agent can push changes back to repositories with proper credentials.

Creating a Scoped GitHub Token¶

Use a fine-grained personal access token:

1. Go to GitHub Settings → Developer settings → Personal access tokens → Fine-grained tokens
2. Click Generate new token
3. Configure:
4. Token name: openclaw-doc-writer
5. Expiration: 30 days (or shorter)
6. Repository access: Only select repositories - pick specific repos
7. Permissions: Set Contents to Read and write - leave everything else at No access
8. Generate token and add to .env.local:

OPENCLAW_DOC_WRITER_GIT_USERNAME=your-github-username
OPENCLAW_DOC_WRITER_GIT_TOKEN=ghp_your_fine_grained_token

Recommendations¶

• ❌ Never use classic tokens - they grant access to all repos
• ✅ Set short expiration - rotate tokens frequently
• ✅ Limit to specific repos - never grant org-wide access
• ✅ Review agent output - check commits before merging
• ✅ Use branch protection - require reviews for main branches
• ✅ For production, consider AWS Secrets Manager instead of env vars

Without Credentials¶

The agent can still operate without credentials:

• ✅ Clone public repositories
• ✅ Analyze code and generate documentation
• ❌ Cannot commit and push changes
• Agent will provide documentation as text response instead

Langfuse Observability¶

If Langfuse is installed, view agent execution traces:

1. Open Langfuse UI
2. Navigate to Traces
3. Filter by doc-writer tag
4. View detailed metrics:
5. Task submission time
6. Git operations (clone, commit, push)
7. LLM API calls with prompts and responses
8. Token usage and costs
9. Response latency
10. Error events

Cost Optimization¶

• Spot instances: Karpenter provisions Spot ARM64 nodes (up to 90% savings)
• Model selection: Use smaller models for simpler docs
• Job-based execution: Consider using Jobs instead of Deployment for one-off tasks
• Prompt optimization: Be specific to reduce unnecessary LLM calls

Troubleshooting¶

Agent cannot clone private repos¶

Problem: fatal: could not read Username

Solution: Configure Git credentials in .env.local

Agent cannot push changes¶

Problem: remote: Permission denied

Solution: Ensure GitHub token has Contents: Read and write permission

Documentation quality is poor¶

Problem: Generated docs lack detail

Solution: - Be specific in prompts about what to include - Use a more capable model (e.g., Claude 3.5 Sonnet) - Provide example documentation style

Uninstallation¶

Remove the Document Writer Agent:

./cli openclaw doc-writer uninstall

This will delete Kubernetes resources (Deployment, Service, ServiceAccount) and the Open WebUI pipe function.

References¶

• OpenClaw Repository
• Open WebUI Pipe Functions
• GitHub Personal Access Tokens
• Git Credential Storage