跳转至

配置指南

ZeroClaw 的配置文件位于 ~/.zeroclaw/config.toml，由 onboard 命令自动创建。

基本配置

API 和模型配置

# API 密钥（支持多个提供商）
# 注意：生产环境建议使用环境变量或加密存储
api_key = "sk-ant-api03-..."
default_provider = "openrouter"
default_model = "anthropic/claude-sonnet-4-20250514"
default_temperature = 0.7

# 自定义提供商端点（可选）
[[custom_providers]]
name = "my-api"
base_url = "https://api.mycompany.com/v1"
api_key = "my-secret-key"

支持的提供商

提供商 配置键 示例
OpenRouter openrouter anthropic/claude-3-5-sonnet
Anthropic anthropic claude-3-5-sonnet-20241022
OpenAI openai gpt-4-turbo
Groq groq llama3-70b-8192
DeepSeek deepseek deepseek-chat
Ollama ollama http://localhost:11434
自定义 custom:https://... 任何 OpenAI 兼容 API

内存配置

后端选择

[memory]
# 内存后端：sqlite（默认）、lucid、markdown、none
backend = "sqlite"

# 自动保存对话到内存
auto_save = true

# 选择性使用嵌入（可选）
embedding_provider = "openai"

# 混合搜索权重（总和应为 1.0）
vector_weight = 0.7     # 向量相似度权重
keyword_weight = 0.3    # 关键词搜索权重

内存后端对比

后端 适用场景 优点 缺点
SQLite 生产环境 快速、可靠、支持向量搜索 需要 SQLite 依赖
Lucid 大规模场景 分层记忆、云同步 需要 lucid 服务
Markdown 简单场景 人类可读、易于编辑 需要手动管理
none 无状态 零存储、隐私保护 无记忆能力

Lucid 配置（可选）

# 启用 Lucid 分层记忆后端
[memory]
backend = "lucid"

# Lucid 环境变量（可选，有默认值）
ZEROCLAW_LUCID_CMD=/usr/local/bin/lucid
ZEROCLAW_LUCID_BUDGET=200
ZEROCLAW_LUCID_LOCAL_HIT_THRESHOLD=3
ZEROCLAW_LUCID_RECALL_TIMEOUT_MS=120
ZEROCLAW_LUCID_STORE_TIMEOUT_MS=800
ZEROCLAW_LUCID_FAILURE_COOLDOWN_MS=15000

网关配置

安全设置

[gateway]
# 启用配对码认证（强烈推荐）
require_pairing = true

# 防止直接绑定到 0.0.0.0（需要配置隧道）
allow_public_bind = false

# 默认绑定地址
bind_address = "127.0.0.1"

# 默认端口（0 表示随机端口）
port = 8080

配对流程

  1. 启动网关：zeroclaw gateway
  2. 获取配对码：从控制台输出获取 6 位配对码
  3. 交换 Token： 
    POST /pair
X-Pairing-Code: 123456
Response: { "token": "eyJ..." }
  4. 使用 Token： 
    POST /webhook
Authorization: Bearer eyJ...
Body: { "message": "你好" }

自主运行配置

[autonomy]
# 自主级别：readonly（只读）、supervised（监督）、full（完全）
level = "supervised"

# 工作区限制（防止访问系统文件）
workspace_only = true

# 允许执行的命令列表
allowed_commands = [
    "git", "npm", "cargo", "ls", "cat", "grep",
    "python", "node", "docker", "kubectl"
]

# 禁止访问的路径
forbidden_paths = [
    "/etc", "/root", "/proc", "/sys",
    "/.ssh", "/.gnupg", "/.aws"
]

运行时配置

[runtime]
# 运行时类型：native（原生）、docker（容器）
kind = "native"

# Docker 配置（仅当 kind = "docker" 时生效）
[runtime.docker]
image = "alpine:3.20"
network = "none"
memory_limit_mb = 512
cpu_limit = 1.0
read_only_rootfs = true
mount_workspace = true
allowed_workspace_roots = []

运行时选择

运行时 安全性 性能 资源需求 适用场景
Native 中 高 低 开发环境、受信任环境
Docker 高 中 高 生产环境、不受信任代码

隧道配置

[tunnel]
# 隧道提供商：none（无）、cloudflare、tailscale、ngrok、custom
provider = "none"

# Cloudflare Tunnel 配置
[tunnel.cloudflare]
tunnel_id = "your-tunnel-id"
account_tag = "your-account-tag"

