openclaw-guide

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

OpenClaw Guide

OpenClaw 指南

OpenClaw is a messaging gateway that connects AI agents to 24+ communication platforms. This skill is the reference for everything after the bot is installed — channels, use cases, memory, cron, MCP, OAuth, troubleshooting.

Current production version assumed: 2026.5.x (latest 2026.4.x is also fully covered). Official docs: https://docs.openclaw.ai/ · Source: https://github.com/openclaw/openclaw

OpenClaw是一款可将AI agents连接至24+个通讯平台的消息网关。本技能是机器人安装完成后所有操作的参考手册——涵盖通道、用例、内存、定时任务（cron）、MCP、OAuth、故障排查等内容。

**当前假定生产版本：**2026.5.x（最新的2026.4.x版本也完全适用）。 **官方文档：**https://docs.openclaw.ai/ · **源码：**https://github.com/openclaw/openclaw

Setup (install OpenClaw first)

配置（先安装OpenClaw）

This skill is consultation-only. If the user doesn't have an OpenClaw bot yet, install both skills together and run the companion wizard:

bash

npx skills add CodeAlive-AI/ceo-ai-os@install-openclaw-to-yc -g
npx skills add CodeAlive-AI/ceo-ai-os@openclaw-guide -g

Then tell the agent: "install OpenClaw on Yandex Cloud Kazakhstan". The

install-openclaw-to-yc

skill takes over and uses this one for any post-install consultation.

For other hosts (local Mac, GCP, AWS, bare metal) the OpenClaw upstream documentation at https://docs.openclaw.ai/start/getting-started is the canonical guide — no CEO AI OS wizard exists for them yet.

本技能仅提供咨询服务。如果用户尚未拥有OpenClaw机器人，请同时安装以下两个技能并运行配套向导：

bash

npx skills add CodeAlive-AI/ceo-ai-os@install-openclaw-to-yc -g
npx skills add CodeAlive-AI/ceo-ai-os@openclaw-guide -g

然后告知代理：“在Yandex Cloud哈萨克斯坦节点安装OpenClaw”。

install-openclaw-to-yc

技能将接管安装流程，并在安装完成后通过本技能提供后续咨询服务。

对于其他主机（本地Mac、GCP、AWS、裸金属服务器），请参考OpenClaw官方上游文档https://docs.openclaw.ai/start/getting-started——目前暂无CEO AI OS向导支持这些环境。

How to read this skill

如何使用本技能

The full content is split across nine reference files. Read only the one that matches the user's current question — bringing all of them into context wastes the budget.

If the user asks about…	Read
Agent runtime, bootstrap files, sessions, message flow, chat commands, skills	`references/01-architecture.md`
MEMORY.md, daily notes, dreaming, memory backends, embedding providers, sync safety	`references/02-memory.md`
Cron jobs (add / list / rm), heartbeat, scheduled tasks, timezones, delivery flags	`references/03-cron-heartbeat.md`
MCP servers (Exa, PostHog, Grafana, …), `openclaw mcp set` , transports, tool naming	`references/04-mcp.md`
`openclaw.json` schema, key CLI commands, paths, auth modes, exec approvals, systemd units	`references/05-config-and-cli.md`
OAuth re-auth ( `models auth login` bugs, orphan profiles), server-side debugging, channel caveats	`references/06-troubleshooting.md`
Use cases — morning brief, research workflows, competitive radar, decision playbook, email handler, meeting prep	`references/use-cases.md`
Channels — Telegram details, adding Discord / Slack / WhatsApp / iMessage	`references/channels.md`
CodeAlive search inside the bot — `semantic_search` , `grep_search` , `chat` over indexed repos	`references/codealive-context-engine.md`

完整内容分为九个参考文件。请仅阅读与用户当前问题匹配的文件——加载全部文件会浪费预算。

用户咨询内容…	阅读对应文件
Agent运行时、引导文件、会话、消息流、聊天命令、技能	`references/01-architecture.md`
MEMORY.md、每日笔记、梦境模式、内存后端、嵌入提供商、同步安全性	`references/02-memory.md`
定时任务（添加/列出/删除）、心跳、调度任务、时区、投递标记	`references/03-cron-heartbeat.md`
MCP服务器（Exa、PostHog、Grafana等）、 `openclaw mcp set` 、传输方式、工具命名	`references/04-mcp.md`
`openclaw.json` schema、核心CLI命令、路径、认证模式、执行审批、systemd单元	`references/05-config-and-cli.md`
OAuth重新授权（ `models auth login` 错误、孤立配置文件）、服务端调试、通道注意事项	`references/06-troubleshooting.md`
用例——早报、研究工作流、竞争雷达、决策手册、邮件处理、会议准备	`references/use-cases.md`
通道——Telegram详情、添加Discord/Slack/WhatsApp/iMessage	`references/channels.md`
机器人内置CodeAlive搜索—— `semantic_search` 、 `grep_search` 、基于索引仓库的 `chat`	`references/codealive-context-engine.md`

