alicloud-platform-openclaw-setup

OpenClaw 设置

在 Linux 上部署 OpenClaw，启用钉钉、飞书、Discord 或其他有文档说明的渠道，并验证网关健康状况。

使用此工作流

按顺序执行以下步骤：

1. 准备 Linux 运行环境并安装 OpenClaw。
2. 从官方文档中发现渠道（新渠道请求必须执行）。
3. 安装并验证渠道集成。
4. 创建/合并 ~/.openclaw/openclaw.json。
5. 配置并启动网关服务。
6. 运行健康检查并收集日志。

前置条件

• 可通过 SSH 访问目标 Linux 主机（优先使用 Debian/Ubuntu）。
• 钉钉企业应用凭据（官方连接器需要 AppKey、AppSecret），或飞书应用凭据（App ID、App Secret），或 Discord 机器人令牌。
• DashScope API 密钥。

第 1 步：准备运行环境

ssh root@<server>
curl -fsSL https://deb.nodesource.com/setup_20.x | bash -
apt-get install -y nodejs
node --version
npm --version

第 2 步：安装 OpenClaw 和渠道集成

npm install -g openclaw@latest
openclaw --version

# DingTalk official connector
openclaw plugins install @dingtalk-real-ai/dingtalk-connector --pin
# or install from official GitHub repo
openclaw plugins install https://github.com/DingTalk-Real-AI/dingtalk-openclaw-connector.git
openclaw plugins list | grep dingtalk

# Feishu channel
openclaw plugins install @openclaw/feishu
openclaw plugins list | grep feishu

# Discord channel (built-in, no extra plugin needed)
# Configure token in Step 3 and start gateway in Step 4

如果要从旧版钉钉插件升级，请先卸载旧插件 ID，并且在 plugins.allow 中仅保留官方连接器。

第 3 步：从官方文档自动发现其他渠道

当用户要求添加当前设置之外的渠道时，先执行以下操作：

1. 打开 https://docs.openclaw.ai/channels/index。
2. 从“Supported channels”列表中找到用户请求的渠道页面。
3. 打开每个渠道页面并提取以下信息：
   • 是内置渠道还是基于插件的渠道。
   • 准确的安装命令（不要猜测软件包名称）。
   • 所需凭据/令牌和配置键。
4. 在主机上应用安装/配置。
5. 将渠道专属说明记录到 ~/.openclaw/openclaw.json。

使用 references/channel-discovery.md 中的准确工作流。

第 4 步：配置 openclaw.json

创建或更新 ~/.openclaw/openclaw.json，包含以下内容：

• models.providers.bailian：DashScope 端点和模型。
• agents.defaults.model.primary：采用 provider/model 格式，默认值为 bailian/glm-5。
• models.providers.bailian.models：按以下顺序排列：
  1. qwen3-plus
  2. glm-5
  3. minimax-m2.5
  4. kimi-k2.5
• agents.defaults.model.fallbacks：按以下顺序排列：
  1. bailian/qwen3-plus
  2. bailian/minimax-m2.5
  3. bailian/kimi-k2.5
• channels.dingtalk-connector、channels.feishu 或 channels.discord 的凭据和策略。
• plugins.allow：包含已安装的渠道插件。

重要事项：

• ~/.openclaw/agents/main/agent/models.json 中的 Agent 级模型配置可能会覆盖 ~/.openclaw/openclaw.json。
• 如果默认设置似乎未生效，请确保两个文件中的提供方定义一致。
• 协议必须与端点匹配：
  • api: openai-completions -> 使用 https://dashscope.aliyuncs.com/compatible-mode/v1
  • api: openai-responses -> 使用 https://dashscope.aliyuncs.com/api/v2/apps/protocols/compatible-mode/v1

使用 references/config.md 中的完整模板。 使用 references/dingtalk-setup.md 中的钉钉字段映射。 使用 references/feishu-setup.md 中的飞书设置和字段映射。 使用 references/discord-setup.md 中的 Discord 设置和字段映射。 使用 references/channel-discovery.md 中的渠道发现工作流。

第 5 步：安装并启动网关

openclaw gateway install
openclaw gateway start
openclaw gateway status

如果通过用户级 systemd 运行，在配置更改后重新加载：

systemctl --user import-environment DASHSCOPE_API_KEY
systemctl --user daemon-reload
systemctl --user restart openclaw-gateway

第 6 步：验证与故障排查

openclaw doctor
openclaw gateway status
openclaw gateway logs -f

常见故障：

• 插件未加载：重新安装插件，并检查 plugins.allow。
• 未知模型：检查 agents.defaults.model.primary 的格式（provider/model-id）。
• API 密钥错误：检查 systemd 中的 models.providers.bailian.apiKey 和 DASHSCOPE_API_KEY 是否已导入。
• 配置已更改，但运行时模型未变：检查并更新 ~/.openclaw/agents/main/agent/models.json。
• 载荷为空／意外回退：验证协议与端点的组合（openai-completions 与 openai-responses），并在需要时清除过期会话。
• DingTalk 无响应：使用 openclaw logs --follow，并检查 gateway/channels/dingtalk-connector 日志行中是否有流重连或凭据问题。
• 已安装官方连接器，但旧探测结果不一致：以运行时日志和真实消息收发为准。
• Feishu 无响应：检查事件订阅模式是否为 WebSocket，以及网关是否正在运行。
• Discord 无响应：验证机器人意图、令牌和首次私信配对审批。

安全说明

• 不要在仓库文件中硬编码真实密钥。
• 将生产密钥保存在服务器本地配置或密钥管理器中。
• 在工单或聊天中分享日志前，请先对日志内容进行脱敏。

验证

mkdir -p output/alicloud-platform-openclaw-setup
echo "validation_placeholder" > output/alicloud-platform-openclaw-setup/validate.txt

通过标准：命令以 0 退出，且已生成 output/alicloud-platform-openclaw-setup/validate.txt。

输出与证据

• 将构件、命令输出和 API 响应摘要保存在 output/alicloud-platform-openclaw-setup/ 下。
• 在证据文件中包含关键参数（区域／资源 ID／时间范围），以确保可复现。

工作流

1. 确认用户意图、区域、标识符，以及操作是只读还是会修改数据。
2. 先运行一个最精简的只读查询，以验证连接和权限。
3. 使用明确的参数和有限的范围执行目标操作。
4. 验证结果并保存输出／证据文件。