openclaw-complete-deployment-guide

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

在阿里云上部署 OpenClaw 完整指南

Complete Guide to Deploying OpenClaw on Alibaba Cloud

覆盖阿里云百炼模型配置、飞书 / 钉钉(传统机器人 + DEAP 高级方案)/ QQ / Discord 全平台接入、Qoder CLI 集成,以及高级配置与运维。

Covers Alibaba Cloud Bailian model configuration, full-platform access for Feishu / DingTalk (traditional bot + DEAP advanced solution) / QQ / Discord, Qoder CLI integration, as well as advanced configuration and O&M.

⚠️ 安全警告

⚠️ Security Warning

在开始之前,请务必阅读以下注意事项:
  1. 切勿在个人主力电脑上部署 OpenClaw——它具有高文件系统和命令执行权限
  2. 务必使用云服务器(如阿里云 ECS)进行部署,与本地环境隔离
  3. 保护好你的 API 密钥——使用环境变量或安全保险箱,不要硬编码在代码中
  4. 使用强随机令牌限制 Gateway 访问,避免使用简单密码
  5. 定期轮换凭证——特别是钉钉/飞书/QQ 等平台的应用密钥

Before you start, please read the following precautions carefully:
  1. Never deploy OpenClaw on your primary personal computer - it has high file system and command execution permissions
  2. Be sure to use a cloud server (such as Alibaba Cloud ECS) for deployment to isolate it from your local environment
  3. Protect your API keys properly - use environment variables or secret vaults, do not hardcode them in code
  4. Use strong random tokens to restrict Gateway access, avoid using simple passwords
  5. Rotate credentials regularly - especially application keys for platforms such as DingTalk/Feishu/QQ

使用场景

Usage Scenarios

  • 在阿里云 ECS 服务器上从零部署 OpenClaw AI 助手
  • 通过钉钉(Stream 机器人或 DEAP 高级方案)与 AI 对话
  • 通过飞书、QQ 或 Discord 接入 OpenClaw
  • 配置阿里云百炼 Coding Plan 作为 AI 推理后端
  • 将 Qoder CLI 注册为 ACP Agent,实现钉钉/飞书中的代码开发
  • Deploy OpenClaw AI assistant from scratch on Alibaba Cloud ECS server
  • Talk to AI through DingTalk (Stream bot or DEAP advanced solution)
  • Access OpenClaw through Feishu, QQ or Discord
  • Configure Alibaba Cloud Bailian Coding Plan as the AI inference backend
  • Register Qoder CLI as ACP Agent to implement code development in DingTalk/Feishu

示例

Examples

bash
undefined
bash
undefined

安装 OpenClaw

Install OpenClaw

启动 Gateway

Start Gateway

openclaw gateway --port 18789 --verbose
openclaw gateway --port 18789 --verbose

交互式配置模型和渠道

Interactive configuration of models and channels

openclaw onboard
openclaw onboard

查看所有渠道状态

View all channel status

openclaw channel list
openclaw channel list

查看实时日志

View real-time logs

tail -f /tmp/openclaw-gateway.log
undefined
tail -f /tmp/openclaw-gateway.log
undefined

注意事项

