# OpenClaw Knowledge Base

## Armorer Hints (Machine Readable)
```json
{
  "env_defaults": {
    "OPENCLAW_CONFIG_DIR": "./.openclaw",
    "OPENCLAW_WORKSPACE_DIR": "./workspace"
  },
  "local_images": [
    "openclaw:local"
  ],
  "create_files": [
    {
      "path": "${OPENCLAW_CONFIG_DIR}/openclaw.json",
      "content": {
        "gateway": {
          "mode": "local"
        }
      }
    }
  ]
}
```

## What is OpenClaw?
OpenClaw is a self-hosted, personal AI agent platform. It is designed to be a private alternative to centralized AI services, allowing users to run powerful agents locally or on their own servers. It typically includes a web-based dashboard, a gateway for secure communication, and a CLI for management.

## Architecture
OpenClaw deployment usually consists of two main components:
1.  **OpenClaw Gateway**: The central hub that manages agent sessions, authentication, and communication between the UI and the agents.
2.  **OpenClaw CLI/App**: The interactive component where the agent logic resides and where users can trigger onboarding or specific tasks.

## Security Risks & Considerations
Deploying OpenClaw (and similar personal AI agents) involves significant security surface areas:

### 1. Remote Code Execution (RCE)
By design, AI agents often have the ability to execute code, run shell commands, or interact with the local filesystem. If the OpenClaw dashboard or gateway is exposed to the internet without proper protection, an attacker could potentially hijack the agent to run malicious commands on the host system.
- **Mitigation**: Always run OpenClaw in a strictly scoped Docker container. Use Armorer's network policies to restrict outbound access.

### 2. Secret Exposure
OpenClaw requires various API keys (e.g., Anthropic, OpenAI) and session tokens (e.g., `CLAUDE_AI_SESSION_KEY`) to function. These are often stored in `.env` files.
- **Mitigation**: Use Armorer's Vault to manage these secrets securely. Monitor `.env` and log files for accidental leakage of these tokens.

### 3. Gateway Token Authentication
The `OPENCLAW_GATEWAY_TOKEN` is critical for securing the connection between the Web UI and the Gateway. If this token is missing or weak, unauthorized users may be able to access your AI sessions.
- **Mitigation**: Ensure a strong, unique token is set in the `.env` file and used in the tokenized dashboard URL.

## Deployment Best Practices

### Docker Configuration
- **Recommended Image**: `alpine/openclaw:latest`
- **Stable docker-compose.yml**:
  ```yaml
  services:
    openclaw:
      image: alpine/openclaw:latest
      ports:
        - "8080:8080"
      volumes:
        - ./data:/home/node/.openclaw
      restart: unless-stopped

    openclaw-cli:
      image: alpine/openclaw:latest
      entrypoint: ["openclaw"]
      volumes:
        - ./data:/home/node/.openclaw
      profiles: ["cli"]
  ```
- **CLI Entrypoint**: You MUST use `entrypoint: ["openclaw"]`. Without this, Docker will try to use `node` to run your commands, which will fail with a "MODULE_NOT_FOUND" error.
- **Volumes**: Always use relative paths (e.g., `./data`) to avoid "empty section" spec errors.

### Common Issues
1. **Invalid Spec (Empty Section between colons)**: This happens when you use an environment variable in a volume mapping that isn't set. 
   - *Fix*: Use literal relative paths like `./openclaw_data`.
2. **Permission Denied**: The container needs to write to the volume.
   - *Fix*: Armorer will automatically pre-create these directories.
3. **Gateway Port Collision (`18789` / `18790` already allocated)**: Happens when another OpenClaw stack is already running on default ports.
   - *Fix*: Stop the conflicting instance first (`armorer stop <alias>`), then deploy again.

## How Armorer Helps
Armorer provides several specialized features to make OpenClaw deployments more secure and manageable:

### 1. Chat-Owned Setup Flow
Armorer can now drive OpenClaw installation and first-run setup directly from chat/TUI without sending the operator into OpenClaw-native configure/onboard flows. The managed flow collects provider, model, API keys, Telegram/channel settings, optional Armory skills, and skill scan paths, then verifies both the Telegram bot/chat configuration and the final instance with `armorer run openclaw status`. This applies to both the Textual TUI and the classic `armorer chat` fallback path.

Concrete runtime sync points:
- Provider/model are written into OpenClaw-native config (`.openclaw/openclaw.json`) so the final instance has an explicit `agents.defaults.model.primary`.
- Provider auth is synchronized into install-local env files (`.env` and `.openclaw/.env`) instead of relying only on Armorer's own vault/config state.
- Gemini provider choices must be translated to OpenClaw's `google/...` model namespace when building the final model reference.
- OpenClaw-native skill directories are written into `skills.load.extraDirs`, while optional Armory skills are injected into `mcpServers`.
- Provider/model prefixes must stay consistent with the selected provider; mismatches should be rejected during setup and final verification instead of being normalized away silently.
- Safe retries can reuse existing OpenClaw runtime state from the install root `.env`, `.openclaw/.env`, and `.openclaw/openclaw.json` when Armorer-side mirrors are absent.
- If the target OpenClaw alias is already registered, the managed setup flow should reuse that existing install for reconfiguration/retry instead of attempting a second install on the same alias.
- Retry prompts also support explicit `clear` operations for optional Telegram allowlists, alert chat targets, injected Armory skills, and extra skill directories, so stale runtime settings can be removed without dropping into manual cleanup.
- When Telegram is configured, Armorer verifies the bot token with the Telegram API and verifies configured channel-style chat IDs with `getChat` instead of only re-reading stored config values.
- OpenClaw-native skill directories should be treated as part of final runtime verification: persisted `skills.load.extraDirs` values are not enough if the directories no longer exist on disk.
- If the registered runtime advertises a health-check shortcut, final verification should run `armorer run openclaw doctor` after `status` to catch provider auth or model endpoint failures that a shallow status check can miss.
- Pending setup prompts can also be cancelled in-flow: Textual accepts `/cancel`, classic fallback select prompts expose a visible cancel choice, Telegram select/confirm prompts expose inline controls, Telegram and Signal high-risk confirmations accept plain `confirm` / `cancel`, and `/confirm <token>` remains available for explicit approval.
- Fresh installs should fail fast when provider/model/auth prerequisites are still missing; the managed flow must not report success with an unusable OpenClaw runtime.

### 2. Path & Volume Translation
OpenClaw often requires complex volume mounts for configuration and workspaces. Armorer automatically handles the translation between your host paths and the Docker container's internal paths, preventing mounting errors.

### 3. Real-time Security Monitoring
Armorer's Core service watches OpenClaw's configuration and session files. If a secret is accidentally written to a log file or a configuration is weakened, Armorer will alert you and offer to redact the sensitive information.

### 4. Agentic Troubleshooting
If OpenClaw fails to start (e.g., due to an incompatible Docker image or a missing environment variable), Armorer uses its internal Expert Debugger to analyze the logs and apply fixes to the `docker-compose.yml` automatically.

### 5. Queue Safety
If a chat-driven OpenClaw install stalls or is retried, Armorer reports the last visible setup step, cleans or supersedes stale queue/status files, and makes that cleanup visible in chat/TUI rather than leaving the operator blocked indefinitely.
