openclaw-config

OpenClaw 運用ランブック

実際の問題を診断して修正します。ここに記載されているコマンドはすべてテスト済みで、動作します。

---

クイックヘルスチェック

何か問題があるように見えたら、まずこれを実行してください。ブロック全体をコピーして貼り付けます。

echo "=== GATEWAY ===" && \
ps aux | grep -c "[o]penclaw" && \
echo "=== CONFIG JSON ===" && \
python3 -m json.tool ~/.openclaw/openclaw.json > /dev/null 2>&1 && echo "JSON: OK" || echo "JSON: BROKEN" && \
echo "=== CHANNELS ===" && \
cat ~/.openclaw/openclaw.json | jq -r '.channels | to_entries[] | "\(.key): policy=\(.value.dmPolicy // "n/a") enabled=\(.value.enabled // "implicit")"' && \
echo "=== PLUGINS ===" && \
cat ~/.openclaw/openclaw.json | jq -r '.plugins.entries | to_entries[] | "\(.key): \(.value.enabled)"' && \
echo "=== CREDS ===" && \
ls ~/.openclaw/credentials/whatsapp/default/ 2>/dev/null | wc -l | xargs -I{} echo "WhatsApp keys: {} files" && \
for d in ~/.openclaw/credentials/telegram/*/; do bot=$(basename "$d"); [ -f "$d/token.txt" ] && echo "Telegram $bot: OK" || echo "Telegram $bot: MISSING"; done && \
[ -f ~/.openclaw/credentials/bird/cookies.json ] && echo "Bird cookies: OK" || echo "Bird cookies: MISSING" && \
echo "=== CRON ===" && \
cat ~/.openclaw/cron/jobs.json | jq -r '.jobs[] | "\(.name): enabled=\(.enabled) status=\(.state.lastStatus // "never") \(.state.lastError // "")"' && \
echo "=== RECENT ERRORS ===" && \
tail -10 ~/.openclaw/logs/gateway.err.log 2>/dev/null && \
echo "=== MEMORY DB ===" && \
sqlite3 ~/.openclaw/memory/main.sqlite "SELECT COUNT(*) || ' chunks, ' || (SELECT COUNT(*) FROM files) || ' files indexed' FROM chunks;" 2>/dev/null

---

ファイル一覧

~/.openclaw/
├── openclaw.json                    # MAIN CONFIG — channels, auth, gateway, plugins, skills
├── openclaw.json.bak*               # Auto-backups (.bak, .bak.1, .bak.2 ...)
├── exec-approvals.json              # Exec approval socket config
│
├── agents/main/
│   ├── agent/auth-profiles.json     # Anthropic auth tokens
│   └── sessions/
│       ├── sessions.json            # SESSION INDEX — keys are like agent:main:whatsapp:+1234
│       └── *.jsonl                  # Session transcripts (one JSON per line)
│
├── workspace/                       # Agent workspace (git-tracked)
│   ├── SOUL.md                      # Personality, writing style, tone rules
│   ├── IDENTITY.md                  # Name, creature type, vibe
│   ├── USER.md                      # Owner context and preferences
│   ├── AGENTS.md                    # Session behavior, memory rules, safety
│   ├── BOOT.md                      # Boot instructions (autopilot notification protocol)
│   ├── HEARTBEAT.md                 # Periodic task checklist (empty = skip heartbeat)
│   ├── MEMORY.md                    # Curated long-term memory (main session only)
│   ├── TOOLS.md                     # Contacts, SSH hosts, device nicknames
│   ├── memory/                      # Daily logs: YYYY-MM-DD.md, topic-chat.md
│   └── skills/                      # Workspace-level skills
│
├── memory/main.sqlite               # Vector memory DB (Gemini embeddings, FTS5 search)
│
├── logs/
│   ├── gateway.log                  # Runtime: startup, channel init, config reload, shutdown
│   ├── gateway.err.log              # Errors: connection drops, API failures, timeouts
│   └── commands.log                 # Command execution log
│
├── cron/
│   ├── jobs.json                    # Job definitions (schedule, payload, delivery target)
│   └── runs/                        # Per-job run logs: {job-uuid}.jsonl
│
├── credentials/
│   ├── whatsapp/default/            # Baileys session: ~1400 app-state-sync-key-*.json files
│   ├── telegram/{botname}/token.txt # Bot tokens (one per bot account)
│   └── bird/cookies.json            # X/Twitter auth cookies
│
├── extensions/{name}/               # Custom plugins (TypeScript)
│   ├── openclaw.plugin.json         # {"id", "channels", "configSchema"}
│   ├── index.ts                     # Entry point
│   └── src/                         # channel.ts, actions.ts, runtime.ts, types.ts
│
├── identity/                        # device.json, device-auth.json
├── devices/                         # paired.json, pending.json
├── media/inbound/                   # Received images, audio files
├── media/browser/                   # Browser screenshots
├── browser/openclaw/user-data/      # Chromium profile (~180MB)
├── tools/signal-cli/                # Signal CLI binary
├── subagents/runs.json              # Sub-agent execution log
├── canvas/index.html                # Web canvas UI
└── telegram/
    ├── update-offset-coder.json     # {"lastUpdateId": N} — Telegram polling cursor
    └── update-offset-sales.json     # Reset these to 0 to replay missed messages

---

トラブルシューティング：WhatsApp

「メッセージを送ったのに返信がない」

最もよくある問題です。メッセージは届くのに、ボットが応答しません。次の順に確認してください。

# 1. Is the bot actually running?
grep -i "whatsapp.*starting\|whatsapp.*listening" ~/.openclaw/logs/gateway.log | tail -5

# 2. Check for 408 timeout drops (WhatsApp web disconnects frequently)
grep -i "408\|499\|retry" ~/.openclaw/logs/gateway.err.log | tail -10
# If you see "Web connection closed (status 408). Retry 1/12" — this is normal,
# it auto-recovers. But if retries reach 12/12, the session dropped completely.

# 3. Check for cross-context messaging blocks
grep -i "cross-context.*denied" ~/.openclaw/logs/gateway.err.log | tail -10
# Common: "Cross-context messaging denied: action=send target provider "whatsapp" while bound to "signal""
# This means the agent was in a Signal session and tried to reply on WhatsApp.
# FIX: The message needs to come through in the WhatsApp session context, not Signal.

# 4. Check the session exists for that contact
cat ~/.openclaw/agents/main/sessions/sessions.json | jq -r 'to_entries[] | select(.key | test("whatsapp")) | "\(.key) | \(.value.origin.label // "?")"'

# 5. Check if the sender is allowed
cat ~/.openclaw/openclaw.json | jq '.channels.whatsapp | {dmPolicy, allowFrom, selfChatMode, groupPolicy}'
# If dmPolicy is "allowlist" and the sender isn't in allowFrom, message is silently dropped.

# 6. Check if it's a group message (groups are disabled by default)
cat ~/.openclaw/openclaw.json | jq '.channels.whatsapp.groupPolicy'
# "disabled" means ALL group messages are ignored.

# 7. Check for lane congestion (agent busy with another task)
grep "lane wait exceeded" ~/.openclaw/logs/gateway.err.log | tail -5
# If the agent is stuck on a long LLM call, new messages queue up.

# 8. Check for agent run timeout
grep "embedded run timeout" ~/.openclaw/logs/gateway.err.log | tail -5
# Hard limit is 600s (10 min). If the agent's response takes longer, it's killed.

「WhatsApp が完全に切断された」

# Check credential files exist (should be ~1400 files)
ls ~/.openclaw/credentials/whatsapp/default/ | wc -l

# If 0 files: session was never created or got wiped
# Fix: re-pair with `openclaw configure`

# Check for QR/pairing events
grep -i "pair\|link\|qr\|scan\|logged out" ~/.openclaw/logs/gateway.log | tail -10

# Check for Baileys errors
grep -i "baileys\|DisconnectReason\|logout\|stream:error" ~/.openclaw/logs/gateway.err.log | tail -20

# Nuclear fix: delete credentials and re-pair
# rm -rf ~/.openclaw/credentials/whatsapp/default/
# openclaw configure

---

トラブルシューティング：Telegram

「ボットに問題がある／情報を忘れる」

見た目は同じでも、問題は2つあります。

# 1. Check for config validation errors (THE COMMON ONE)
grep -i "telegram.*unrecognized\|telegram.*invalid\|telegram.*policy" ~/.openclaw/logs/gateway.err.log | tail -10
# Known issue: the keys "token" and "username" under accounts are not recognized.
# The correct field is "botToken", not "token".

# 2. Check the actual config
cat ~/.openclaw/openclaw.json | jq '.channels.telegram'
# Verify each bot has "botToken" (not "token") and "name" fields.

# 3. Check polling status — bots die after getUpdates timeout
grep -i "telegram.*exit\|telegram.*timeout\|getUpdates" ~/.openclaw/logs/gateway.err.log | tail -10
# "[telegram] [sales] channel exited: Request to 'getUpdates' timed out after 500 seconds"
# This means the bot lost connection to Telegram's API and stopped listening.
# Fix: restart gateway — `openclaw gateway restart`

# 4. Check the polling offset (if bot "forgets" or replays old messages)
cat ~/.openclaw/telegram/update-offset-coder.json
cat ~/.openclaw/telegram/update-offset-sales.json
# If lastUpdateId is stuck or 0, the bot will reprocess old messages.
# To skip to latest: the gateway sets this automatically on restart.

# 5. Check if both bots are starting
grep -i "telegram.*starting\|telegram.*coder\|telegram.*sales" ~/.openclaw/logs/gateway.log | tail -10

# 6. "Bot forgets" — this is usually a session issue, not Telegram
# Each Telegram user gets their own session in sessions.json.
# Check if the session exists:
cat ~/.openclaw/agents/main/sessions/sessions.json | jq -r 'to_entries[] | select(.key | test("telegram")) | "\(.key) | \(.value.origin.label // "?")"'

# 7. Check if compaction happened (context window pruned = "forgot")
SESS_ID="paste-session-id"
grep '"compaction"' ~/.openclaw/agents/main/sessions/$SESS_ID.jsonl | wc -l
# If compaction count > 0, old messages were pruned from context.
# The agent's compaction mode is:
cat ~/.openclaw/openclaw.json | jq '.agents.defaults.compaction'

Telegram の設定修正テンプレート

# Correct Telegram config structure:
cat ~/.openclaw/openclaw.json | jq '.channels.telegram = {
  "enabled": true,
  "accounts": {
    "coder": {
      "name": "Bot Display Name",
      "enabled": true,
      "botToken": "your-bot-token-here"
    },
    "sales": {
      "name": "Sales Bot Name",
      "enabled": true,
      "botToken": "your-bot-token-here"
    }
  },
  "dmPolicy": "pairing",
  "groupPolicy": "disabled"
}' > /tmp/oc.json && mv /tmp/oc.json ~/.openclaw/openclaw.json

---

トラブルシューティング：Signal

「Signal RPC がメッセージの送信に失敗しました」

この問題により、cron ジョブとチャネル間の通知がブロックされます。

# 1. Check if signal-cli process is alive
ps aux | grep "[s]ignal-cli"

# 2. Check the RPC endpoint
grep -i "signal.*starting\|signal.*8080\|signal.*rpc" ~/.openclaw/logs/gateway.log | tail -10
# Should see: "[signal] [default] starting provider (http://127.0.0.1:8080)"

# 3. Check for connection instability
grep -i "HikariPool\|reconnecting\|SSE stream error\|terminated" ~/.openclaw/logs/gateway.err.log | tail -10
# "HikariPool-1 - Thread starvation or clock leap detected" = signal-cli internal DB issue
# "SSE stream error: TypeError: terminated" = lost connection to signal-cli daemon

# 4. Check for rate limiting
grep -i "signal.*rate" ~/.openclaw/logs/gateway.err.log | tail -5
# "Signal RPC -5: Failed to send message due to rate limiting"

# 5. Check for wrong target format
grep -i "unknown target" ~/.openclaw/logs/gateway.err.log | tail -5
# "Unknown target "adi" for Signal. Hint: <E.164|uuid:ID|...>"
# The agent must use phone numbers (+1...) or uuid: format, not names.

# 6. Fix profile name warning spam
grep -c "No profile name set" ~/.openclaw/logs/gateway.err.log
# If high count: run signal-cli updateProfile to set a name

# 7. Test signal-cli directly
ACCT=$(cat ~/.openclaw/openclaw.json | jq -r '.channels.signal.account')
echo "Account: $ACCT"
# signal-cli -a $ACCT send -m "test" +TARGET_NUMBER

# 8. Check if the signal-cli daemon needs restart
# The gateway manages signal-cli as a subprocess.
# Restart the whole gateway: openclaw gateway restart

---

トラブルシューティング：cron ジョブ

# 1. Overview of all jobs
cat ~/.openclaw/cron/jobs.json | jq -r '.jobs[] | "\(.enabled | if . then "ON " else "OFF" end) \(.state.lastStatus // "never" | if . == "error" then "FAIL" elif . == "ok" then "OK  " else .  end) \(.name)"'

# 2. Failing jobs with error details
cat ~/.openclaw/cron/jobs.json | jq '.jobs[] | select(.state.lastStatus == "error") | {name, error: .state.lastError, lastRun: (.state.lastRunAtMs | . / 1000 | todate), id}'

# 3. Read the actual run log for a failing job
JOB_ID="paste-job-uuid-here"
tail -20 ~/.openclaw/cron/runs/$JOB_ID.jsonl | python3 -c "
import sys, json
for line in sys.stdin:
    try:
        obj = json.loads(line)
        if obj.get('type') == 'message':
            role = obj['message']['role']
            text = ''.join(c.get('text','') for c in obj['message'].get('content',[]) if isinstance(c,dict))
            if text.strip():
                print(f'[{role}] {text[:300]}')
    except: pass
"

# 4. Common cron failure causes:
#    - "Signal RPC -1" → Signal daemon down, see Signal section above
#    - "gateway timeout after 10000ms" → gateway was restarting when cron fired
#    - "Brave Search 429" → free tier rate limit hit (2000 req/month)
#    - "embedded run timeout" → job took longer than 600s

# 5. Next scheduled run times
cat ~/.openclaw/cron/jobs.json | jq -r '.jobs[] | select(.enabled) | "\(.name): \((.state.nextRunAtMs // 0) | . / 1000 | todate)"'

# 6. Disable a broken job temporarily
cat ~/.openclaw/cron/jobs.json | jq '(.jobs[] | select(.name == "JOB_NAME")).enabled = false' > /tmp/cron.json && mv /tmp/cron.json ~/.openclaw/cron/jobs.json

---

トラブルシューティング：メモリ／「忘れてしまった」

メモリシステムは3つのレイヤーで構成されています。エージェントが「忘れてしまった」場合、いずれかのレイヤーに問題があります。

レイヤー1：コンテキストウィンドウ（セッション内）

# Check compaction count for a session (compaction = old messages pruned)
grep -c '"compaction"' ~/.openclaw/agents/main/sessions/SESSION_ID.jsonl
# 7 compactions = the agent has "forgotten" its earliest messages 7 times.

# Check compaction mode
cat ~/.openclaw/openclaw.json | jq '.agents.defaults.compaction'
# "safeguard" = only compacts when hitting context limit

レイヤー2：ワークスペースのメモリファイル

# What daily memory files exist
ls -la ~/.openclaw/workspace/memory/

# What's in MEMORY.md (long-term curated)
cat ~/.openclaw/workspace/MEMORY.md

# Search memory files for something specific
grep -ri "KEYWORD" ~/.openclaw/workspace/memory/

レイヤー3：ベクトルメモリデータベース（SQLite + Gemini embeddings）

# What files are indexed
sqlite3 ~/.openclaw/memory/main.sqlite "SELECT path, size, datetime(mtime/1000, 'unixepoch') as modified FROM files;"

# How many chunks (text fragments) exist
sqlite3 ~/.openclaw/memory/main.sqlite "SELECT COUNT(*) FROM chunks;"

# Search chunks by text (FTS5 full-text search)
sqlite3 ~/.openclaw/memory/main.sqlite "SELECT substr(text, 1, 200) FROM chunks_fts WHERE chunks_fts MATCH 'KEYWORD' LIMIT 5;"

# Check embedding config
sqlite3 ~/.openclaw/memory/main.sqlite "SELECT value FROM meta WHERE key='memory_index_meta_v1';" | python3 -m json.tool

# Check for Gemini embedding rate limits (breaks indexing)
grep -i "gemini.*batch.*failed\|RESOURCE_EXHAUSTED\|429" ~/.openclaw/logs/gateway.err.log | tail -10
# "embeddings: gemini batch failed (2/2); disabling batch" = indexing degraded

# Rebuild memory index (re-index all workspace files)
# Delete the DB and restart gateway — it will rebuild:
# rm ~/.openclaw/memory/main.sqlite && openclaw gateway restart

---

セッションの検索

特定の人との会話を検索する

# Search session index by name (case-insensitive)
cat ~/.openclaw/agents/main/sessions/sessions.json | jq -r 'to_entries[] | select(.value.origin.label // "" | test("NAME"; "i")) | "\(.value.sessionId) | \(.value.lastChannel) | \(.value.origin.label)"'

チャネル別にセッションを検索する

cat ~/.openclaw/agents/main/sessions/sessions.json | jq -r 'to_entries[] | select(.value.lastChannel == "whatsapp") | "\(.value.sessionId) | \(.value.origin.label // .key)"'
# Replace "whatsapp" with: signal, telegram, or check .key for cron sessions

最新のセッション

cat ~/.openclaw/agents/main/sessions/sessions.json | jq -r '[to_entries[] | {id: .value.sessionId, updated: .value.updatedAt, label: (.value.origin.label // .key), ch: (.value.lastChannel // "cron")}] | sort_by(.updated) | reverse | .[:10][] | "\(.updated | . / 1000 | todate) | \(.ch) | \(.label)"'

すべてのセッションからメッセージの内容を検索する

# Quick: find which session files contain a keyword
grep -l "KEYWORD" ~/.openclaw/agents/main/sessions/*.jsonl

# Detailed: show matching messages with timestamps
grep "KEYWORD" ~/.openclaw/agents/main/sessions/*.jsonl | python3 -c "
import sys, json
for line in sys.stdin:
    path, data = line.split(':', 1)
    try:
        obj = json.loads(data)
        if obj.get('type') == 'message':
            role = obj['message']['role']
            text = ''.join(c.get('text','') for c in obj['message'].get('content',[]) if isinstance(c,dict))
            if text.strip():
                sid = path.split('/')[-1].replace('.jsonl','')[:8]
                ts = obj.get('timestamp','')[:19]
                print(f'{ts} [{sid}] [{role}] {text[:200]}')
    except: pass
" | head -30

特定のセッションのトランスクリプトを読む

# Last 30 messages from a session
tail -50 ~/.openclaw/agents/main/sessions/SESSION_ID.jsonl | python3 -c "
import sys, json
for line in sys.stdin:
    try:
        obj = json.loads(line)
        if obj.get('type') == 'message':
            role = obj['message']['role']
            text = ''.join(c.get('text','') for c in obj['message'].get('content',[]) if isinstance(c,dict))
            if text.strip() and role != 'toolResult':
                print(f'[{role}] {text[:300]}')
                print()
    except: pass
"

---

設定の編集

安全な編集手順

必ずバックアップを作成し、jq で編集してから再起動します。

cp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.bak.manual
jq 'YOUR_EDIT_HERE' ~/.openclaw/openclaw.json > /tmp/oc.json && mv /tmp/oc.json ~/.openclaw/openclaw.json
openclaw gateway restart

よくある編集

# Switch WhatsApp to allowlist
jq '.channels.whatsapp.dmPolicy = "allowlist" | .channels.whatsapp.allowFrom = ["+1XXXXXXXXXX"]' ~/.openclaw/openclaw.json > /tmp/oc.json && mv /tmp/oc.json ~/.openclaw/openclaw.json

# Enable WhatsApp autopilot (bot responds as you to everyone)
jq '.channels.whatsapp += {dmPolicy: "open", selfChatMode: false, allowFrom: ["*"]}' ~/.openclaw/openclaw.json > /tmp/oc.json && mv /tmp/oc.json ~/.openclaw/openclaw.json

# Add number to Signal allowlist
jq '.channels.signal.allowFrom += ["+1XXXXXXXXXX"]' ~/.openclaw/openclaw.json > /tmp/oc.json && mv /tmp/oc.json ~/.openclaw/openclaw.json

# Change model
jq '.agents.defaults.models = {"anthropic/claude-sonnet-4": {"alias": "sonnet"}}' ~/.openclaw/openclaw.json > /tmp/oc.json && mv /tmp/oc.json ~/.openclaw/openclaw.json

# Set concurrency
jq '.agents.defaults.maxConcurrent = 10 | .agents.defaults.subagents.maxConcurrent = 10' ~/.openclaw/openclaw.json > /tmp/oc.json && mv /tmp/oc.json ~/.openclaw/openclaw.json

# Disable a plugin
jq '.plugins.entries.imessage.enabled = false' ~/.openclaw/openclaw.json > /tmp/oc.json && mv /tmp/oc.json ~/.openclaw/openclaw.json

バックアップから復元する

# Latest backup
cp ~/.openclaw/openclaw.json.bak ~/.openclaw/openclaw.json

# List all backups by date
ls -lt ~/.openclaw/openclaw.json.bak*

# Validate JSON before restart
python3 -m json.tool ~/.openclaw/openclaw.json > /dev/null && echo "OK" || echo "BROKEN"

# Nuclear reset
openclaw configure

---

チャネルのセキュリティモード

モード	動作	リスク
open + allowFrom: ["*"]	誰でもメッセージを送信でき、ボットはすべてのメッセージに応答します	高 — API クレジットを消費し、ボットがあなたになりすまして発言します
allowlist + allowFrom: ["+1..."]	リストに登録された番号からのメッセージのみ受信します	低 — 明示的に制御できます
pairing	未知の送信者にコードを送り、あなたが承認します	低 — 承認が必要です
disabled	チャネルを完全に停止します	なし

現在のセキュリティ状態を確認する

cat ~/.openclaw/openclaw.json | jq '{
  whatsapp: {policy: .channels.whatsapp.dmPolicy, from: .channels.whatsapp.allowFrom, groups: .channels.whatsapp.groupPolicy, selfChat: .channels.whatsapp.selfChatMode},
  signal: {policy: .channels.signal.dmPolicy, from: .channels.signal.allowFrom, groups: .channels.signal.groupPolicy},
  telegram: {policy: .channels.telegram.dmPolicy, groups: .channels.telegram.groupPolicy, bots: [.channels.telegram.accounts | to_entries[] | "\(.key)=\(.value.enabled)"]},
  imessage: {enabled: .channels.imessage.enabled, policy: .channels.imessage.dmPolicy}
}'

---

ワークスペースのファイル

ファイル	内容	編集するタイミング
SOUL.md	性格：口調、スタイル（「ダッシュ記号を使わない、カジュアルな小文字表記」）	ボットの話し方を変更するとき
IDENTITY.md	名前（Jarvis）、生き物の種類、絵文字	ブランドを変更するとき
USER.md	オーナー情報、設定	ユーザーのコンテキストが変わったとき
AGENTS.md	運用ルール：メモリプロトコル、安全性、グループチャットでの動作、ハートビートの指示	ボットの動作を変更するとき
BOOT.md	起動時の指示（自動操縦通知プロトコル：WA → Signal）	起動時の動作を変更するとき
HEARTBEAT.md	定期チェックリスト（空の場合、ハートビート API 呼び出しはありません）	定期タスクを追加／削除するとき
MEMORY.md	長期メモリを厳選して記録（メイン／ダイレクトセッションでのみ読み込み）	ボットが自動で管理します
TOOLS.md	連絡先、SSH ホスト、デバイスのニックネーム	ローカルのツールに関するメモを追加するとき
memory/*.md	日ごとの生ログ、トピック別のチャットログ	ボットが自動で書き込みます

---

セッション JSONL 形式

各 .jsonl ファイルには、1行につき1つの JSON オブジェクトが含まれています。種類は次のとおりです。

type	内容
session	セッションヘッダー：id、タイムスタンプ、cwd
message	会話のターン：role（user/assistant/toolResult）、content、model、usage
custom	メタデータ：model-snapshot、openclaw.cache-ttl
compaction	コンテキストウィンドウが圧縮されました（古いメッセージが削除されました）
model_change	セッション途中でモデルが切り替えられました
thinking_level_change	思考レベルが調整されました

セッションインデックス（sessions.json）のキー：

• パターン：agent:main:{channel}:{contact} または agent:main:cron:{job-uuid}
• フィールド：sessionId（UUID = ファイル名）、lastChannel、origin.label（人が読める名前）、origin.from（正規アドレス）、updatedAt（エポックミリ秒）、chatType（direct/group）

---

ゲートウェイの起動シーケンス

通常の起動には約3秒かかります。

[heartbeat] started
[gateway] listening on ws://127.0.0.1:18789
[browser/service] Browser control service ready
[hooks] loaded 3 internal hook handlers (boot-md, command-logger, session-memory)
[whatsapp] [default] starting provider
[signal] [default] starting provider (http://127.0.0.1:8080)
[telegram] [coder] starting provider
[telegram] [sales] starting provider
[whatsapp] Listening for personal WhatsApp inbound messages.
[signal] signal-cli: Started HTTP server on /127.0.0.1:8080

いずれかの行が表示されない場合、そのコンポーネントの起動に失敗しています。gateway.err.log を確認してください。

---

既知のエラーパターン

エラー	意味	対処方法
Web connection closed (status 408)	WhatsApp Web のタイムアウト。最大12回まで自動再試行します	通常は自動的に復旧します。12/12に達した場合は、ゲートウェイを再起動してください
Signal RPC -1: Failed to send message	signal-cli デーモンの接続が失われました	ゲートウェイを再起動してください
Signal RPC -5: Failed to send message due to rate limiting	Signal のレート制限です	待ってから再試行するか、メッセージの送信頻度を下げてください
No profile name set (signal-cli WARN)	ログが大量に出力されますが、問題はありません	signal-cli -a +ACCOUNT updateProfile --given-name "Name"
Cross-context messaging denied	エージェントがチャネル間の送信を試みました	バグではありません。セキュリティ上の保護機能です。正しいチャネルのセッションからメッセージを送信する必要があります
getUpdates timed out after 500 seconds	Telegram ボットのポーリング接続が失われました	ゲートウェイを再起動してください
Unrecognized keys: "token", "username"	Telegram ボットの設定キーが正しくありません	openclaw.json では token ではなく botToken を使用してください
RESOURCE_EXHAUSTED (Gemini 429)	埋め込みのレート制限です	ワークスペース内のファイルの変更頻度を下げるか、Gemini のクォータをアップグレードしてください
lane wait exceeded	エージェントが長時間の LLM 呼び出しでブロックされています	待機してください。2分以上停止している場合は再起動してください
embedded run timeout: timeoutMs=600000	エージェントの応答が10分を超えました	タスクを小さく分割してください
gateway timeout after 10000ms	再起動中にゲートウェイへ到達できませんでした	ゲートウェイ停止中に Cron が実行されました。一時的な現象です

---

OpenClaw の拡張

OpenClaw には4つの拡張レイヤーがあります。それぞれ異なる問題を解決します。

レイヤー	内容	場所	追加方法
スキル	エージェントが必要に応じて読み込む知識とワークフロー	/opt/homebrew/lib/node_modules/openclaw/skills/ または ~/.openclaw/workspace/skills/	clawdhub install <slug> または npx add-skill <repo>
拡張機能	カスタムチャネルプラグイン（TypeScript）	~/.openclaw/extensions/{name}/	openclaw.plugin.json と TypeScript のソースを作成します
チャネル	メッセージングプラットフォーム（組み込み）	openclaw.json → channels.* と plugins.entries.*	openclaw.json で設定し、認証情報を追加します
Cron ジョブ	スケジュールに従って自律的に実行するタスク	~/.openclaw/cron/jobs.json	エージェントがツール経由で作成するか、jobs.json を直接編集します

スキル：ClawdHub エコシステム

スキルは、エージェントの知識や実行できることを拡張する主な方法です。スキルは Markdown ファイルで、必要に応じてスクリプトやアセットを含めることができ、関連する場合にコンテキストへ読み込まれます。

# Search for skills (vector search across the registry)
clawdhub search "postgres optimization"
clawdhub search "image generation"

# Browse latest skills
clawdhub explore

# Install a skill
clawdhub install supabase-postgres-best-practices
clawdhub install nano-banana-pro

# Install a specific version
clawdhub install my-skill --version 1.2.3

# List what's installed
clawdhub list

# Update all installed skills
clawdhub update --all

# Update a specific skill
clawdhub update my-skill
clawdhub update my-skill --force  # overwrite local changes

現在インストールされているスキル（OpenClaw に同梱）：

カテゴリ	スキル
メッセージング	discord、slack、imsg、wacli、voice-call
ソーシャル／Web	bird（X/Twitter）、blogwatcher、github、trello、notion
Google	gog、google-workspace-mcp、goplaces、local-places
メディア	nano-banana-pro（Gemini 画像生成）、openai-image-gen、video-frames、gifgrep、pixelation、sag（TTS）、openai-whisper、sherpa-onnx-tts、songsee、camsnap
コーディングエージェント	coding-agent（Codex/Claude Code/Pi）、ccbg（バックグラウンド実行ツール）、tmux
生産性	apple-notes、apple-reminders、bear-notes、things-mac、obsidian、himalaya（メール）
スマートホーム	openhue（Philips Hue）、eightctl（Eight Sleep）、sonoscli、blucli（BluOS）
開発ツール	github、worktree、starter、desktop、supabase-postgres-best-practices、superdesign
コンテンツ	remotion-best-practices、remotion-fastest-tech-stack、humanizer、summarize、market、buildinpublic
メタ	skill-creator、clawdhub、find-skills、add-skill、model-usage、session-logs、recentplans、canvas

独自のスキルを作成する

スキルは SKILL.md を含むフォルダーです。

my-skill/
├── SKILL.md              # Required: YAML frontmatter + markdown instructions
├── scripts/              # Optional: executable scripts
├── references/           # Optional: docs loaded on demand
└── assets/               # Optional: templates, images

SKILL.md の形式：

---
name: my-skill
description: What this does and WHEN to trigger it. The description is the primary
  trigger — the agent reads this to decide whether to load the full skill.
---

# My Skill

Instructions go here. Only loaded AFTER the skill triggers.
Keep under 500 lines. Split large content into references/ files.

重要な原則：コンテキストウィンドウは共有リソースです。 エージェントがすでに知っていることは含めないでください。冗長な説明よりも、簡潔な例を優先してください。

# Publish to ClawdHub
clawdhub login
clawdhub publish ./my-skill --slug my-skill --name "My Skill" --version 1.0.0

# Or publish to GitHub for npx add-skill
# (see add-skill skill for details)

マルチエージェントのオーケストレーション

OpenClaw は、他の AI エージェント（Codex、Claude Code、Pi）をバックグラウンドワーカーとして起動できます。これにより、並行するコーディングタスクやレビューなど、複数のエージェントを活用すると効果的な作業を実行できます。

パターン： bash pty:true background:true workdir:/path command:"agent 'task'"

# Spawn Codex to build something (background, auto-approve)
bash pty:true workdir:~/project background:true command:"codex exec --full-auto 'Build a REST API for todos'"
# Returns sessionId for tracking

# Spawn Claude Code on a different task
bash pty:true workdir:~/other-project background:true command:"claude 'Refactor the auth module'"

# Monitor all running agents
process action:list

# Check output of a specific agent
process action:log sessionId:XXX

# Send input if agent asks a question
process action:submit sessionId:XXX data:"yes"

# Kill a stuck agent
process action:kill sessionId:XXX

並行する PR レビュー：

# Fetch all PR refs
git fetch origin '+refs/pull/*/head:refs/remotes/origin/pr/*'

# Launch one agent per PR
bash pty:true workdir:~/project background:true command:"codex exec 'Review PR #86. git diff origin/main...origin/pr/86'"
bash pty:true workdir:~/project background:true command:"codex exec 'Review PR #87. git diff origin/main...origin/pr/87'"

git worktree を使った並行する Issue の修正：

git worktree add -b fix/issue-78 /tmp/issue-78 main
git worktree add -b fix/issue-99 /tmp/issue-99 main

bash pty:true workdir:/tmp/issue-78 background:true command:"codex --yolo 'Fix issue #78: description. Commit and push.'"
bash pty:true workdir:/tmp/issue-99 background:true command:"codex --yolo 'Fix issue #99: description. Commit and push.'"

エージェントの完了時に自動通知：

bash pty:true workdir:~/project background:true command:"codex --yolo exec 'Your task.

When completely finished, run: openclaw gateway wake --text \"Done: summary\" --mode now'"

新しいチャネルの追加

チャネルは、エージェントが通信に使用できるメッセージングプラットフォームです。組み込みチャネル：WhatsApp、Signal、Telegram、iMessage、Discord、Slack。

組み込みチャネルを有効にする：

# 1. Enable the plugin
jq '.plugins.entries.discord.enabled = true' ~/.openclaw/openclaw.json > /tmp/oc.json && mv /tmp/oc.json ~/.openclaw/openclaw.json

# 2. Add channel config
jq '.channels.discord = {enabled: true, dmPolicy: "pairing", groupPolicy: "disabled"}' ~/.openclaw/openclaw.json > /tmp/oc.json && mv /tmp/oc.json ~/.openclaw/openclaw.json

# 3. Add credentials (channel-specific)
# 4. Restart gateway
openclaw gateway restart

カスタムチャネル拡張機能を作成する：

~/.openclaw/extensions/{name}/
├── openclaw.plugin.json    # {"id": "name", "channels": ["name"], "configSchema": {...}}
├── package.json            # Standard npm package
├── index.ts                # Entry point
└── src/
    ├── channel.ts          # Inbound message handling + outbound send
    ├── actions.ts          # Tool actions the agent can invoke
    ├── runtime.ts          # Lifecycle: start, stop, health check
    ├── config-schema.ts    # JSON schema for plugin config
    └── types.ts            # TypeScript types

# List installed extensions
ls ~/.openclaw/extensions/

# View extension manifests
cat ~/.openclaw/extensions/*/openclaw.plugin.json | jq .