Critical pitfalls (always cross-check before infrastructure changes)

关键陷阱（基础设施变更前务必交叉检查）

These are the recurring footguns. Read this table before any planned restart, OAuth re-auth, cron edit, or schema change.

#	Title	When it bites
1	Isolated cron sessions can't deliver to Telegram	Use `--session main` or `session:cron-<name>` , not `isolated`
2	Telegram adapter silently dies after ~12h	Watchdog timer restarts gateway on outbound errors
6	Gateway auth handshake timeout on small VMs	`gateway.auth.mode: none` is safe on loopback
7	Bootstrap file truncation drops the middle	Keep individual files compact; truncation = 70% head + 20% tail
14	`cron add` syntax — `--message` (not positional), `--name` (no `--id` ), `cron rm` (no `delete` )	All cron CLI work
18	Cron jobs without explicit `--timeout-seconds` use 600s default	Always set explicitly
19	Exec approval blocked when no Telegram approver	`tools.exec.security: full` + `ask: off` on headless server
20	`openclaw-monitor.timer` kills gateway during slow startup	Stop timer → restart → wait `/health=200` → start timer
21	`models auth login` clobbers other providers + schema gotcha	Backup config first; correct path is `agents.defaults.models` , NOT `models.configuredModels`
22	`composio` CLI fails with EACCES posix_spawn from `gcloud ssh`	Run `cd /tmp` first or invoke as root
23	OAuth re-auth leaves orphan profiles	Decode `access` JWT, compare `chatgpt_account_id` , prune duplicates

Full numbered list with workarounds lives in the CEO AI OS workspace repo at

OPENCLAW_PITFALLS.md

. When a new pitfall surfaces, add it there — single source of truth.

以下是常见的易踩坑点。在计划重启、OAuth重新授权、定时任务编辑或schema变更前，请阅读本表。

#	标题	触发场景
1	孤立定时任务会话无法向Telegram投递消息	使用 `--session main` 或 `session:cron-<name>` ，而非 `isolated`
2	Telegram适配器约12小时后会静默崩溃	启用看门狗定时器，在出站错误时重启网关
6	小型VM上网关认证握手超时	在环回接口上设置 `gateway.auth.mode: none` 是安全的
7	引导文件截断会丢失中间内容	保持单个文件精简；截断规则为保留70%头部+20%尾部
14	`cron add` 语法——使用 `--message` （非位置参数）、 `--name` （不使用 `--id` ），删除用 `cron rm` （不使用 `delete` ）	所有定时任务CLI操作
18	未显式设置 `--timeout-seconds` 的定时任务默认超时时间为600秒	务必显式设置超时时间
19	无Telegram审批人时执行审批被阻止	在无头服务器上设置 `tools.exec.security: full` + `ask: off`
20	`openclaw-monitor.timer` 在网关启动缓慢时会终止进程	先停止定时器→重启网关→等待 `/health=200` →再启动定时器
21	`models auth login` 会覆盖其他提供商配置+schema陷阱	先备份配置；正确路径为 `agents.defaults.models` ，而非 `models.configuredModels`
22	从 `gcloud ssh` 执行 `composio` CLI时因EACCES posix_spawn失败	先执行 `cd /tmp` 或以root身份调用
23	OAuth重新授权会留下孤立配置文件	解码 `access` JWT，对比 `chatgpt_account_id` ，清理重复项

完整带解决方案的编号列表可在CEO AI OS工作区仓库的

OPENCLAW_PITFALLS.md

中查看。当发现新的陷阱时，请添加至该文件——作为唯一可信来源。

Upstream documentation index (quick links)

上游文档索引（快速链接）

These are direct URLs into docs.openclaw.ai for occasions when this skill's references don't cover a feature. Prefer this skill's references first — they're tuned for the workshop / personal CEO bot context.

当本技能的参考文件未覆盖某功能时，可直接访问docs.openclaw.ai的以下链接。优先使用本技能的参考文件——它们针对工作坊/个人CEO机器人场景进行了优化。

Getting started

入门指南

Topic	URL
Getting Started	https://docs.openclaw.ai/start/getting-started
Onboarding Wizard	https://docs.openclaw.ai/start/wizard
Documentation Hub	https://docs.openclaw.ai/start/hubs
DM/Node Pairing	https://docs.openclaw.ai/start/pairing

主题	URL
快速入门	https://docs.openclaw.ai/start/getting-started
入职向导	https://docs.openclaw.ai/start/wizard
文档中心	https://docs.openclaw.ai/start/hubs
DM/节点配对	https://docs.openclaw.ai/start/pairing

