Config & Working Directory

Working directory structure, config.json reference, environment variables, LLM providers, skills, and memory configuration.

This page covers:

• Working directory — Where things are stored
• config.json — What every field means and its defaults
• Environment variables — How to customize paths

No code required — just edit JSON and go.

What is the working directory?

By default, all config and data live in one folder — the working directory:

• ~/.copaw (the .copaw folder under your home directory)

When you run copaw init, this directory is created automatically. Here's what you'll find inside:

Tip: SOUL.md and AGENTS.md are the minimum required Markdown files for the agent's system prompt. Without them, the agent falls back to a generic "You are a helpful assistant" prompt. Run copaw init to auto-copy them based on your language choice (zh / en).

Changing paths with environment variables (optional)

If you don't want to use ~/.copaw, you can override the working directory or specific file names:

Example — use a different working dir for this shell:

export COPAW_WORKING_DIR=/home/me/my_copaw
copaw app

Config, HEARTBEAT, jobs, memory, etc. will be read/written under /home/me/my_copaw.

What's in config.json?

Below is the complete structure with every field, its type, default value, and what it does. You don't need to fill in everything — missing fields automatically use defaults.

Full example

{
  "channels": {
    "imessage": {
      "enabled": false,
      "bot_prefix": "",
      "db_path": "~/Library/Messages/chat.db",
      "poll_sec": 1.0
    },
    "discord": {
      "enabled": false,
      "bot_prefix": "",
      "bot_token": "",
      "http_proxy": "",
      "http_proxy_auth": ""
    },
    "dingtalk": {
      "enabled": false,
      "bot_prefix": "",
      "client_id": "",
      "client_secret": ""
    },
    "feishu": {
      "enabled": false,
      "bot_prefix": "",
      "app_id": "",
      "app_secret": "",
      "encrypt_key": "",
      "verification_token": "",
      "media_dir": "~/.copaw/media"
    },
    "qq": {
      "enabled": false,
      "bot_prefix": "",
      "app_id": "",
      "client_secret": ""
    },
    "console": {
      "enabled": true,
      "bot_prefix": ""
    }
  },
  "agents": {
    "defaults": {
      "heartbeat": {
        "every": "30m",
        "target": "main",
        "activeHours": null
      }
    },
    "running": {
      "max_iters": 50,
      "max_input_length": 131072
    },
    "language": "zh",
    "installed_md_files_language": "zh"
  },
  "last_api": {
    "host": "127.0.0.1",
    "port": 8088
  },
  "last_dispatch": null,
  "show_tool_details": true
}

Field-by-field reference

channels — Messaging channel configs

Each channel has a common base and channel-specific fields.

Common fields (all channels):

channels.imessage — macOS iMessage

channels.discord — Discord Bot

channels.dingtalk — DingTalk

channels.feishu — Feishu / Lark

channels.qq — QQ Bot

channels.console — Console (terminal I/O)

Tip: The system auto-watches config.json for changes (every 2 seconds). If you edit a channel's config while the app is running, it will automatically reload that channel — no restart needed.

agents — Agent behavior settings

agents.running — Agent runtime behavior

agents.defaults.heartbeat — Heartbeat scheduling

agents.defaults.heartbeat.activeHours (when not null):

See Heartbeat for a detailed guide.

last_api — Last used API address

This is auto-saved every time you run copaw app. Other CLI subcommands (like copaw cron) use this to know where to send requests.

last_dispatch — Last message dispatch target

Auto-updated when a user sends a message. Used by heartbeat when target = "last" — the heartbeat result will be sent to this channel/user/session.

show_tool_details — Tool output visibility

LLM Providers

CoPaw needs an LLM provider to work. You can set it up in three ways:

• copaw init — interactive wizard, the easiest way
• Console UI — click through the settings page at runtime
• API — PUT /providers/{id} and PUT /providers/active_llm

Built-in providers

For each provider you need to set:

Then choose which provider + model to activate:

Tip: Run copaw init and follow the prompts — it will list available models for each provider so you can pick one directly.

Note: You are responsible for ensuring the API key and base URL are valid. CoPaw does not verify whether the key is correct or has sufficient quota — make sure the chosen provider and model are accessible.

Environment Variables

Some tools need extra API keys (e.g. TAVILY_API_KEY for web search). You can manage them in three ways:

• copaw init — prompts "Configure environment variables?" during setup
• Console UI — edit on the settings page
• API — GET/PUT/DELETE /envs

Set variables are auto-loaded at app startup, so all tools and child processes can read them via os.environ.

Note: You are responsible for ensuring the values (e.g. third-party API keys) are valid. CoPaw only stores and injects them — it does not verify correctness.

Skills

Skills extend the agent's capabilities. They live in three directories:

Each skill is a directory with a SKILL.md file (YAML front matter with name and description), and optional references/ and scripts/ subdirectories.

Manage skills via:

• copaw init (choose all / none / custom during setup)
• copaw skills config (interactive toggle)
• API endpoints (/skills/...)

Memory

CoPaw has persistent cross-conversation memory: it automatically compresses context and saves key information to Markdown files for long-term retention. See Memory for full details.

Memory files are stored in two locations:

Embedding Configuration

Memory search relies on vector embeddings for semantic retrieval. Configure via these environment variables:

Recommended: Set EMBEDDING_API_KEY and keep FTS_ENABLED=true to use hybrid vector + BM25 retrieval for best results.

Summary

• Everything lives under ~/.copaw by default; override with COPAW_WORKING_DIR (and related env vars) if needed.
• Day-to-day you edit config.json (channels, heartbeat, language) and HEARTBEAT.md (what to ask on each heartbeat tick); manage cron jobs via CLI/API.
• Agent personality is defined by Markdown files in the working directory: SOUL.md + AGENTS.md (required).
• LLM providers are configured via copaw init or the console UI.
• Config changes to channels are auto-reloaded without restart (polled every 2 seconds).
• Call the Agent API: POST /agent/process, JSON body, SSE streaming; see Quick start — Verify install for examples.

Related pages

• Introduction — What the project can do
• Channels — How to fill in channels in config
• Heartbeat — How to fill in heartbeat in config

Agent Prompt Files at a Glance

Condensed from Agent Prompt Files — see the full page for details.

The prompt design in this section is inspired by OpenClaw.

File collaboration:

BOOTSTRAP.md (one-time)
    |-- generates -> PROFILE.md (who am I)
    |-- guides reading -> SOUL.md (my soul)
    +-- self-deletes after completion

AGENTS.md (daily manual)
    |-- reads/writes -> MEMORY.md (long-term memory)
    |-- references -> HEARTBEAT.md (periodic patrol)
    +-- references -> PROFILE.md (know the user)

In one sentence: SOUL defines character, PROFILE remembers relationships, BOOTSTRAP handles birth, AGENTS governs behavior, MEMORY accumulates experience, HEARTBEAT stays vigilant.