# Check extension source files
find ~/.openclaw/extensions/ -name "*.ts" -not -path "*/node_modules/*"

チャネル間の通信

エージェントはあるチャネルでメッセージを受信し、別のチャネルで送信できますが、いくつかのガードレールがあります。

# Check cross-context settings
cat ~/.openclaw/openclaw.json | jq '.tools.message.crossContext'
# allowAcrossProviders: true = agent CAN send across channels
# marker.enabled: false = no "[via Signal]" prefix on cross-channel messages

# If you see "Cross-context messaging denied" errors:
# The agent tried to send from a session bound to channel A to channel B.
# This is a security feature. To allow it:
jq '.tools.message.crossContext.allowAcrossProviders = true' ~/.openclaw/openclaw.json > /tmp/oc.json && mv /tmp/oc.json ~/.openclaw/openclaw.json

BOOT.md 通知プロトコル（設定済み）： エージェントは WhatsApp のメッセージを受信して WhatsApp で返信した後、通知の概要を Signal に送信します。これはチャネル間通信の主要なパターンです。1 つのチャネルで自動運転し、もう 1 つのチャネルをコントロールセンターとして使用します。

Canvas：接続デバイス向け Web UI

接続された Mac／iOS／Android ノードに HTML／ゲーム／ダッシュボードを送信します：