Gateway & configuration

网关与配置

Topic	URL
Gateway Runbook	https://docs.openclaw.ai/gateway
Configuration	https://docs.openclaw.ai/gateway/configuration
Authentication	https://docs.openclaw.ai/gateway/authentication
Sandboxing	https://docs.openclaw.ai/gateway/sandboxing
Security	https://docs.openclaw.ai/gateway/security
Troubleshooting	https://docs.openclaw.ai/gateway/troubleshooting

主题	URL
网关运行手册	https://docs.openclaw.ai/gateway
配置	https://docs.openclaw.ai/gateway/configuration
认证	https://docs.openclaw.ai/gateway/authentication
沙箱	https://docs.openclaw.ai/gateway/sandboxing
安全	https://docs.openclaw.ai/gateway/security
故障排查	https://docs.openclaw.ai/gateway/troubleshooting

Channels

通道

Topic	URL
Telegram	https://docs.openclaw.ai/channels/telegram
WhatsApp	https://docs.openclaw.ai/channels/whatsapp
Discord	https://docs.openclaw.ai/channels/discord
Slack	https://docs.openclaw.ai/channels/slack
iMessage	https://docs.openclaw.ai/channels/imessage
Matrix	https://docs.openclaw.ai/channels/matrix
Mattermost	https://docs.openclaw.ai/channels/mattermost
Groups	https://docs.openclaw.ai/channels/groups

主题	URL
Telegram	https://docs.openclaw.ai/channels/telegram
WhatsApp	https://docs.openclaw.ai/channels/whatsapp
Discord	https://docs.openclaw.ai/channels/discord
Slack	https://docs.openclaw.ai/channels/slack
iMessage	https://docs.openclaw.ai/channels/imessage
Matrix	https://docs.openclaw.ai/channels/matrix
Mattermost	https://docs.openclaw.ai/channels/mattermost
群组	https://docs.openclaw.ai/channels/groups

Core concepts

核心概念

Topic	URL
Agent	https://docs.openclaw.ai/concepts/agent
Agent Workspace	https://docs.openclaw.ai/concepts/agent-workspace
Memory	https://docs.openclaw.ai/concepts/memory
Sessions	https://docs.openclaw.ai/concepts/session
Compaction	https://docs.openclaw.ai/concepts/compaction
Models	https://docs.openclaw.ai/concepts/models

主题	URL
Agent	https://docs.openclaw.ai/concepts/agent
Agent工作区	https://docs.openclaw.ai/concepts/agent-workspace
内存	https://docs.openclaw.ai/concepts/memory
会话	https://docs.openclaw.ai/concepts/session
压缩	https://docs.openclaw.ai/concepts/compaction
模型	https://docs.openclaw.ai/concepts/models

Tools, automation, install

工具、自动化、安装

Topic	URL
Skills	https://docs.openclaw.ai/tools/skills
Plugin System	https://docs.openclaw.ai/tools/plugin
Cron Jobs	https://docs.openclaw.ai/automation/cron-jobs
Hooks	https://docs.openclaw.ai/automation/hooks
Webhooks	https://docs.openclaw.ai/automation/webhook
Docker install	https://docs.openclaw.ai/install/docker
CLI Reference	https://docs.openclaw.ai/cli

主题	URL
Skills	https://docs.openclaw.ai/tools/skills
插件系统	https://docs.openclaw.ai/tools/plugin
定时任务	https://docs.openclaw.ai/automation/cron-jobs
钩子	https://docs.openclaw.ai/automation/hooks
Webhooks	https://docs.openclaw.ai/automation/webhook
Docker安装	https://docs.openclaw.ai/install/docker
CLI参考	https://docs.openclaw.ai/cli

Companion skill (required at install time)

配套技能（安装时必需）

install-openclaw-to-yc

(sibling) — the wizard that creates the VM, installs OpenClaw, and seeds the workspace. Install it alongside this skill:

bash

npx skills add CodeAlive-AI/ceo-ai-os@install-openclaw-to-yc -g

The two skills cross-reference:

install-openclaw-to-yc

runs the bootstrap and hands off to this guide for everything after. This guide assumes the bot is already up and walks the user through configuration, channels, use cases, and operations.

install-openclaw-to-yc

（姊妹技能）——用于创建VM、安装OpenClaw并初始化工作区的向导。请与本技能一同安装：

bash

npx skills add CodeAlive-AI/ceo-ai-os@install-openclaw-to-yc -g

两个技能相互关联：

install-openclaw-to-yc

负责引导安装流程，之后将所有后续操作移交至本指南。本指南假定机器人已启动运行，将引导用户完成配置、通道、用例和运维操作。