YouTipOpenclaw Setup
OpenClaw Configuration Directory | Rookie Tutorial
All configurations, status data, workspaces, and skills of OpenClaw (also known as Clawdbot) are centralized in the core directory under the user's home directory: `~/.openclaw/` (Linux/macOS) or `%USERPROFILE%.openclaw` (Windows).
`~/.openclaw/` is the root configuration directory of the entire system, which is automatically created upon first installation/running of `openclaw onboard` or `openclaw onboard --install-daemon`.
~/.openclaw/
├── openclaw.json # Main configuration file (JSON/JSON5)
├── workspace/ # Your AI "soul" folder (git version control recommended)
│ ├── SOUL.md # Personality settings (tone, style)
│ ├── USER.md # Your personal information (helps AI understand you better)
│ ├── MEMORY.md # Long-term memory (manually editable)
│ ├── IDENTITY.md # Agent name, image
│ ├── AGENTS.md # Multi-Agent routing rules
│ ├── BOOT.md # Startup prompt
│ ├── HEARTBEAT.md # Daily checklist
│ └── skills/ # Installed skills (each skill is a subfolder)
├── agents// # Independent state for each Agent
├── memory/.sqlite # Vector memory database
├── credentials/ # API Key, OAuth (legacy)
├── skills/ # Global skill packages
└── secrets.json # Encrypted credentials (optional)
!(#)
**Most Important Files:**
* `openclaw.json`: Global settings (model, channel, port, security policy)
* All `.md` files under `workspace/`: **Edit directly with VS Code for immediate effect!**
View/Modify Configuration Commands:
openclaw configure # Interactive configuration wizard
openclaw config file # Show full path
openclaw config get agent.model
openclaw config set agent.model "anthropic/claude-3-5-sonnet"
openclaw config validate # Validate configuration
| Path | Purpose |
| --- | --- |
| `~/.openclaw/openclaw.json` | **Main configuration file** (most important!) Stores global settings (model, Gateway mode, bind address, Agents defaults, plugins, etc.). Can be viewed/modified with commands: • `openclaw config file` (show full path) • `openclaw config get ` • `openclaw config set ` |
| `~/.openclaw/workspace/` | **Default workspace** (where the Agent's "soul" resides) Contains the following Markdown files (editable directly and take effect immediately): • `SOUL.md`: AI personality/tone settings • `USER.md`: Your personal preferences and background • `MEMORY.md`: Long-term memory records • `AGENTS.md`: Instruction descriptions • `IDENTITY.md`: Name/theme • `BOOT.md`: Startup configuration • `HEARTBEAT.md`: Periodic checklist |
| `~/.openclaw/agents//` | Individual Agent state directory (`` is the instance ID) |
| `~/.openclaw/agents//agent/auth-profiles.json` | **API Key & OAuth credentials** (new recommended location) Legacy location may be in `~/.openclaw/credentials/` |
| `~/.openclaw/memory/.sqlite` | Vector index storage (for memory search) |
| `~/.openclaw/skills/` | **Global skills directory** Skills installed via `openclaw skills install` or `clawhub install` are placed here (each skill is a subfolder containing SKILL.md) |
| `~/.openclaw/memory/` | Long-term memory related files (SQLite + vector embeddings) |
| `/tmp/openclaw/*.log` | Gateway service logs (for debugging) |
### 1. Main Configuration File
**Path:** `~/.openclaw/openclaw.json`
**Description:** OpenClaw's core configuration file, containing all system-level settings.
**Main Configuration Items:**
* **gateway** - Gateway service configuration
* `mode`: Gateway mode (e.g., "local")
* `port`: Gateway port number (default 18789)
* `bind`: Bind address (default 127.0.0.1)
* `token`: Access token, used for Web UI authentication
* **models** - AI model configuration
* Default model settings
* API authentication information
* **messages** - Message processing configuration
* TTS (text-to-speech) settings
* Message format configuration
**Example Configuration Snippet:**
```json
{
"gateway": {
"mode": "local",
"port": 18789,
"bind": "127.0.0.1",
"token": "c9917c5a066beeb26266d09baed99495e7563b33c771e89a"
}
}
**Operation Suggestions:**
* Automatically generated via `openclaw onboard` wizard after first installation
* Restart gateway service after modifying configuration for changes to take effect
* Keep token value secure as it is used for Web UI access
### 2. Workspace Directory
**Path:** `~/.openclaw/workspace/`
**Description:** OpenClaw's default working directory, where all AI-generated files, temporary files, and user-requested output files are saved.
**Main Purposes:**
* Default location for AI agent to read/write files
* Code execution output storage
* Document generation and editing
* Temporary data storage
**Permission Notes:**
* By default, AI can only access this directory and its subdirectories
* To access other paths, configure the `filesystem-mcp` skill and grant additional permissions
* Windows users may need to copy files from workspace to other locations
**Usage Suggestions:**
* Regularly clean up unnecessary temporary files
* Important outputs should be backed up outside the workspace
* Create project subdirectories here for organization and management
### 3. Agent State Directory
**Path:** `~/.openclaw/agents//`
**Description:** The state and configuration storage directory for each Conversation's agent. `` is the conversation ID, and each conversation has its own independent configuration space.
**Directory Structure:**
~/.openclaw/agents//
├── agent/
│ ├── auth-profiles.json # OAuth and API keys for this conversation
│ └── ...
└── ...
**auth-profiles.json Description:**
* Stores API authentication information used by this agent
* Contains OAuth tokens for various services
* New versions use this path; older versions stored in `~/.openclaw/credentials/`
**Data Isolation:**
* Authentication information for each conversation is independent
* Different API keys can be configured for different conversations
* Supports multiple agents running in parallel
### 4. Authentication Credentials Directory (Legacy)
**Path:** `~/.openclaw/credentials/`
**Description:** Legacy credential storage location for older versions of OpenClaw.
**Migration Notes:**
* New versions have migrated to `~/.openclaw/agents//agent/auth-profiles.json`
* Users upgrading from older versions may need to reconfigure credentials
* Recommended to use `openclaw models auth setup` to reconfigure
### 5. Memory Storage Directory
**Path:** `~/.openclaw/memory/`
**Description:** Storage location for OpenClaw's persistent memory system, containing vector indexes and conversation history.
**Main Files:**
* **`.sqlite`** - Vector index database
* Stores semantic vectors of conversations
* Supports semantic search functionality
* Used for long-term memory retrieval
* **`YYYY-MM-DD.md`** - Daily conversation logs
* Markdown files named by date
* Records all conversation content for that day
* Facilitates manual review and archiving
**Memory Functions:**
* **Vector Search:** Use `memory search "keyword"` to search historical conversations
* **Context Association:** Supports cross-conversation context understanding
* **Long-term Memory:** Agent will "remember" user preferences and habits
**Maintenance Suggestions:**
* Regularly back up the memory directory
* Large databases may affect performance; consider periodic archiving
* Log files can be used for auditing and troubleshooting
### 6. Skills Directory
**Path:** `~/.openclaw/skills/`
**Description:** Installation location for globally shared Skills. Skills are plugins that extend OpenClaw's functionality.
**Skill Management:**
* **Install skill:** `npx clawhub install `
* **List skills:** `openclaw skills list`
* **Search skills:** `npx clawhub search `
**Common Skill Examples:**
* `filesystem-mcp` - File system operations
* `github` - GitHub integration
* `nano-pdf` - PDF editing
* `notion` / `obsidian` - Note synchronization
* `weather` - Weather queries
* `summarize` - Content summarization
**Skill Ecosystem:**
* Community skill library ClawHub provides 500+ skills
* Supports custom skill development
* Skills can access external APIs and system resources
**Configuration Notes:**
* Each skill may require separate API Key configuration
* Some skills depend on system tools (e.g., GitHub CLI)
* macOS-specific skills are unavailable on Windows/Linux
### 7. Gateway Log Directory
**Path:** `/tmp/openclaw/*.log`
**Description:** Gateway service runtime logs, stored in the system temporary directory.
**Log Types:**
* Gateway start/stop logs
* API request/response logs
* Error and exception logs
* Performance monitoring information
**Log Management:**
* Logs in temporary directory may be cleared after system restart
* Use `openclaw gateway --verbose` to view detailed logs
* Check log files first when troubleshooting issues
**Gateway Service Management:**
openclaw gateway start # Start gateway
openclaw gateway status # View status
openclaw gateway stop # Stop gateway
---
## Other Important Files
### USER.md
**Path:** Usually located in workspace or user-defined location
**Description:** User information file, containing personalized information about the user to help AI better understand user needs.
**Content Examples:**
* User preference settings
* Common workflows
* Project background information
* Custom instructions
---
## Configuration File Management Best Practices
### 1. Backup Strategy
**Key Directory Backup:**
```bash
# Backup entire configuration directory
tar -czf openclaw-backup-$(date +%Y%m%d).tar.gz ~/.openclaw/
# Backup only core configuration
cp ~/.openclaw/openclaw.json ~/backups/
cp -r ~/.openclaw/memory/ ~/backups/memory/
**Recommended Backup Frequency:**
* Main configuration file: After each modification
* Memory database: Once a week
* Skill configuration: After installing new skills
### 2. Security Recommendations
**Sensitive Information Protection:**
* `openclaw.json` contains gateway token, should not be made public
* `auth-profiles.json` contains API keys, requires encryption protection
* Regularly rotate API keys
* Do not commit configuration files to version control systems
**Permission Settings:**
```bash
# Ensure configuration directory is only accessible by user
chmod 700 ~/.openclaw/
chmod 600 ~/.openclaw/openclaw.json
chmod 600 ~/.openclaw/agents/*/agent/auth-profiles.json
### 3. Migration and Upgrade
**Version Upgrade Notes:**
* Back up entire `~/.openclaw/` directory before upgrading
* Check release notes for configuration changes
* Legacy credentials may need migration
**Cross-device Synchronization:**
* Synchronize configuration files to achieve multi-device consistency
* Note path differences (Windows vs Unix)
* Sensitive information should be configured independently
### 4. Troubleshooting
**Configuration Problem Diagnosis:**
```bash
# Check configuration file syntax
cat ~/.openclaw/openclaw.json | json_pp
# Deep check
openclaw doctor --deep
# View gateway status
openclaw gateway status
**Common Issues:**
* **Authentication failure:** Run `openclaw models auth setup` to reconfigure
* **Gateway cannot start:** Check port occupancy, view log files
* **Skill unavailable:** Confirm skill dependencies are installed, check API keys
---
## Environment Variable Configuration
OpenClaw supports configuration via environment variables:
```bash
# API key environment variables
export ANTHROPIC_API_KEY="your-key-here"
export OPENAI_API_KEY="your-key-here"
export DEEPSEEK_API_KEY="your-key-here"
# Custom configuration directory
export OPENCLAW_HOME="~/custom-path/.openclaw"
**Environment Variable Priority:**
* API Keys in environment variables are automatically detected by the onboard wizard
* Can override default values in configuration files
* Suitable for CI/CD environments and containerized deployments
---
## Network and Deployment Configuration
### Local Deployment
**Default Configuration:**
* Bind address: 127.0.0.1 (local access only)
* Gateway port: 18789
**Access Method:**
http://127.0.0.1:18789/#token=
### Cloud Deployment
OpenClaw supports deployment on cloud servers:
**Supported Platforms:**
* Alibaba Cloud: [https://www.aliyun.com/activity/ecs/clawdbot](https://www.aliyun.com/activity/ecs/clawdbot?userCode=i5mn5r7m)
* Tencent Cloud: [https://cloud.tencent.com/developer/article/2624973](https://cloud.tencent.com/act/cps/redirect?redirect=37925&cps_key=4537fb0f9e70f157220dafdec0f9c750)
* 1Panel
* Docker containers
**Cloud Configuration Features:**
* Requires configuring public network access permissions
* May need to configure firewall rules
* Supports domain binding and SSL certificates
---
## Integration Platform Configuration
OpenClaw supports multiple instant messaging platforms:
### Supported Platforms
* **International:** WhatsApp, Telegram, Discord, Slack, iMessage
* **Domestic China:** Feishu, DingTalk
### Configuration Location
Chat channel configurations are stored in `openclaw.json`, including:
* Channel type (Slack/Feishu, etc.)
* Authentication Token
* Channel whitelist/blacklist
* Response mode (DM/group chat)
### Configuration Management
```bash
# Add new channel
openclaw channels add
# List configured channels
openclaw channels list
# Pairing management
openclaw pairing list
openclaw pairing approve