# Check canvas config
cat ~/.openclaw/openclaw.json | jq '.canvasHost // "not configured"'

# List connected nodes
openclaw nodes list

# Present HTML content on a node
# canvas action:present node:<node-id> target:http://localhost:18793/__moltbot__/canvas/my-page.html

# Canvas files live in:
ls ~/.openclaw/canvas/

音声通話

Twilio／Telnyx／Plivo を通じて電話をかけます：

# Check if voice-call plugin is enabled
cat ~/.openclaw/openclaw.json | jq '.plugins.entries["voice-call"] // "not configured"'

# CLI usage
openclaw voicecall call --to "+15555550123" --message "Hello"
openclaw voicecall status --call-id <id>

Cron：スケジュールされた自律タスク

# View all jobs
cat ~/.openclaw/cron/jobs.json | jq '.jobs[] | {name, enabled, schedule: .schedule, channel: .payload.channel, to: .payload.to}'

# Job schedule types:
# "kind": "at", "atMs": <epoch>          — one-shot at specific time
# "kind": "every", "everyMs": <ms>       — recurring interval

# Job delivery targets:
# channel + to fields determine where results go (signal, whatsapp, telegram)
# sessionTarget: "isolated" = fresh context each run (no memory of previous runs)

# To add a job, the agent creates it via tool, or edit jobs.json:
# See existing jobs as templates in ~/.openclaw/cron/jobs.json

---

ライセンス

MIT