This document covers all configuration options for OpenAkita.

OpenAkita is configured primarily through environment variables, typically stored in a .env file.

Each agent's display name is owned by the AgentProfile record managed from the desktop "Agents" menu, not by an env variable.

8 built-in presets with distinct communication styles. Users can also switch persona via chat commands. Persona preferences are learned from conversations (LLM-driven trait mining) and promoted to identity files during daily consolidation.

When enabled, the agent proactively sends greetings, task follow-ups, and memory-based reminders. Frequency adapts based on user feedback (fast reply = keep frequency, ignored = reduce).

Integrates with ChineseBQB (5700+ stickers). Each persona preset has a different sticker strategy (e.g., business=never, girlfriend=frequent).

Note: Persona, proactive, and sticker settings can also be changed at runtime via chat commands. Runtime changes are persisted to data/runtime_state.json and survive agent restarts.

TELEGRAM_ENABLED=true
TELEGRAM_BOT_TOKEN=your-bot-token

To get a bot token:

1. Message @BotFather on Telegram
2. Use /newbot command
3. Follow the prompts
4. Copy the token

DINGTALK_ENABLED=true
DINGTALK_CLIENT_ID=your-client-id
DINGTALK_CLIENT_SECRET=your-client-secret

FEISHU_ENABLED=true
FEISHU_APP_ID=your-app-id
FEISHU_APP_SECRET=your-app-secret

WEWORK_ENABLED=true
WEWORK_CORP_ID=your-corp-id
WEWORK_AGENT_ID=your-agent-id
WEWORK_SECRET=your-secret

QQBOT_ENABLED=true
QQBOT_APP_ID=your-app-id
QQBOT_APP_SECRET=your-app-secret
QQBOT_SANDBOX=false

ONEBOT_ENABLED=true
ONEBOT_WS_URL=ws://127.0.0.1:8080
ONEBOT_ACCESS_TOKEN=              # 可选

You can also use a YAML configuration file at config/agent.yaml:

# Agent settings
agent:
  name: OpenAkita
  max_iterations: 100
  auto_confirm: false

# Model settings
model:
  provider: anthropic
  name: claude-sonnet-4-20250514
  max_tokens: 8192

# Tools configuration
tools:
  shell:
    enabled: true
    timeout: 30
    blocked_commands:
      - rm -rf /
      - format
  file:
    enabled: true
    allowed_paths:
      - ./
      - /tmp
  web:
    enabled: true
    timeout: 30

# Logging
logging:
  level: INFO
  format: "%(asctime)s - %(name)s - %(levelname)s - %(message)s"
  file: logs/agent.log

The soul document defines core values. Generally should not be modified:

# Soul Overview

OpenAkita is a self-evolving AI assistant...

## Core Values
1. Safety and human oversight
2. Ethical behavior
3. Following guidelines
4. Being genuinely helpful

Behavioral specifications and workflows:

# Agent Behavior Specification

## Working Mode
- Ralph Wiggum Mode (never give up)
- Task execution flow
- Validation requirements

User-specific preferences (auto-updated):

# User Profile

## Preferences
- Language: English
- Technical level: Advanced
- Preferred tools: Python, Git

Working memory (auto-managed):

# Working Memory

## Current Task
- Description: ...
- Progress: 50%
- Next steps: ...

## Lessons Learned
- Issue X was solved by Y

# Override config file
openakita --config /path/to/config.yaml

# Override log level
openakita --log-level DEBUG

# Override model
openakita --model claude-opus-4-0-20250514

# Disable confirmation prompts
openakita --auto-confirm

# Run in specific mode
openakita --mode chat|task|test

OpenAkita's security policy lives in identity/POLICIES.yaml. Most fields have safe defaults; only override what your deployment needs.

Watch POLICIES.yaml for edits and rebuild the policy engine in-place without restarting OpenAkita:

# identity/POLICIES.yaml
security:
  hot_reload:
    enabled: true              # default: false (opt-in)
    poll_interval_seconds: 5.0 # 0.5 .. 3600
    debounce_seconds: 0.5      # avoid reading half-written editor saves

Behavior when enabled: true:

• A daemon thread polls the YAML file every poll_interval_seconds.
• mtime + content-hash dedup skips no-op writes (touch, git checkout to same SHA, etc.).
• Validation failure → keep the last-known-good config; write a reload_failed row to the audit chain. The previous engine keeps running so a typo doesn't lock you out.
• Validation success → atomic swap of the engine singleton; write a reload_ok audit row.

Recommended for: k8s ConfigMap mounts, CI rolling deploys. Not recommended for: workstation development (manual openakita serve restart is fine).

When >= 2 confirms accumulate in the same conversation, show one "Approve all / Deny all" affordance instead of stacking N modals:

security:
  confirmation:
    aggregation_window_seconds: 5.0  # default 0 (disabled)

