OpenClaw 完全指南：从安装到玩转

~/.openclaw/
├── openclaw.json          # 主配置文件（JSON5）
├── .env                   # API 密钥和敏感信息
├── workspace/             # 默认工作空间
│   ├── SOUL.md            # 助手人格定义
│   ├── MEMORY.md          # 长期记忆
│   ├── USER.md            # 用户画像
│   ├── AGENTS.md          # 工作空间指令
│   └── skills/            # 工作空间技能
├── skills/                # 全局技能目录
├── agents/                # 多 Agent 配置
│   └── main/              # 主 Agent
│       └── agent/
│           └── auth-profiles.json  # 认证配置
└── credentials/           # 渠道凭据

// ~/.openclaw/openclaw.json
{
  agents: {
    defaults: {
      workspace: "~/.openclaw/workspace",
      model: "claude-sonnet-4-20250514",
      thinkingDefault: "high",
      verboseDefault: "off",
      timeoutSeconds: 900,
      compaction: {
        mode: "auto",
      },
    },
  },
  channels: {
    telegram: {
      botToken: "${TELEGRAM_BOT_TOKEN}",
      allowFrom: ["123456789"],
    },
  },
  models: {
    providers: {
      anthropic: {
        apiKey: "${ANTHROPIC_API_KEY}",
      },
    },
  },
}

{
  models: {
    providers: {
      anthropic: {
        apiKey: "${ANTHROPIC_API_KEY}",
        apiType: "anthropic",
      },
      openai: {
        apiKey: "${OPENAI_API_KEY}",
        apiType: "openai",
      },
      openrouter: {
        apiKey: "${OPENROUTER_API_KEY}",
        baseUrl: "https://openrouter.ai/api/v1",
        apiType: "openai",
      },
      // 自定义端点（连接 vLLM / Ollama 等）
      local: {
        baseUrl: "http://localhost:11434/v1",
        apiKey: "ollama",
        apiType: "openai",
      },
    },
  },
  agents: {
    defaults: {
      // 单模型
      model: "claude-sonnet-4-20250514",
      // 或带故障转移的模型链
      // model: {
      //   primary: "claude-sonnet-4-20250514",
      //   fallbacks: ["gpt-4o", "gemini-2.0-flash"],
      // },
    },
  },
}

// 1. 纯字符串
"apiKey": "sk-ant-xxx..."

// 2. 环境变量引用
"apiKey": "${ANTHROPIC_API_KEY}"

// 3. SecretRef 对象（高级）
"apiKey": { "source": "env", "id": "ANTHROPIC_API_KEY" }

{
  channels: {
    telegram: {
      botToken: "${TELEGRAM_BOT_TOKEN}",
      allowFrom: ["123456789", "987654321"],  // 允许的用户 ID
    },
  },
}

{
  channels: {
    telegram: {
      dmPolicy: "open",
      allowFrom: ["*"],
    },
  },
}

{
  agents: {
    defaults: { workspace: "~/.openclaw/workspace" },
    shopping: { workspace: "~/.openclaw/shopping-agent" },
    coding: { workspace: "~/.openclaw/coding-agent" },
  },
  channels: {
    whatsapp: {
      allowFrom: ["+155****0123"],
      agent: "shopping",  // WhatsApp 消息路由到购物 Agent
    },
    discord: {
      token: "${DISCORD_BOT_TOKEN}",
      allowFrom: ["123456789"],
      agent: "coding",  // Discord 消息路由到编码 Agent
    },
  },
}

{
  agents: {
    defaults: {
      workspace: "~/.openclaw/workspace",
      // 多 Agent 场景下使用 workspace-{agentId}
    },
  },
}

{
  agents: {
    defaults: {
      sandbox: {
        // 沙箱模式：non-main 会话在沙箱中运行
        mode: "non-main",
        backend: "docker",  // docker / ssh / openshell
        docker: {
          image: "openclaw/sandbox:latest",
        },
      },
    },
  },
}

{
  messages: {
    tts: {
      providers: {
        elevenlabs: {
          voiceId: "21m00Tcm4TlvDq8ikWAM",
          modelId: "eleven_multilingual_v2",
        },
        // 或使用系统 TTS
        microsoft: {
          voice: "en-US-AriaNeural",
        },
      },
    },
  },
}