Precautions

  • 切勿在本地主力电脑部署,务必使用云服务器(如阿里云 ECS)
  • 钉钉应用必须完成「版本发布」流程,仅保存配置不生效
  • 钉钉 Client Secret、百炼 API Key、QQ 机器人密钥均只显示一次,需立即保存
  • 飞书集成需选择「WebSocket 长连接」模式,不要使用 HTTP 回调
  • 钉钉 DEAP 方案需在同一服务器运行 Connector,确保 18789 端口本地可访问
  • 建议为 Gateway 配置随机强令牌认证(
    openssl rand -hex 24

  • Never deploy on your primary local computer, be sure to use a cloud server (such as Alibaba Cloud ECS)
  • DingTalk applications must complete the "version release" process, saving configuration only will not take effect
  • DingTalk Client Secret, Bailian API Key, QQ bot key are only displayed once, please save them immediately
  • Feishu integration requires the "WebSocket persistent connection" mode, do not use HTTP callbacks
  • DingTalk DEAP solution requires running Connector on the same server, ensure port 18789 is locally accessible
  • It is recommended to configure random strong token authentication for Gateway (
    openssl rand -hex 24
    )

概述

Overview

本指南将带你完成一套完整的 OpenClaw 云端部署,实现通过多种 IM 平台与 AI 助手对话,并可选接入 Qoder CLI 进行代码开发。
整体架构:
┌────────────────────────────────────────────────────────────┐
│                         用户层                              │
│  ┌────────┐  ┌────────┐  ┌──────┐  ┌─────────┐           │
│  │  飞书  │  │  钉钉  │  │  QQ  │  │ Discord │           │
│  └───┬────┘  └───┬────┘  └──┬───┘  └────┬────┘           │
└──────┼───────────┼──────────┼───────────┼─────────────────┘
       │           │          │           │
       └───────────┴──────────┴───────────┘
                     Stream / WebSocket
┌─────────────────────────────▼──────────────────────────────┐
│                   OpenClaw Gateway :18789                   │
│  ┌──────────────────────────────────────────────────────┐  │
│  │  ACP 协议层                                           │  │
│  │  ┌──────────┐  ┌──────────┐  ┌──────────┐           │  │
│  │  │  acpx    │  │  调度器  │  │  会话管理 │           │  │
│  │  └──────────┘  └──────────┘  └──────────┘           │  │
│  └──────────────────────────────────────────────────────┘  │
│  ┌──────────────────────────────────────────────────────┐  │
│  │  渠道连接器层(飞书 / 钉钉 / QQ / Discord)           │  │
│  └──────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────┘
                    阿里云百炼 API / Qoder CLI
部署步骤总览:
  1. 购买并配置阿里云 ECS 服务器
  2. 安装 Node.js 与 OpenClaw
  3. 配置阿里云百炼模型(Coding Plan)
  4. 配置 Gateway 外部访问与认证
  5. 配置 ACP 协议支持
  6. 安装并配置 Qoder CLI(可选)
  7. 接入 IM 平台(飞书 / 钉钉 / QQ / Discord)

This guide will walk you through a complete cloud deployment of OpenClaw, enabling conversations with the AI assistant through multiple IM platforms, and optional access to Qoder CLI for code development.
Overall Architecture:
┌────────────────────────────────────────────────────────────┐
│                         User Layer                         │
│  ┌────────┐  ┌────────┐  ┌──────┐  ┌─────────┐           │
│  │ Feishu │  │DingTalk│  │ QQ  │  │ Discord │           │
│  └───┬────┘  └───┬────┘  └──┬───┘  └────┬────┘           │
└──────┼───────────┼──────────┼───────────┼─────────────────┘
       │           │          │           │
       └───────────┴──────────┴───────────┘
                     Stream / WebSocket
┌─────────────────────────────▼──────────────────────────────┐
│                   OpenClaw Gateway :18789                   │
│  ┌──────────────────────────────────────────────────────┐  │
│  │  ACP Protocol Layer                                  │  │
│  │  ┌──────────┐  ┌──────────┐  ┌──────────┐           │  │
│  │  │  acpx    │  │ Scheduler│  │Session Mgmt│         │  │
│  │  └──────────┘  └──────────┘  └──────────┘           │  │
│  └──────────────────────────────────────────────────────┘  │
│  ┌──────────────────────────────────────────────────────┐  │
│  │  Channel Connector Layer (Feishu / DingTalk / QQ / Discord) │  │
│  └──────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────┘
                    Alibaba Cloud Bailian API / Qoder CLI
Deployment Steps Overview:
  1. Purchase and configure Alibaba Cloud ECS server
  2. Install Node.js and OpenClaw
  3. Configure Alibaba Cloud Bailian model (Coding Plan)
  4. Configure Gateway external access and authentication
  5. Configure ACP protocol support
  6. Install and configure Qoder CLI (optional)
  7. Access IM platforms (Feishu / DingTalk / QQ / Discord)

前置要求

Prerequisites

必需账号和权限

Required Accounts and Permissions

  • 阿里云账号
  • 阿里云百炼账号(用于模型 API)
  • 目标 IM 平台的开发者/管理员账号
  • Alibaba Cloud account
  • Alibaba Cloud Bailian account (for model API)
  • Developer/Administrator account for the target IM platform

必需软件(本地)

Required Software (Local)

  • SSH 客户端
  • 现代浏览器(用于访问各平台开发者控制台)

  • SSH client
  • Modern browser (for accessing each platform's developer console)

第一阶段:阿里云服务器购买与配置

Phase 1: Alibaba Cloud Server Purchase and Configuration

1.1 推荐服务器配置

1.1 Recommended Server Configuration

配置项最低要求推荐配置
CPU2 核2 核
内存2 GiB4 GiB
磁盘20 GB SSD40 GB ESSD
带宽1 Mbps20 Mbps+
操作系统Ubuntu 22.04 / CentOS 8Alibaba Cloud Linux 3
地域任意美国弗吉尼亚 / 中国香港(访问 AI 服务延迟低)
Configuration ItemMinimum RequirementRecommended Configuration
CPU2 vCPU2 vCPU
Memory2 GiB4 GiB
Disk20 GB SSD40 GB ESSD
Bandwidth1 Mbps20 Mbps+
Operating SystemUbuntu 22.04 / CentOS 8Alibaba Cloud Linux 3
RegionAnyNorthern Virginia, USA / Hong Kong, China (low latency for accessing AI services)

1.2 购买方式

1.2 Purchase Method

方式一:通过计算巢快速部署(推荐新手)
访问阿里云计算巢,一键部署预配置环境:
按页面指引:选择地域 → 选择实例规格 → 配置网络和安全组 → 确认创建。
方式二:手动购买 ECS 实例
  1. 访问 阿里云 ECS 控制台
  2. 点击「创建实例」
  3. 关键选项:
    • 镜像:Alibaba Cloud Linux 3 / Ubuntu 22.04(如有 OpenClaw 应用镜像可直接选用)
    • 实例规格
      ecs.c7.large
      (2 核 4 GiB)或更高
    • 系统盘:40 GB ESSD
    • 公网 IP:分配公网 IPv4
    • 带宽:按使用流量或按固定带宽(至少 1 Mbps)
  4. 配置安全组(见下方)
  5. 设置登录凭证(密钥对推荐)
  6. 确认并创建
Method 1: Quick deployment via Compute Nest (recommended for beginners)
Visit Alibaba Cloud Compute Nest to deploy the pre-configured environment with one click:
Follow the page guide: Select region → Select instance specification → Configure network and security group → Confirm creation.
Method 2: Manually purchase ECS instance
  1. Visit Alibaba Cloud ECS Console
  2. Click "Create Instance"
  3. Key options:
    • Image: Alibaba Cloud Linux 3 / Ubuntu 22.04 (you can directly select the OpenClaw application image if available)
    • Instance specification:
      ecs.c7.large
      (2 vCPU 4 GiB) or higher
    • System disk: 40 GB ESSD
    • Public IP: Allocate public IPv4
    • Bandwidth: Pay-by-traffic or fixed bandwidth (at least 1 Mbps)
  4. Configure security group (see below)
  5. Set login credentials (key pair is recommended)
  6. Confirm and create

1.3 配置安全组规则

1.3 Configure Security Group Rules

端口协议用途授权对象
22TCPSSH 远程连接你的 IP 地址
18789TCPOpenClaw Gateway0.0.0.0/0
配置步骤:
  1. ECS 控制台 → 找到实例 → 点击「安全组」
  2. 「配置规则」→「入方向」→「手动添加」以上规则
PortProtocolPurposeAuthorization Object
22TCPSSH remote connectionYour IP address
18789TCPOpenClaw Gateway0.0.0.0/0
Configuration Steps:
  1. ECS Console → Find the instance → Click "Security Group"
  2. "Configure Rules" → "Inbound Direction" → "Add Manually" the above rules

1.4 连接到服务器

1.4 Connect to the Server

bash
undefined
bash
undefined

使用密码登录

Login with password

ssh root@<你的服务器公网IP>
ssh root@<your server public IP>

使用密钥登录

Login with key

ssh -i /path/to/your-key.pem root@<你的服务器公网IP>
ssh -i /path/to/your-key.pem root@<your server public IP>

或通过阿里云控制台网页终端:

Or via Alibaba Cloud Console web terminal:

ECS 控制台 → 实例详情 → 远程连接

ECS Console → Instance Details → Remote Connection


---

---

第二阶段:安装 Node.js 与 OpenClaw

Phase 2: Install Node.js and OpenClaw

2.1 安装 Node.js(推荐 nvm)

2.1 Install Node.js (nvm recommended)

bash
undefined
bash
undefined

安装 nvm

Install nvm

安装 Node.js 22 LTS

Install Node.js 22 LTS

nvm install 22 nvm use 22 node -v # 验证:应输出 v22.x.x
undefined
nvm install 22 nvm use 22 node -v # Verification: should output v22.x.x
undefined

2.2 安装 OpenClaw

2.2 Install OpenClaw

方式一:通过官方安装脚本(推荐)
bash
curl -fsSL https://clawd.bot/install.sh | bash
方式二:通过 npm 全局安装
bash
npm install -g openclaw
验证安装:
bash
openclaw --version
Method 1: Via official installation script (recommended)
bash
curl -fsSL https://clawd.bot/install.sh | bash
Method 2: Global installation via npm
bash
npm install -g openclaw
Verify installation:
bash
openclaw --version

预期输出:版本号如 "2026.1.x"

Expected output: version number such as "2026.1.x"

若提示命令不存在,尝试旧名称:clawdbot --version

If the command is not found, try the old name: clawdbot --version

undefined
undefined

2.3 启动 OpenClaw Gateway

2.3 Start OpenClaw Gateway

bash
undefined
bash
undefined

方式一:前台启动(调试用)

Method 1: Start in foreground (for debugging)

openclaw gateway --port 18789 --verbose
openclaw gateway --port 18789 --verbose

方式二:后台启动

Method 2: Start in background

nohup setsid openclaw gateway --port 18789 --verbose > /tmp/openclaw-gateway.log 2>&1 &
nohup setsid openclaw gateway --port 18789 --verbose > /tmp/openclaw-gateway.log 2>&1 &

检查状态

Check status

systemctl --user status openclaw-gateway.service
systemctl --user status openclaw-gateway.service

Or

openclaw gateway status

---
openclaw gateway status

---

第三阶段:配置阿里云百炼模型(Coding Plan)

Phase 3: Configure Alibaba Cloud Bailian Model (Coding Plan)

3.1 购买 Coding Plan 套餐

3.1 Purchase Coding Plan Package

套餐首月价格次月价格每月请求量
Lite 基础版7.9 元40 元/月18,000 次
Pro 高级版39.9 元200 元/月90,000 次
  1. 访问 阿里云百炼控制台
  2. 导航至「Coding Plan」或「订阅套餐」
  3. 选择 Lite 或 Pro 完成支付
PackageFirst Month PriceSubsequent Monthly PriceMonthly Requests
Lite Basic Version¥7.9¥40/month18,000 times
Pro Advanced Version¥39.9¥200/month90,000 times
  1. Visit Alibaba Cloud Bailian Console
  2. Navigate to "Coding Plan" or "Subscription Packages"
  3. Select Lite or Pro to complete payment

3.2 获取 API 凭证

3.2 Obtain API Credentials

  • Base URL(固定):
    https://coding.dashscope.aliyuncs.com/v1
  • API Key 格式
    sk-sp-xxxxx
获取步骤:
  1. 登录 阿里云百炼控制台
  2. 进入「密钥管理」或「API Keys」
  3. 点击「创建 API Key」
  4. 立即复制并保存——关闭后无法再次查看
支持的模型:
  • qwen3.5-plus
    - 通用场景(推荐入门)
  • qwen3-max-2026-01-23
    - 高级推理
  • kimi-k2.5
    - 代码生成(如可用)
  • glm-5
    - 中文优化
  • Base URL (fixed):
    https://coding.dashscope.aliyuncs.com/v1
  • API Key Format:
    sk-sp-xxxxx
Obtainment Steps:
  1. Log in to Alibaba Cloud Bailian Console
  2. Go to "Key Management" or "API Keys"
  3. Click "Create API Key"
  4. Copy and save immediately - you cannot view it again after closing the page
Supported Models:
  • qwen3.5-plus
    - General scenarios (recommended for beginners)
  • qwen3-max-2026-01-23
    - Advanced reasoning
  • kimi-k2.5
    - Code generation (if available)
  • glm-5
    - Chinese optimized

3.3 配置 OpenClaw 使用百炼

3.3 Configure OpenClaw to Use Bailian

方式一:交互式引导
bash
openclaw onboard
按提示操作:
  1. 选择「添加自定义模型供应商」
  2. 供应商 ID:
    bailian
  3. Base URL:
    https://coding.dashscope.aliyuncs.com/v1
  4. API Key:粘贴
    sk-sp-xxxxx
  5. API 类型:
    openai-completions
  6. 添加模型:
    qwen3.5-plus
  7. 设为默认模型
方式二:手动编辑配置文件
编辑
~/.openclaw/openclaw.json
json
{
  "models": {
    "providers": {
      "bailian": {
        "baseUrl": "https://coding.dashscope.aliyuncs.com/v1",
        "apiKey": "sk-sp-YOUR_KEY_HERE",
        "api": "openai-completions",
        "models": [
          {
            "id": "qwen3.5-plus",
            "name": "Qwen 3.5 Plus",
            "reasoning": true,
            "input": ["text"],
            "contextWindow": 32000,
            "maxTokens": 4096
          }
        ]
      }
    }
  },
  "agents": {
    "defaults": {
      "model": {
        "primary": "bailian/qwen3.5-plus"
      }
    }
  }
}

Method 1: Interactive Guide
bash
openclaw onboard
Follow the prompts:
  1. Select "Add custom model provider"
  2. Provider ID:
    bailian
  3. Base URL:
    https://coding.dashscope.aliyuncs.com/v1
  4. API Key: Paste
    sk-sp-xxxxx
  5. API Type:
    openai-completions
  6. Add model:
    qwen3.5-plus
  7. Set as default model
Method 2: Manually edit configuration file
Edit
~/.openclaw/openclaw.json
:
json
{
  "models": {
    "providers": {
      "bailian": {
        "baseUrl": "https://coding.dashscope.aliyuncs.com/v1",
        "apiKey": "sk-sp-YOUR_KEY_HERE",
        "api": "openai-completions",
        "models": [
          {
            "id": "qwen3.5-plus",
            "name": "Qwen 3.5 Plus",
            "reasoning": true,
            "input": ["text"],
            "contextWindow": 32000,
            "maxTokens": 4096
          }
        ]
      }
    }
  },
  "agents": {
    "defaults": {
      "model": {
        "primary": "bailian/qwen3.5-plus"
      }
    }
  }
}

第四阶段:配置 Gateway 外部访问与认证

Phase 4: Configure Gateway External Access and Authentication

当需要通过钉钉 DEAP 或其他外部服务访问 Gateway 时,需配置认证和 HTTP 端点。
When you need to access the Gateway through DingTalk DEAP or other external services, you need to configure authentication and HTTP endpoints.

4.1 生成强认证令牌

4.1 Generate Strong Authentication Token

bash
openssl rand -hex 24
bash
openssl rand -hex 24

示例输出:a3f7c2e1d4b5a6c7d8e9f0a1b2c3d4e5f6a7b8c9d0e1f2a3

Example output: a3f7c2e1d4b5a6c7d8e9f0a1b2c3d4e5f6a7b8c9d0e1f2a3

undefined
undefined

4.2 更新 Gateway 配置

4.2 Update Gateway Configuration

编辑
~/.openclaw/openclaw.json
,添加
gateway
部分:
json
{
  "gateway": {
    "port": 18789,
    "mode": "local",
    "bind": "loopback",
    "controlUI": {
      "allowInsecureAuth": false
    },
    "auth": {
      "mode": "token",
      "token": "在此处填入上一步生成的强令牌"
    },
    "http": {
      "endpoints": {
        "chatCompletions": {
          "enabled": true
        }
      }
    }
  }
}
Edit
~/.openclaw/openclaw.json
, add the
gateway
section:
json
{
  "gateway": {
    "port": 18789,
    "mode": "local",
    "bind": "loopback",
    "controlUI": {
      "allowInsecureAuth": false
    },
    "auth": {
      "mode": "token",
      "token": "Fill in the strong token generated in the previous step here"
    },
    "http": {
      "endpoints": {
        "chatCompletions": {
          "enabled": true
        }
      }
    }
  }
}

4.3 重启 Gateway

4.3 Restart Gateway

bash
openclaw gateway restart
bash
openclaw gateway restart

或手动重启:

Or manual restart:

pkill -f "openclaw gateway" nohup setsid openclaw gateway --port 18789 --verbose > /tmp/openclaw-gateway.log 2>&1 &
undefined
pkill -f "openclaw gateway" nohup setsid openclaw gateway --port 18789 --verbose > /tmp/openclaw-gateway.log 2>&1 &
undefined

4.4 验证 Gateway 正常运行

4.4 Verify Gateway is Running Properly

bash
curl http://127.0.0.1:18789/health
bash
curl http://127.0.0.1:18789/health

应返回 {"status":"ok"} 或类似响应

Should return {"status":"ok"} or similar response


---

---

第五阶段:配置 ACP 协议支持

Phase 5: Configure ACP Protocol Support

ACP(Agent Client Protocol)协议允许 OpenClaw 调度多种 AI Agent。
ACP (Agent Client Protocol) allows OpenClaw to schedule multiple AI Agents.

5.1 安装并启用 ACPX 插件

5.1 Install and Enable ACPX Plugin

bash
undefined
bash
undefined

安装 ACPX 插件

Install ACPX plugin

openclaw plugins install @openclaw/acpx
openclaw plugins install @openclaw/acpx

启用插件

Enable plugin

openclaw config set plugins.entries.acpx.enabled true
undefined
openclaw config set plugins.entries.acpx.enabled true
undefined

5.2 配置 ACP 参数

5.2 Configure ACP Parameters

bash
undefined
bash
undefined

启用 ACP

Enable ACP

openclaw config set acp.enabled true
openclaw config set acp.enabled true

启用 ACP 调度

Enable ACP dispatch

openclaw config set acp.dispatch.enabled true
openclaw config set acp.dispatch.enabled true

设置后端为 acpx

Set backend to acpx

openclaw config set acp.backend "acpx"
openclaw config set acp.backend "acpx"

设置默认 Agent

Set default Agent

openclaw config set acp.defaultAgent "openclaw"
openclaw config set acp.defaultAgent "openclaw"

设置允许的 Agents

Set allowed Agents

openclaw config set acp.allowedAgents '["openclaw","claude","codex","opencode","gemini"]'
openclaw config set acp.allowedAgents '["openclaw","claude","codex","opencode","gemini"]'

设置最大并发会话数

Set maximum concurrent sessions

openclaw config set acp.maxConcurrentSessions 8
undefined
openclaw config set acp.maxConcurrentSessions 8
undefined

5.3 重启 Gateway 使配置生效

5.3 Restart Gateway for Configuration to Take Effect

bash
openclaw gateway restart
bash
openclaw gateway restart

5.4 验证 ACP 配置

5.4 Verify ACP Configuration

bash
openclaw config get acp --raw
bash
openclaw config get acp --raw

应输出:

Should output:

{

{

"enabled": true,

"enabled": true,

"dispatch": { "enabled": true },

"dispatch": { "enabled": true },

"backend": "acpx",

"backend": "acpx",

"defaultAgent": "openclaw",

"defaultAgent": "openclaw",

"allowedAgents": [...]

"allowedAgents": [...]

}

}


---

---

第六阶段:安装并配置 Qoder CLI(可选)

Phase 6: Install and Configure Qoder CLI (Optional)

如果你希望通过 Qoder 进行代码开发,可安装 Qoder CLI 并将其注册为 ACP Agent。
If you want to develop code through Qoder, you can install Qoder CLI and register it as an ACP Agent.

6.1 安装 Qoder CLI

6.1 Install Qoder CLI

bash
npm install -g @qoder-ai/qodercli
bash
npm install -g @qoder-ai/qodercli

验证安装

Verify installation

qodercli --version
undefined
qodercli --version
undefined

6.2 配置 Qoder CLI 认证

6.2 Configure Qoder CLI Authentication

方式一:环境变量(临时)
bash
export QODER_PERSONAL_ACCESS_TOKEN="your-api-key-here"
qodercli status  # 验证登录
方式二:持久化配置文件
bash
mkdir -p ~/.config/qoder
cat > ~/.config/qoder/config.json << 'EOF'
{
  "api_key": "your-api-key-here"
}
EOF
Method 1: Environment variable (temporary)
bash
export QODER_PERSONAL_ACCESS_TOKEN="your-api-key-here"
qodercli status  # Verify login
Method 2: Persistent configuration file
bash
mkdir -p ~/.config/qoder
cat > ~/.config/qoder/config.json << 'EOF'
{
  "api_key": "your-api-key-here"
}
EOF

6.3 配置 acpx 支持 Qoder

6.3 Configure acpx to Support Qoder

bash
mkdir -p ~/.acpx
cat > ~/.acpx/config.json << 'EOF'
{
  "agents": {
    "qoder": {
      "command": "env QODER_PERSONAL_ACCESS_TOKEN=your-api-key-here qodercli --acp"
    }
  },
  "defaultAgent": "qoder",
  "defaultPermissions": "approve-all"
}
EOF
bash
mkdir -p ~/.acpx
cat > ~/.acpx/config.json << 'EOF'
{
  "agents": {
    "qoder": {
      "command": "env QODER_PERSONAL_ACCESS_TOKEN=your-api-key-here qodercli --acp"
    }
  },
  "defaultAgent": "qoder",
  "defaultPermissions": "approve-all"
}
EOF

6.4 将 Qoder 注册到 ACP

6.4 Register Qoder to ACP

bash
undefined
bash
undefined

添加 qoder 到允许的 Agents 列表

Add qoder to allowed Agents list

openclaw config set acp.allowedAgents '["openclaw","qoder","claude","codex","opencode","gemini"]'
openclaw config set acp.allowedAgents '["openclaw","qoder","claude","codex","opencode","gemini"]'

可选:设置 qoder 为默认 Agent

Optional: Set qoder as default Agent

openclaw config set acp.defaultAgent "qoder"
openclaw config set acp.defaultAgent "qoder"

重启 Gateway

Restart Gateway

openclaw gateway restart
undefined
openclaw gateway restart
undefined

6.5 测试 Qoder CLI

6.5 Test Qoder CLI

bash
qodercli -p "hello" --max-turns 1
bash
qodercli -p "hello" --max-turns 1

若返回结果,说明 Qoder CLI 工作正常

If a result is returned, Qoder CLI is working properly


---

---

第七阶段:飞书 Bot 集成

Phase 7: Feishu Bot Integration

7.1 创建飞书企业自建应用

7.1 Create Feishu Enterprise Self-built Application

  1. 访问 飞书开放平台
  2. 点击「创建应用」→ 选择「企业自建」
  3. 填写应用名称(如「OpenClaw 助手」)和描述
  4. 立即记录 App ID 和 App Secret
  1. Visit Feishu Open Platform
  2. Click "Create Application" → Select "Enterprise Self-built"
  3. Fill in the application name (such as "OpenClaw Assistant") and description
  4. Record App ID and App Secret immediately

7.2 配置必需权限

7.2 Configure Required Permissions

进入应用「权限管理」,开启以下权限:
contact:user.base:readonly   获取用户基本信息
im:message                   读取消息
im:message:send_as_bot       发送消息(Bot 身份)
im:resource                  获取消息中的资源
确认 4 个权限全部激活。
Go to the application "Permission Management" and enable the following permissions:
contact:user.base:readonly   Get basic user information
im:message                   Read messages
im:message:send_as_bot       Send messages (as Bot)
im:resource                  Get resources in messages
Confirm all 4 permissions are activated.

7.3 启用机器人并配置事件订阅

7.3 Enable Bot and Configure Event Subscription

  1. 进入「应用能力」→ 添加「机器人」
  2. 事件订阅:选择「使用长连接接收事件」(WebSocket,无需公网 URL)
  3. 添加事件:
    im.message.receive_v1
    (接收消息事件)
  4. 保存并创建版本
  5. 发布应用(企业内部审批即可)
  1. Go to "Application Capabilities" → Add "Robot"
  2. Event subscription: Select "Use persistent connection to receive events" (WebSocket, no public URL required)
  3. Add event:
    im.message.receive_v1
    (message receiving event)
  4. Save and create a version
  5. Publish the application (only internal enterprise approval required)

7.4 配置 OpenClaw 接入飞书

7.4 Configure OpenClaw to Access Feishu

运行引导:
bash
openclaw onboard
按提示操作:
  1. 接受风险:
  2. 配置方式:快速开始
  3. 模型供应商:选择已配置的百炼
  4. 通道:选择飞书
  5. 输入凭证:App ID、App Secret(来自步骤 7.1)
  6. 启用技能:
  7. 选择钩子:session-memory
  8. 重启 Gateway:
Run the guide:
bash
openclaw onboard
Follow the prompts:
  1. Accept risk: Yes
  2. Configuration method: Quick Start
  3. Model provider: Select the configured Bailian
  4. Channel: Select Feishu
  5. Enter credentials: App ID, App Secret (from step 7.1)
  6. Enable skills: Yes
  7. Select hook: session-memory
  8. Restart Gateway: Yes

7.5 使用飞书机器人

7.5 Use Feishu Bot

  • 工作台:飞书 → 工作台 → 找到应用 → 开始聊天
  • 全局搜索:搜索应用名称直接进入
  • 群聊:将机器人加入群组 → @提及机器人交互

  • Workbench: Feishu → Workbench → Find the application → Start chatting
  • Global Search: Search for the application name to enter directly
  • Group Chat: Add the bot to the group → @mention the bot to interact

第八阶段:钉钉集成

Phase 8: DingTalk Integration

钉钉提供两种接入方案,根据需求选择:
方案复杂度特点
方案 A:传统机器人(Stream 模式)较低直接配置,无需额外组件
方案 B:DEAP Agent(高级)较高通过 Connector 隧道,功能更丰富

DingTalk provides two access solutions, choose according to your needs:
SolutionComplexityFeatures
Solution A: Traditional Bot (Stream Mode)LowDirect configuration, no additional components required
Solution B: DEAP Agent (Advanced)HighRicher functions through Connector tunnel

方案 A:钉钉机器人(Stream 模式)

Solution A: DingTalk Bot (Stream Mode)

A-1:安装钉钉插件

A-1: Install DingTalk Plugin

bash
openclaw plugins install https://github.com/soimy/openclaw-channel-dingtalk.git
bash
openclaw plugins install https://github.com/soimy/openclaw-channel-dingtalk.git

验证安装

Verify installation

openclaw plugins list
undefined
openclaw plugins list
undefined

A-2:在钉钉开放平台创建企业内部应用

A-2: Create Enterprise Internal Application on DingTalk Open Platform

  1. 访问 钉钉开放平台
  2. 使用企业管理员账号登录
  3. 点击「创建应用」→ 选择「企业内部应用」
  4. 填写应用信息(名称、描述、图标)
  5. 点击「确定创建」
  6. 在「凭证与基础信息」中记录 Client ID(AppKey)和 Client Secret(AppSecret)
⚠️ Client Secret 只显示一次,请立即妥善保存。
  1. Visit DingTalk Open Platform
  2. Log in with enterprise administrator account
  3. Click "Create Application" → Select "Enterprise Internal Application"
  4. Fill in application information (name, description, icon)
  5. Click "Confirm Creation"
  6. Record Client ID (AppKey) and Client Secret (AppSecret) in "Credentials and Basic Information"
⚠️ Client Secret is only displayed once, please save it properly immediately.

A-3:配置应用权限

A-3: Configure Application Permissions

进入「权限管理」,申请以下权限:
通讯录权限:
  • qyapi_get_member
    - 获取企业成员信息
  • qyapi_get_department_list
    - 获取部门列表
机器人权限:
  • chat:chat:readonly
    /
    chat:chat:write
  • im:chat:readonly
    /
    im:chat:write
    /
    im:chat:write:group
  • Card.Instance.Write
    /
    Card.Streaming.Write
  • qyapi_robot_sendmsg
点击「批量申请」,等待管理员审批通过。
Go to "Permission Management" and apply for the following permissions:
Address Book Permissions:
  • qyapi_get_member
    - Get enterprise member information
  • qyapi_get_department_list
    - Get department list
Bot Permissions:
  • chat:chat:readonly
    /
    chat:chat:write
  • im:chat:readonly
    /
    im:chat:write
    /
    im:chat:write:group
  • Card.Instance.Write
    /
    Card.Streaming.Write
  • qyapi_robot_sendmsg
Click "Batch Apply" and wait for administrator approval.

A-4:配置并发布机器人

A-4: Configure and Publish Bot

  1. 进入「机器人」页面 → 添加机器人 → 选择「自定义机器人」
  2. 消息接收模式:Stream 模式(WebSocket,无需公网 IP)
  3. 进入「版本管理与发布」→ 创建新版本(1.0.0)→ 申请发布
  1. Go to "Robot" page → Add Robot → Select "Custom Robot"
  2. Message receiving mode: Stream Mode (WebSocket, no public IP required)
  3. Go to "Version Management and Release" → Create new version (1.0.0) → Apply for release

A-5:配置 OpenClaw 连接钉钉

A-5: Configure OpenClaw to Connect to DingTalk

编辑
~/.openclaw/openclaw.json
,在
channels
中添加:
json
{
  "channels": {
    "dingtalk": {
      "enabled": true,
      "clientId": "你的_APPKEY",
      "clientSecret": "你的_APPSECRET",
      "robotCode": "你的_APPKEY",
      "corpId": "你的_CORPID",
      "agentId": "你的_AGENTID",
      "dmPolicy": "open",
      "groupPolicy": "open",
      "messageType": "markdown",
      "streamMode": true,
      "autoReply": true,
      "debug": false
    }
  }
}
或使用命令行配置:
bash
openclaw config set channels.dingtalk.enabled true
openclaw config set channels.dingtalk.clientId "YOUR_CLIENT_ID"
openclaw config set channels.dingtalk.clientSecret "YOUR_CLIENT_SECRET"
openclaw config set channels.dingtalk.sessionTimeout 1800000

openclaw gateway restart
Edit
~/.openclaw/openclaw.json
, add in
channels
:
json
{
  "channels": {
    "dingtalk": {
      "enabled": true,
      "clientId": "YOUR_APPKEY",
      "clientSecret": "YOUR_APPSECRET",
      "robotCode": "YOUR_APPKEY",
      "corpId": "YOUR_CORPID",
      "agentId": "YOUR_AGENTID",
      "dmPolicy": "open",
      "groupPolicy": "open",
      "messageType": "markdown",
      "streamMode": true,
      "autoReply": true,
      "debug": false
    }
  }
}
Or use command line configuration:
bash
openclaw config set channels.dingtalk.enabled true
openclaw config set channels.dingtalk.clientId "YOUR_CLIENT_ID"
openclaw config set channels.dingtalk.clientSecret "YOUR_CLIENT_SECRET"
openclaw config set channels.dingtalk.sessionTimeout 1800000

openclaw gateway restart

A-6:将机器人添加到群聊

A-6: Add Bot to Group Chat

  1. 打开目标钉钉群 → 群设置 → 智能群助手
  2. 添加机器人 → 企业内部机器人 → 找到你的机器人 → 添加
验证: 在群聊中发送
@OpenClaw 助手 你好
,机器人应回复。

  1. Open the target DingTalk group → Group Settings → Smart Group Assistant
  2. Add Robot → Enterprise Internal Robot → Find your robot → Add
Verification: Send
@OpenClaw Assistant Hello
in the group chat, the bot should reply.

方案 B:钉钉 DEAP Agent(高级方案)

Solution B: DingTalk DEAP Agent (Advanced Solution)

架构: 钉钉 App → DEAP 云端 → Connector 隧道 → 你的服务器 Gateway
Architecture: DingTalk App → DEAP Cloud → Connector Tunnel → Your Server Gateway

B-1:获取 DEAP 凭证

B-1: Obtain DEAP Credentials

  1. CorpId钉钉开放平台 → 企业信息
  2. DEAP API Key钉钉 DEAP 平台 → 安全与权限 → API-Key 管理 → 创建密钥
  1. CorpId: DingTalk Open Platform → Enterprise Information
  2. DEAP API Key: DingTalk DEAP Platform → Security and Permissions → API-Key Management → Create Key

B-2:在服务器上安装并运行 Connector

B-2: Install and Run Connector on Server

bash
undefined
bash
undefined

检查服务器架构

Check server architecture

uname -m # x86_64 或 aarch64
uname -m # x86_64 or aarch64

从以下地址下载对应版本:

Download the corresponding version from:

cd ~ wget [下载链接] -O connector.zip unzip -o connector.zip cd connector-linux-amd64 # 根据实际目录名调整 chmod +x connector-linux
cd ~ wget [download link] -O connector.zip unzip -o connector.zip cd connector-linux-amd64 # Adjust according to actual directory name chmod +x connector-linux

后台运行 Connector

Run Connector in background

nohup ./connector-linux
-deapCorpId 你的_CORPID
-deapApiKey 你的_DEAP_APIKEY \
/tmp/dingtalk-connector.log 2>&1 &
nohup ./connector-linux
-deapCorpId YOUR_CORPID
-deapApiKey YOUR_DEAP_APIKEY \
/tmp/dingtalk-connector.log 2>&1 &

验证运行状态

Verify running status

ps aux | grep connector tail -20 /tmp/dingtalk-connector.log
undefined
ps aux | grep connector tail -20 /tmp/dingtalk-connector.log
undefined

B-3:在 DEAP 平台创建 Agent

B-3: Create Agent on DEAP Platform

  1. 访问 钉钉 DEAP 平台
  2. 创建新 Agent
  3. 添加技能:搜索「OpenClaw」或「OpenClaw Gateway」
  4. 配置技能参数:
    • apikey:你的 DEAP API Key
    • apihost
      127.0.0.1:18789
    • gatewayToken:第四阶段配置的 Gateway 认证令牌
  5. 发布 Agent
  1. Visit DingTalk DEAP Platform
  2. Create new Agent
  3. Add skill: Search for "OpenClaw" or "OpenClaw Gateway"
  4. Configure skill parameters:
    • apikey: Your DEAP API Key
    • apihost:
      127.0.0.1:18789
    • gatewayToken: Gateway authentication token configured in Phase 4
  5. Publish Agent

B-4:在钉钉中使用 DEAP Agent

B-4: Use DEAP Agent in DingTalk

  • 在钉钉 App 中搜索 Agent 名称
  • 直接用自然语言发送任务,命令通过隧道在阿里云服务器上执行

  • Search for the Agent name in DingTalk App
  • Send tasks directly in natural language, commands are executed on Alibaba Cloud server through the tunnel

第九阶段:QQ Bot 集成

Phase 9: QQ Bot Integration

9.1 创建 QQ 机器人

9.1 Create QQ Bot

  1. 访问 QQ 开放平台
  2. 重要:需注册账号(非 QQ 账号直接登录)
  3. 登录 → 「机器人」→「创建机器人」
  4. 填写名称和描述
  5. 立即记录机器人 ID 和机器人密钥(关闭后无法再次查看)
  1. Visit QQ Open Platform
  2. Important: You need to register an account (cannot log in directly with QQ account)
  3. Log in → "Robot" → "Create Robot"
  4. Fill in name and description
  5. Record robot ID and robot secret immediately (cannot be viewed again after closing the page)

9.2 配置 IP 白名单

9.2 Configure IP Whitelist

  1. QQ 开放平台 → 机器人详情 → IP 白名单
  2. 将阿里云服务器的公网 IP 加入白名单
  1. QQ Open Platform → Bot Details → IP Whitelist
  2. Add the public IP of your Alibaba Cloud server to the whitelist

9.3 配置 OpenClaw

9.3 Configure OpenClaw

bash
openclaw onboard
选择 QQ 作为通道,输入:
  • 机器人 ID
  • 机器人密钥
完成剩余步骤(模型选择、技能、钩子)。

bash
openclaw onboard
Select QQ as the channel, enter:
  • Robot ID
  • Robot Secret
Complete the remaining steps (model selection, skills, hooks).

第十阶段:Discord Bot 集成

Phase 10: Discord Bot Integration

10.1 创建 Discord Bot

10.1 Create Discord Bot

  1. 访问 Discord Developer Portal
  2. 「New Application」→ 输入应用名称
  3. 进入「Bot」标签页
  4. 点击「Reset Token」→ 立即复制并保存 Bot Token
  5. 开启「Message Content Intent」(消息内容意图权限)
  1. Visit Discord Developer Portal
  2. "New Application" → Enter application name
  3. Go to "Bot" tab
  4. Click "Reset Token" → Copy and save Bot Token immediately
  5. Enable "Message Content Intent" (message content intent permission)

10.2 生成邀请链接并加入服务器

10.2 Generate Invite Link and Join Server

  1. 进入「OAuth2」→「URL Generator」
  2. Scope 选择:
    bot
  3. Bot Permissions 勾选:
    • Send Messages
    • Read Message History
  4. 复制生成的 URL,在浏览器中打开
  5. 选择你的 Discord 服务器 → 授权
  1. Go to "OAuth2" → "URL Generator"
  2. Scope select:
    bot
  3. Bot Permissions check:
    • Send Messages
    • Read Message History
  4. Copy the generated URL, open it in a browser
  5. Select your Discord server → Authorize

10.3 配置 OpenClaw

10.3 Configure OpenClaw

bash
openclaw onboard
选择 Discord 作为通道,输入 Bot Token(来自步骤 10.1)。
遗留说明:部分旧版文档使用
clawdbot
,请统一使用
openclaw

bash
openclaw onboard
Select Discord as the channel, enter Bot Token (from step 10.1).
Legacy Note: Some old documents use
clawdbot
, please use
openclaw
uniformly.

验证与使用示例

Verification and Usage Examples

全平台通用测试消息

General Test Messages for All Platforms

你现在用的是什么模型?
用三句话总结什么是 OpenClaw
创建一个工作日报模板
What model are you using now?
Summarize what OpenClaw is in three sentences
Create a work daily report template

检查 Gateway 状态

Check Gateway Status

bash
undefined
bash
undefined

查看 Gateway 运行日志

View Gateway running logs

tail -50 /tmp/openclaw-gateway.log
tail -50 /tmp/openclaw-gateway.log

查看所有渠道状态

View all channel status

openclaw channel list
openclaw channel list

查看 ACP 会话

View ACP sessions

openclaw sessions list
undefined
openclaw sessions list
undefined

钉钉使用示例

DingTalk Usage Examples

text
undefined
text
undefined

日常对话

Daily conversation

@OpenClaw 助手 你好,请介绍一下你自己
@OpenClaw Assistant Hello, please introduce yourself

代码需求

Code requirement

@OpenClaw 助手 帮我写一段 Python 爬虫代码,抓取网页标题
@OpenClaw Assistant Help me write a Python crawler code to grab web page titles

指定特定 Agent

Specify specific Agent

@OpenClaw 助手 /acp spawn claude 分析这段代码的 bug
@OpenClaw Assistant /acp spawn claude Analyze the bugs in this code

如果安装了 Qoder CLI

If Qoder CLI is installed

@OpenClaw 助手 用 qoder 开发一个 TODO 应用
@OpenClaw Assistant Use qoder to develop a TODO application

多轮对话

Multi-turn conversation

@OpenClaw 助手 我想开发一个个人博客(使用 Next.js 和 TypeScript)
undefined
@OpenClaw Assistant I want to develop a personal blog (using Next.js and TypeScript)
undefined

并行任务执行示例

Parallel Task Execution Example

一次发送多个任务以提升效率:
请处理以下任务:
1. 用三句话总结 OpenClaw
2. 创建一个包含 5 项的每周待办模板
3. 推荐一个提高效率的小技巧

Send multiple tasks at once to improve efficiency:
Please handle the following tasks:
1. Summarize OpenClaw in three sentences
2. Create a weekly to-do template with 5 items
3. Recommend a small tip to improve efficiency

高级配置

Advanced Configuration

配置多个 Agent

Configure Multiple Agents

bash
undefined
bash
undefined

设置允许的 Agents 列表

Set allowed Agents list

openclaw config set acp.allowedAgents '["openclaw","qoder","claude","codex","opencode","gemini"]'
openclaw config set acp.allowedAgents '["openclaw","qoder","claude","codex","opencode","gemini"]'

在聊天中使用特定 Agent

Use specific Agent in chat

/acp spawn codex --mode persistent 使用 Codex

/acp spawn codex --mode persistent Use Codex

/acp spawn claude --mode persistent 使用 Claude

/acp spawn claude --mode persistent Use Claude

/acp spawn qoder --mode persistent 使用 Qoder

/acp spawn qoder --mode persistent Use Qoder

undefined
undefined

配置持久化会话

Configure Persistent Sessions

bash
undefined
bash
undefined

启用会话绑定(同一话题持续使用同一 Agent)

Enable session binding (continue using the same Agent for the same topic)

openclaw config set session.threadBindings.enabled true openclaw config set session.threadBindings.ttlHours 24
openclaw gateway restart
undefined
openclaw config set session.threadBindings.enabled true openclaw config set session.threadBindings.ttlHours 24
openclaw gateway restart
undefined

配置安全策略

Configure Security Policy

bash
undefined
bash
undefined

设置执行权限级别

Set execution permission level

strict: 严格限制 moderate: 适度限制 approve-all: 全部批准

strict: Strict restriction moderate: Moderate restriction approve-all: Approve all

openclaw config set acp.permissions "strict"
openclaw config set acp.permissions "strict"

设置任务超时时间(秒)

Set task timeout (seconds)

openclaw config set acp.timeout 300
undefined
openclaw config set acp.timeout 300
undefined

配置消息回复模板

Configure Message Reply Template

新建
~/.openclaw/dingtalk-templates.json
json
{
  "welcome": "你好!我是 OpenClaw AI 助手,有什么可以帮助你的吗?",
  "error": "抱歉,处理您的请求时出现了错误,请稍后重试。",
  "thinking": "正在思考中...",
  "timeout": "处理超时,请简化您的问题后重试。"
}

Create
~/.openclaw/dingtalk-templates.json
:
json
{
  "welcome": "Hello! I am OpenClaw AI Assistant, how can I help you?",
  "error": "Sorry, an error occurred while processing your request, please try again later.",
  "thinking": "Thinking...",
  "timeout": "Processing timed out, please simplify your question and try again."
}

性能优化与运维

Performance Optimization and O&M

配置 systemd 系统服务(推荐生产环境)

Configure systemd System Service (Recommended for Production Environment)

bash
undefined
bash
undefined

增加系统文件描述符限制

Increase system file descriptor limit

echo "fs.file-max = 65535" >> /etc/sysctl.conf sysctl -p
echo "fs.file-max = 65535" >> /etc/sysctl.conf sysctl -p

创建 systemd 服务

Create systemd service

cat > /etc/systemd/system/openclaw.service << 'EOF' [Unit] Description=OpenClaw Gateway After=network.target
[Service] Type=simple User=root ExecStart=/root/.nvm/versions/node/v22.22.0/bin/openclaw gateway Restart=always RestartSec=5 Environment="PATH=/root/.nvm/versions/node/v22.22.0/bin:/usr/bin:/usr/local/bin"
[Install] WantedBy=multi-user.target EOF
systemctl daemon-reload systemctl enable openclaw systemctl start openclaw systemctl status openclaw
undefined
cat > /etc/systemd/system/openclaw.service << 'EOF' [Unit] Description=OpenClaw Gateway After=network.target
[Service] Type=simple User=root ExecStart=/root/.nvm/versions/node/v22.22.0/bin/openclaw gateway Restart=always RestartSec=5 Environment="PATH=/root/.nvm/versions/node/v22.22.0/bin:/usr/bin:/usr/local/bin"
[Install] WantedBy=multi-user.target EOF
systemctl daemon-reload systemctl enable openclaw systemctl start openclaw systemctl status openclaw
undefined

监控与日志管理

Monitoring and Log Management

bash
undefined
bash
undefined

实时查看 Gateway 日志

View Gateway logs in real time

tail -f /tmp/openclaw-gateway.log
tail -f /tmp/openclaw-gateway.log

查看 ACP 状态

View ACP status

openclaw acp status
openclaw acp status

查看所有会话

View all sessions

openclaw sessions list
openclaw sessions list

查看钉钉渠道指标

View DingTalk channel metrics

openclaw channel metrics dingtalk
openclaw channel metrics dingtalk

通过 systemd 查看日志

View logs via systemd

journalctl -u openclaw -f
undefined
journalctl -u openclaw -f
undefined

钉钉 DEAP Connector 守护进程

DingTalk DEAP Connector Daemon

bash
undefined
bash
undefined

配置 Connector 开机自启

Configure Connector to start on boot

cat > /etc/systemd/system/dingtalk-connector.service << 'EOF' [Unit] Description=DingTalk DEAP Connector After=network.target openclaw.service
[Service] Type=simple User=root WorkingDirectory=/root/connector-linux-amd64 ExecStart=/root/connector-linux-amd64/connector-linux
-deapCorpId YOUR_CORPID
-deapApiKey YOUR_DEAP_APIKEY Restart=always RestartSec=10
[Install] WantedBy=multi-user.target EOF
systemctl enable dingtalk-connector systemctl start dingtalk-connector

---
cat > /etc/systemd/system/dingtalk-connector.service << 'EOF' [Unit] Description=DingTalk DEAP Connector After=network.target openclaw.service
[Service] Type=simple User=root WorkingDirectory=/root/connector-linux-amd64 ExecStart=/root/connector-linux-amd64/connector-linux
-deapCorpId YOUR_CORPID
-deapApiKey YOUR_DEAP_APIKEY Restart=always RestartSec=10
[Install] WantedBy=multi-user.target EOF
systemctl enable dingtalk-connector systemctl start dingtalk-connector

---

常见问题排查

Common Problem Troubleshooting

故障速查表

Troubleshooting Cheat Sheet

现象可能原因解决方案
401 Unauthorized
Gateway Token 不匹配检查
openclaw.json
中的 token 与 DEAP/机器人配置一致
405 Method Not Allowed
HTTP 端点未启用确保
gateway.http.endpoints.chatCompletions.enabled: true
机器人完全无响应应用未发布 / 权限缺失检查应用发布状态和权限审批
DEAP Connector 断开防火墙 / 端口问题确保 18789 端口本地可访问,检查防火墙规则
机器人回复慢服务器资源不足检查 CPU/内存,查看 ACP 会话数
insufficient scope
钉钉权限未通过审批重新申请权限并等待审批
PhenomenonPossible CauseSolution
401 Unauthorized
Gateway Token mismatchCheck that the token in
openclaw.json
is consistent with DEAP/bot configuration
405 Method Not Allowed
HTTP endpoint not enabledEnsure
gateway.http.endpoints.chatCompletions.enabled: true
Bot does not respond at allApplication not published / missing permissionsCheck application publication status and permission approval
DEAP Connector disconnectedFirewall / port issueEnsure port 18789 is locally accessible, check firewall rules
Bot replies slowlyInsufficient server resourcesCheck CPU/memory, view ACP session count
insufficient scope
DingTalk permissions not approvedReapply for permissions and wait for approval

问题 1:Gateway 启动失败

Problem 1: Gateway Startup Failed

bash
undefined
bash
undefined

检查端口占用

Check port occupation

netstat -tlnp | grep 18789
netstat -tlnp | grep 18789

查看详细日志

View detailed logs

openclaw logs
openclaw logs

强制重启

Force restart

openclaw gateway restart --force
undefined
openclaw gateway restart --force
undefined

问题 2:钉钉机器人无响应

Problem 2: DingTalk Bot Does Not Respond

排查步骤:
  1. 确认应用已在「版本管理与发布」中正式发布(仅保存不够)
  2. 确认所有机器人权限已申请并审批通过
  3. 核对 Client ID 和 Client Secret 无误
  4. 查看连接器日志:
    openclaw logs dingtalk -f
  5. 确认 Stream 模式已启用
  6. 确认机器人已添加到目标群聊
Troubleshooting Steps:
  1. Confirm the application has been officially published in "Version Management and Release" (saving only is not enough)
  2. Confirm all bot permissions have been applied for and approved
  3. Verify that Client ID and Client Secret are correct
  4. View connector logs:
    openclaw logs dingtalk -f
  5. Confirm Stream mode is enabled
  6. Confirm the bot has been added to the target group chat

问题 3:无法将机器人添加到群聊

Problem 3: Cannot Add Bot to Group Chat

排查步骤:
  1. 确认你是群管理员或群主
  2. 确认应用已发布并通过管理员审批
  3. 在「机器人」页面确认机器人状态为「已启用」
Troubleshooting Steps:
  1. Confirm you are the group administrator or owner
  2. Confirm the application has been published and approved by the administrator
  3. Confirm the bot status is "Enabled" on the "Robot" page

问题 4:Stream 模式 / WebSocket 连接失败

Problem 4: Stream Mode / WebSocket Connection Failed

bash
undefined
bash
undefined

检查服务器是否能访问外部服务

Check if the server can access external services

ping oapi.dingtalk.com ping open.feishu.cn
ping oapi.dingtalk.com ping open.feishu.cn

检查防火墙是否阻止出站连接

Check if the firewall blocks outbound connections

尝试重启对应渠道连接器

Try restarting the corresponding channel connector

openclaw channel restart dingtalk
undefined
openclaw channel restart dingtalk
undefined

问题 5:机器人回复慢或中途超时

Problem 5: Bot Replies Slowly or Times Out Midway

bash
undefined
bash
undefined

检查服务器资源

Check server resources

top free -h
top free -h

查看 ACP 会话状态

View ACP session status

openclaw sessions list
openclaw sessions list

检查 OpenClaw 错误日志

Check OpenClaw error logs

openclaw logs --tail 200

---
openclaw logs --tail 200

---

快速参考卡

Quick Reference Card

平台关键凭证连接模式特殊要求
飞书App ID、App SecretWebSocket 长连接4 个权限,
im.message.receive_v1
事件
钉钉(传统机器人)AppKey、AppSecret、CorpId、AgentIdStream 模式
Card.Instance.Write
Card.Streaming.Write
权限
钉钉(DEAP)CorpId、DEAP API Key、Gateway TokenConnector 隧道Connector 需与 Gateway 在同一服务器
QQ机器人 ID、机器人密钥HTTP API服务器公网 IP 加入白名单
DiscordBot TokenWebSocket Gateway启用 Message Content Intent

PlatformKey CredentialsConnection ModeSpecial Requirements
FeishuApp ID, App SecretWebSocket persistent connection4 permissions,
im.message.receive_v1
event
DingTalk (Traditional Bot)AppKey, AppSecret, CorpId, AgentIdStream Mode
Card.Instance.Write
,
Card.Streaming.Write
permissions
DingTalk (DEAP)CorpId, DEAP API Key, Gateway TokenConnector tunnelConnector must be on the same server as Gateway
QQRobot ID, Robot SecretHTTP APIServer public IP added to whitelist
DiscordBot TokenWebSocket GatewayEnable Message Content Intent

环境变量参考

Environment Variable Reference

使用环境变量代替配置文件中的硬编码令牌(推荐):
bash
undefined
Use environment variables instead of hardcoded tokens in configuration files (recommended):
bash
undefined

添加到 ~/.bashrc 或 ~/.zshrc

Add to ~/.bashrc or ~/.zshrc

export OPENCLAW_GATEWAY_TOKEN="你的_gateway_token" export DINGTALK_CLIENT_SECRET="你的_dingtalk_secret" export FEISHU_APP_SECRET="你的_feishu_secret" export BAILIAN_API_KEY="sk-sp-YOUR_KEY_HERE" export QODER_PERSONAL_ACCESS_TOKEN="你的_qoder_api_key"

然后执行 `source ~/.bashrc` 使配置生效。部分 OpenClaw 版本支持在 `openclaw.json` 中使用 `$ENV_VAR` 语法引用环境变量。

---
export OPENCLAW_GATEWAY_TOKEN="your_gateway_token" export DINGTALK_CLIENT_SECRET="your_dingtalk_secret" export FEISHU_APP_SECRET="your_feishu_secret" export BAILIAN_API_KEY="sk-sp-YOUR_KEY_HERE" export QODER_PERSONAL_ACCESS_TOKEN="your_qoder_api_key"

Then execute `source ~/.bashrc` for the configuration to take effect. Some versions of OpenClaw support using `$ENV_VAR` syntax in `openclaw.json` to reference environment variables.

---

日常维护命令

Daily Maintenance Commands

重启 Gateway:
bash
systemctl restart openclaw
Restart Gateway:
bash
systemctl restart openclaw

或手动方式:

Or manual method:

pkill -f "openclaw gateway" && nohup setsid openclaw gateway --port 18789 --verbose > /tmp/openclaw-gateway.log 2>&1 &

**更新 OpenClaw:**
```bash
openclaw update
pkill -f "openclaw gateway" && nohup setsid openclaw gateway --port 18789 --verbose > /tmp/openclaw-gateway.log 2>&1 &

**Update OpenClaw:**
```bash
openclaw update

或重新运行安装脚本:

Or re-run the installation script:


**管理插件:**
```bash
openclaw plugins list
openclaw plugins update [插件名]
openclaw plugins install [插件名或 Git URL]
查看运行日志:
bash
undefined

**Manage Plugins:**
```bash
openclaw plugins list
openclaw plugins update [plugin name]
openclaw plugins install [plugin name or Git URL]
View Running Logs:
bash
undefined

Gateway 主日志

Gateway main log

tail -f /tmp/openclaw-gateway.log
tail -f /tmp/openclaw-gateway.log

钉钉 DEAP Connector 日志

DingTalk DEAP Connector log

tail -f /tmp/dingtalk-connector.log
tail -f /tmp/dingtalk-connector.log

特定渠道日志

Specific channel logs

openclaw logs dingtalk -f openclaw logs feishu -f

**故障排查入口:**
```bash
openclaw gateway status        # Gateway 状态
openclaw channel list          # 所有渠道状态
openclaw sessions list         # ACP 会话列表
openclaw channel status dingtalk   # 特定渠道状态

openclaw logs dingtalk -f openclaw logs feishu -f

**Troubleshooting Entry:**
```bash
openclaw gateway status        # Gateway status
openclaw channel list          # All channel status
openclaw sessions list         # ACP session list
openclaw channel status dingtalk   # Specific channel status

参考资料

References