# Tailscale 配置
[tunnel.tailscale]
auth_key = "your-auth-key"
hostname = "zeroclaw-1"

# ngrok 配置
[tunnel.ngrok]
authtoken = "your-auth-token"
domain = "your-domain.ngrok-free.app"

安全配置

[secrets]
# 加密 API 密钥（推荐）
encrypt = true

# 加密密钥文件路径（自动生成）
key_file = "~/.zeroclaw/crypto.key"

浏览器配置

[browser]
# 启用浏览器工具（需要显式选择）
enabled = false

# 允许访问的域名列表（必需）
allowed_domains = [
    "docs.rs",
    "github.com",
    "stackoverflow.com"
]

# 浏览器后端
backend = "agent_browser"  # agent_browser, rust_native, computer_use, auto

# Rust-Native 配置
native_headless = true
native_webdriver_url = "http://127.0.0.1:9515"
# native_chrome_path = "/usr/bin/chromium"

# Computer-Use Sidecar 配置
[browser.computer_use]
endpoint = "http://127.0.0.1:8787/v1/actions"
timeout_ms = 15000
allow_remote_endpoint = false

身份配置

OpenClaw 格式（默认）

[identity]
format = "openclaw"

# 工作区中的身份文件
# ~/.zeroclaw/workspace/IDENTITY.md
# ~/.zeroclaw/workspace/SOUL.md
# ~/.zeroclaw/workspace/USER.md

AIEOS 格式

[identity]
format = "aieos"
aieos_path = "identity.json"
# 或内联 JSON
aieos_inline = '''{
  "identity": {
    "names": { "first": "Nova", "nickname": "N" }
  },
  "psychology": {
    "neural_matrix": { "creativity": 0.9 }
  }
}'''

心跳配置

[heartbeat]
# 启用周期性任务
enabled = false

# 执行间隔（分钟）
interval_minutes = 30

# 周期性任务文件
# ~/.zeroclaw/workspace/HEARTBEAT.md

渠道配置

Telegram

[channels_config.telegram]
bot_token = "your-bot-token"

# 允许的用户列表（推荐）
allowed_users = ["your_username", "123456789"]

# 使用 "*" 允许所有人（不推荐）
# allowed_users = ["*"]

Discord

[channels_config.discord]
bot_token = "your-bot-token"

# 允许的用户 ID
allowed_user_ids = ["your-discord-user-id"]

WhatsApp

[channels_config.whatsapp]
access_token = "EAABx..."
phone_number_id = "123456789012345"
verify_token = "my-secret-token"
allowed_numbers = ["+1234567890"]

Composio 集成

[composio]
# 启用 1000+ OAuth 应用集成
enabled = false

# Composio API 密钥（可选，自动加密）
# api_key = "cmp_..."
entity_id = "default"

配置验证

在修改配置后，使用以下命令验证：

# 检查配置语法
zeroclaw doctor

# 测试网关连接
zeroclaw gateway --test

# 验证频道配置
zeroclaw channel doctor

# 获取集成信息
zeroclaw integrations info Telegram

环境变量选项

部分配置也可以通过环境变量设置：

环境变量 说明
ZEROCLAW_API_KEY API 密钥
ZEROCLAW_PROVIDER 默认提供商
ZEROCLAW_MODEL 默认模型
ZEROCLAW_LOG_LEVEL 日志级别
ZEROCLAW_CONFIG_PATH 自定义配置路径

配置最佳实践

  1. 安全性
  2. 使用 encrypt = true 加密敏感信息
  3. 定期轮换 API 密钥

  4. 限制命令和路径访问

  5. 性能

  6. 根据场景选择合适的内存后端
  7. 调整混合搜索权重

  8. 选择合适的运行时

  9. 可维护性

  10. 使用注释说明配置项
  11. 保持配置文件版本控制
  12. 使用环境变量覆盖敏感配置

故障排查

配置文件未生效

# 检查配置文件位置
ls -la ~/.zeroclaw/config.toml

# 重新运行向导
zeroclaw onboard --interactive

API 密钥问题

# 测试 API 连接
zeroclaw agent -m "test"

# 查看详细日志
RUST_LOG=debug zeroclaw agent -m "test"

内存问题

# 切换到轻量级后端
# 编辑 config.toml
[memory]
backend = "none"

详细的安全配置请参阅 安全配置 章节。