Range: [0, 600]. Set to 5.0 for the typical UX. The window anchors on the most recent emission — only confirms that arrived within the window are batched.

Endpoint: POST /api/chat/security-confirm/batch with body {session_id, decision, within_seconds?}. The server clamps client within_seconds to the configured value so a malicious client cannot resolve every pending confirm with a huge window.

Five OPENAKITA_* variables can override fields without rewriting POLICIES.yaml. Useful for container deploys where the YAML is mounted read-only.

Notes:

• ENV is re-read on every config load → hot-reload (Phase A) picks up ENV changes automatically.
• Invalid values (e.g. OPENAKITA_POLICY_HOT_RELOAD=yes-please) log a loud [PolicyV2] warning, leave the YAML default in place, and write an env_override_invalid audit row.
• Successful overrides write an env_override_applied audit row listing the (env, path, value) tuples.
• OPENAKITA_POLICY_FILE is resolved early (before the override layer itself runs) and takes precedence over settings.identity_path.

We intentionally do NOT expose workspace.paths, safety_immune.paths, user_allowlist, or any approval-class table via ENV — those must live in VCS.

openakita --auto-confirm                 # interactive CLI
openakita --auto-confirm run "..."       # one-shot task
openakita --auto-confirm serve           # API server

Equivalent to OPENAKITA_AUTO_CONFIRM=1. Destructive (mutating_global) tools and safety_immune paths still require confirm — this is enforced in the classifier, not in confirmation.mode. So --auto-confirm does NOT mean "yolo mode".

The CLI flag is additive: setting it does not clear a pre-existing OPENAKITA_AUTO_CONFIRM env var that operators set elsewhere.

The audit log (security.audit.log_path, default data/audit/policy_decisions.jsonl) is append-only with tamper-evident hash chaining (C16). C20 adds optional rotation so a long-running deployment doesn't grow a single multi-GB file.

security:
  audit:
    log_path: data/audit/policy_decisions.jsonl
    enabled: true
    include_chain: true       # C16: hash-chain rows for tamper detection

    # === C20 rotation (default off — no behaviour change from C18) ===
    rotation_mode: none       # none | daily | size
    rotation_size_mb: 100     # threshold for "size" mode (1..10240 MiB)
    rotation_keep_count: 30   # how many archives to retain (0 = unlimited)

Modes:

• none (default): never rotate. Single file grows forever. Identical to C16/C17/C18 behaviour — operators who haven't touched their YAML see no change.
• daily: when the active file's mtime falls on a UTC day before "today", rename it to <stem>.YYYY-MM-DD.jsonl (date = mtime's UTC date) and start a fresh active file for today.
• size: when stat().st_size + len(new_line) > rotation_size_mb * 1024 * 1024, rename to <stem>.YYYYMMDDTHHMMSS.jsonl (UTC stamp at rotation moment).

Chain head carry-over: rotation preserves the hash chain across files. The first record written to the new active file has prev_hash = <last row_hash of the rotated archive>. The /api/config/security/audit endpoint uses verify_chain_with_rotation to walk archives + active file as one continuous chain, so SecurityView correctly reports tamper status across rotation boundaries.

Pruning: after each rotation, archives matching <stem>.*.jsonl are sorted by mtime ascending and the oldest beyond rotation_keep_count are deleted. 0 = keep everything (operator runs an external archiver).

Hot-reload: rotation parameters are read at each append via the lock-free global_engine._config attribute, so C18 hot-reload (security.hot_reload.enabled: true) takes effect on the very next audit write — no restart required.

Operator notes:

• Multi-process deployments: rotation happens under the same filelock.FileLock as appends, so concurrent processes serialize safely. Clocks should stay in sync via NTP (assumption shared with every other audit feature).
• Existing archives: a pre-existing archive at the would-be rotation target path is never overwritten — rotation skips with a WARN log and the active file keeps growing until the next eligible window. This prevents accidental history loss from clock jumps.
• Forensics: if the active file is moved aside for offline analysis, the archives still verify on their own via verify_chain_with_rotation(<active_path>) — the function tolerates a missing active file as long as archives exist.

For users behind firewalls:

# HTTP proxy
HTTP_PROXY=http://proxy:8080
HTTPS_PROXY=http://proxy:8080

# Or use custom API endpoint
ANTHROPIC_BASE_URL=https://your-proxy-service.com

# Requests per minute
RATE_LIMIT_RPM=60

# Tokens per minute
RATE_LIMIT_TPM=100000

# Memory limit (MB)
MEMORY_LIMIT=2048

# CPU cores
CPU_LIMIT=4

# Disk space (MB)
DISK_LIMIT=10240

To validate your configuration:

openakita config validate

To show current configuration:

openakita config show

1. Never commit .env - Add to .gitignore
2. Use separate configs for dev/staging/production
3. Rotate API keys regularly
4. Enable logging in production
5. Set resource limits to prevent runaway processes