{
  mcp: {
    servers: {
      "my-server": {
        command: "npx",
        args: ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"],
        env: {},
        cwd: "/tmp",
        // 或 HTTP 传输
        // url: "https://mcp.example.com/sse",
        tools: {
          include: ["read_file", "write_file"],
          // exclude: ["dangerous_tool"],
        },
      },
    },
  },
}

{
  session: {
    reset: {
      mode: "daily",        // "daily" / "idle" / 两者
      atHour: 0,            // daily 模式：每天 0 点重置
      idleMinutes: 30,      // idle 模式：30 分钟无活动重置
    },
    // 或使用简化形式
    // resetTriggers: ["daily", "idle"],
  },
}

{
  // 在配置文件中定义
  // 或通过 openclaw 命令管理
}

{
  gateway: {
    auth: {
      token: "${HERMES_GATEWAY_TOKEN}",  // Gateway 访问令牌
    },
  },
}

/status              查看 Gateway 和会话状态
/new                 开启新会话
/reset               重置当前会话
/compact             压缩上下文
/think <level>       设置思考深度（off/low/medium/high）
/verbose on|off      开关详细输出
/trace on|off        开关调用追踪
/usage off|tokens|full  查看 Token 使用量
/restart             重启 Gateway
/activation mention|always  设置激活模式

{
  agents: {
    defaults: {
      model: {
        primary: "claude-sonnet-4-20250514",
        fallbacks: ["gpt-4o", "gemini-2.0-flash"],
      },
    },
  },
}

{
  agents: {
    defaults: { workspace: "~/.openclaw/workspace" },
    work: {
      workspace: "~/.openclaw/work-agent",
      model: "claude-sonnet-4-20250514",
    },
    personal: {
      workspace: "~/.openclaw/personal-agent",
      model: "gpt-4o",
    },
  },
  channels: {
    slack: {
      botToken: "${SLACK_BOT_TOKEN}",
      agent: "work",  // Slack -> 工作 Agent
    },
    whatsapp: {
      allowFrom: ["+155****0123"],
      agent: "personal",  // WhatsApp -> 个人 Agent
    },
  },
}

{
  agents: {
    defaults: {
      compaction: {
        mode: "auto",     // "auto" / "off"
        model: "gpt-4o-mini",  // 压缩用模型（可选）
      },
    },
  },
}

/think high
帮我设计一个微服务架构方案

{
  agents: {
    defaults: {
      sandbox: {
        mode: "non-main",
        backend: "docker",
      },
    },
  },
  gateway: {
    auth: {
      token: "${GATEWAY_TOKEN}",
    },
  },
  channels: {
    telegram: {
      dmPolicy: "pairing",
      allowFrom: ["123456789"],
    },
  },
}

{
  agents: {
    defaults: {
      timeoutSeconds: 900,  // 最大执行时间（秒）
      humanDelay: {
        mode: "natural",   // "natural" / "custom" / "off"
        minMs: 500,        // 自定义模式下的最小延迟
        maxMs: 2000,       // 最大延迟
      },
    },
  },
}

# 安装和更新
openclaw onboard              # Onboarding 向导
openclaw onboard --install-daemon  # 安装守护进程
openclaw update               # 更新到最新版
openclaw update --channel dev  # 切换到开发版
openclaw doctor               # 健康检查

# Gateway 控制
openclaw gateway status       # 查看状态
openclaw gateway stop         # 停止
openclaw gateway --port 18789 --verbose  # 前台调试
openclaw dashboard            # 打开控制面板

# 配置
openclaw configure            # 配置向导
openclaw config get KEY       # 读取配置
openclaw config set KEY VAL   # 设置配置
openclaw config unset KEY     # 删除配置

# 消息和对话
openclaw message send --target +123 --message "Hello"  # 发送消息
openclaw agent --message "问题" --thinking high         # 与助手对话

# 安全
openclaw pairing approve <channel> <code>  # 批准 DM 配对

# 迁移（从 Hermes 迁移到 OpenClaw）
# 参见 https://docs.openclaw.ai/install/migrating/migrating-from-hermes