文档 – OpenClaw 教程

OpenClaw 技术文档

OpenClaw 是自托管 AI 代理网关，连接 WhatsApp、Telegram、Discord、iMessage 等聊天应用到 AI 编码代理。本页面面向开发者和运维人员，提供核心技术文档。

📖 官方文档

完整技术文档

🐙 GitHub

源码与 Issue

💻 CLI 参考

命令行完整文档

安装部署

系统要求

Node.js 24 (推荐) 或 Node.js 22.14+ LTS，内存 ≥ 1GB。

快速安装

npm install -g openclaw@latest
openclaw onboard --install-daemon
openclaw gateway start
openclaw dashboard

Docker 部署

git clone https://github.com/openclaw/openclaw.git
cd openclaw
./scripts/docker/setup.sh

使用预构建镜像：

export OPENCLAW_IMAGE="ghcr.io/openclaw/openclaw:latest"
./scripts/docker/setup.sh

健康检查

openclaw gateway status
openclaw doctor
openclaw logs --follow

配置

配置文件：~/.openclaw/openclaw.json（JSON5 格式，支持注释）

最小配置

{
  agents: { defaults: { workspace: "~/.openclaw/workspace" } },
  channels: { whatsapp: { allowFrom: ["+15555550123"] } }
}

配置命令

openclaw configure                      # 交互式配置
openclaw config get agents.defaults.workspace
openclaw config set agents.defaults.heartbeat.every "2h"
openclaw config validate

配置验证失败时，运行 openclaw doctor 查看问题，openclaw doctor --fix 应用修复。

频道接入

支持的频道

频道	配置路径	文档
WhatsApp	`channels.whatsapp`	配置
Telegram	`channels.telegram`	配置
Discord	`channels.discord`	配置
Signal	`channels.signal`	配置
iMessage	`channels.imessage`	配置
Slack	`channels.slack`	配置

DM 策略

{
  channels: {
    telegram: {
      enabled: true,
      botToken: "123:abc",
      dmPolicy: "pairing",    # pairing | allowlist | open | disabled
      allowFrom: ["tg:123"]
    }
  }
}

"pairing" — 未知发送者获取配对码（默认）
"allowlist" — 仅允许 allowFrom 列表
"open" — 允许所有 DM（需设置 allowFrom: ["*"]）
"disabled" — 忽略所有 DM

架构

Gateway 是会话、路由和频道连接的唯一数据源。

🔀 多频道网关

单进程服务 WhatsApp、Telegram、Discord 等

🤖 多代理路由

按代理、工作区或发送者隔离会话

🖼️ 媒体支持

发送接收图片、音频、文档

📱 移动节点

iOS/Android 配对，支持相机、语音

网络模型

本地：http://127.0.0.1:18789/
远程：Web surfaces 或 Tailscale

模型配置

{
  agents: {
    defaults: {
      model: {
        primary: "anthropic/claude-sonnet-4-6",
        fallbacks: ["openai/gpt-5.2"]
      },
      models: {
        "anthropic/claude-sonnet-4-6": { alias: "Sonnet" },
        "openai/gpt-5.2": { alias: "GPT" }
      }
    }
  }
}

支持的提供商

提供商	示例
Anthropic	`anthropic/claude-opus-4-6`
OpenAI	`openai/gpt-5.2`
Google	`google/gemini-2.5-pro`
Ollama	`ollama/qwen3.5:35b`
OpenRouter	`openrouter/auto`
NVIDIA	`nvidia/z-ai/glm5`

更多：Provider Directory

CLI 参考

Gateway 管理

openclaw gateway status
openclaw gateway start
openclaw gateway stop
openclaw gateway restart

配置管理

openclaw config get <path>
openclaw config set <path> <value>
openclaw config validate

频道管理

openclaw channels list
openclaw channels add --channel telegram --token "<token>"

安全审计

openclaw security audit
openclaw security audit --deep
openclaw security audit --fix

全局标志

标志	说明
`--dev`	隔离到 ~/.openclaw-dev
`--profile <name>`	隔离到 ~/.openclaw-<name>
`--json`	JSON 格式输出
`--no-color`	禁用颜色

安全配置

访问控制

{
  channels: {
    whatsapp: {
      allowFrom: ["+15555550123"],
      groups: { "*": { requireMention: true } }
    }
  },
  messages: { groupChat: { mentionPatterns: ["@openclaw"] } }
}

沙箱模式

{
  agents: {
    defaults: {
      sandbox: {
        mode: "non-main",   # off | non-main | all
        scope: "agent"      # session | agent | shared
      }
    }
  }
}

故障排除

诊断工具

openclaw doctor
openclaw logs --follow
curl http://127.0.0.1:18789/healthz

常见问题

问题	解决方案
Gateway 无法启动	`openclaw doctor` 检查配置
频道连接失败	检查 token，运行 `openclaw channels status`
代理无响应	检查模型配置和 API key
内存占用高	调整会话重置策略

更多：故障排除指南

插件开发

插件管理

openclaw plugins list
openclaw plugins install <path|npm-spec>
openclaw plugins enable <id>
openclaw plugins disable <id>

开发资源

HTTP API

API	端点	用途
Health	`/healthz`	健康检查
OpenAI Chat	`/v1/chat/completions`	OpenAI 兼容 API
Tools Invoke	`/api/tools/invoke`	工具调用

更多：OpenAI API 文档