11장 문제 해결 및 최적화

OpenClaw를 사용하다 보면 다양한 문제에 직면하는 것은 불가피합니다. 이 장에서는 일반적인 문제에 대한 해결 방법, 성능 조정 팁 및 커뮤니티 리소스를 요약합니다.

읽기 제안: 섹션 1 "자주 묻는 질문 빠른 확인"은 문제가 발생했을 때 빠르게 찾을 수 있도록 모든 사람이 읽을 것을 권장합니다. 특정 문제가 발생하면 다음 로그 진단, 성능 최적화 및 기타 내용을 읽을 수 있습니다.

1. 빠른 FAQ

1.1 설치 문제

문제	원인	솔루션
`npm install -g openclaw` 실패	Node.js 버전이 너무 낮습니다	Node.js 22 이상으로 업그레이드
권한 오류	npm 전역 설치에 대한 권한이 부족함	`sudo`을 사용하거나 npm 접두사 구성
네트워크 시간 초과	npm 소스에 액세스할 수 없습니다	Taobao 소스로 전환: `npm config set registry https://registry.npmmirror.com`

1.2 API 연결 문제

문제	원인	솔루션
`401 Unauthorized`	API 키가 유효하지 않거나 만료되었습니다	API 키 확인 및 업데이트
`429 Too Many Requests`	API 호출 제한에 도달했습니다	동시 작업을 줄이거나 API 패키지를 업그레이드
연결 시간 초과	네트워크 문제(특히 해외 API 접속 시)	네트워크 프록시 구성(HTTP_PROXY 환경 변수) 또는 국내 공급자(예: Silicon Mobile, 1장 참조)로 전환
`503 Service Unavailable`	API 서비스를 일시적으로 사용할 수 없습니다	복구 대기 중 또는 백업 모델로 전환 중
보조자는 "기억상실증"을 앓고 있습니다(이전에 제공된 정보를 잊어버림)	긴 대화가 컨텍스트 창을 초과하고 기본 메모리 압축으로 세부 정보가 손실됨	USER.md 또는 MEMORY.md에 주요 정보를 기록합니다(자세한 내용은 第九章 참조). 장거리 시나리오에서는 OpenViking 메모리 플러그인을 설치할 수 있습니다

1.3 채널 접근 문제

문제	원인	솔루션
전보가 응답하지 않습니다	Bot 토큰 오류 또는 네트워크 문제	토큰을 확인하고 프록시 구성을 확인하세요.
Feishu 메시지가 응답하지 않습니다	권한이 활성화되지 않았거나 페어링이 완료되지 않았습니다	Feishu 오픈 플랫폼 권한 설정 확인
QQ 연결이 끊어졌습니다	NapCat WebSocket 연결이 끊어졌습니다	NapCat 실행 상태를 확인하고 다시 로그인하세요

1.4 스킬 문제

문제	원인	솔루션
`clawhub install` 실패	네트워크 문제 또는 잘못된 스킬 이름	네트워크를 확인하고 스킬명(슬러그)이 맞는지 확인
설치 후 스킬을 사용할 수 없음	누락된 시스템 종속성	SKILL.md에서 요구사항을 확인하세요
API 키 구성 후에도 오류가 계속 보고됨	openclaw.json 형식 오류	대화형 구성에는 `openclaw config` 사용

확장: 로그 진단

2. 로그 진단

2.1 로그 보기

bash

# 查看实时日志（持续输出）
openclaw logs --follow

# 查看最近 100 条日志
openclaw logs --limit 100

# 以 JSON 格式输出（方便用 jq 等数据处理工具过滤，新手可忽略此选项）
openclaw logs --limit 100 --json

# 纯文本输出（无颜色）
openclaw logs --limit 50 --plain

2.2 로그 수준

jsonc

// openclaw.json 中的 logging 配置
{
  "logging": {
    "level": "info",
    "file": true,
    "maxSize": "50mb",
    "maxFiles": 10
  }
}

개발 및 디버깅 중에 일시적으로 디버그 수준을 켤 수 있습니다.

bash

openclaw config set logging.level debug
openclaw gateway restart

확장: 성능 최적화

3. 성능 최적화

3.1 응답 속도

활성 스킬 감소: 스킬당 약 200-500개의 토큰으로 컨텍스트를 추가했습니다. 10개의 스킬로 3000~5000개의 토큰을 추가할 수 있습니다.

bash

# 查看当前活跃技能数量
clawhub list --active

# 禁用不常用的技能
clawhub uninstall rarely-used-skill

더 빠른 모델 사용: Haiku는 간단한 작업의 경우 Opus보다 5~10배 빠릅니다.

캐싱 활성화:

json

{
  "cache": {
    "enabled": true,
    "ttl": 3600,
    "maxSize": "100mb"
  }
}

3.2 메모리 최적화

bash

# 查看 OpenClaw 内存使用
openclaw status --verbose

# 清理对话历史缓存
openclaw cleanup --conversations --older-than 7d

# 清理技能缓存
openclaw cleanup --skill-cache

3.3 토큰 최적화

bash

# 查看每次调用的 Token 消耗
openclaw usage --detail

# 按技能统计
openclaw usage --by-skill --period month

확장: 데이터 백업 및 복구

4. 데이터 백업 및 복구

4.1 백업해야 할 사항

~/.openclaw/
├── openclaw.json        # 配置文件（API Key、渠道设置）
├── workspace/           # 工作区（详见第九章第 7 节）
│   ├── IDENTITY.md      # 助理身份（名字、风格）
│   ├── SOUL.md          # 人格设定和行为准则
│   ├── USER.md          # 你的个人信息和偏好
│   ├── AGENTS.md        # 工作流程和操作规范
│   ├── TOOLS.md         # 环境专属信息（服务器、设备等）
│   ├── MEMORY.md        # 长期记忆
│   ├── HEARTBEAT.md     # 定期巡检清单
│   ├── BOOT.md          # 网关启动时执行的任务
│   ├── BOOTSTRAP.md     # 首次运行初始化（完成后自动删除）
│   └── memory/          # 每日工作日志
├── skills/              # 已安装技能及配置
├── cron/                # 定时任务
└── conversations/       # 对话历史

4.2 백업 명령

bash

# 完整备份
tar -czf openclaw-backup-$(date +%Y%m%d).tar.gz ~/.openclaw/

# 只备份配置和工作区（不含对话历史）
tar -czf openclaw-config-$(date +%Y%m%d).tar.gz \
  ~/.openclaw/openclaw.json \
  ~/.openclaw/workspace/ \
  ~/.openclaw/skills/ \
  ~/.openclaw/cron/

4.3 복구

bash

# 恢复备份
tar -xzf openclaw-backup-20260307.tar.gz -C ~/

# 重启服务
openclaw gateway restart

확장: 업그레이드 가이드

5. 업그레이드 안내

5.1 OpenClaw 업그레이드

bash

# 查看当前版本
openclaw --version

# 升级到最新版
npm update -g openclaw

# Docker 用户
docker pull ghcr.io/openclaw/openclaw:latest
docker compose up -d

5.2 업그레이드 참고 사항

업그레이드 전 ~/.openclaw/ 디렉터리를 백업하세요.
주요 변경 사항은 릴리스 노트를 참조하세요.
일부 스킬은 메이저 버전 업그레이드 후 재구성이 필요할 수 있습니다.

6. 커뮤니티 리소스

6.1 공식 리소스

자원	주소
공식 문서	https://openclaw.ai/docs
GitHub 저장소	https://github.com/openclaw/openclaw
ClawHub 기술 시장	https://github.com/openclaw/clawhub
디스코드 커뮤니티	https://discord.gg/openclaw

6.2 중국 커뮤니티

자원	주소
이 튜토리얼의 온라인 버전	https://datawhalechina.github.io/hello-claw
데이터웨일 커뮤니티	https://github.com/datawhalechina

6.3 도움 받기

문제 발생 시 문제 해결 단계:

먼저 이 장의 "빠른 FAQ"를 확인하세요.
GitHub 문제 검색
Discord 커뮤니티에 질문하세요
GitHub 문제 제출(로그 및 재생 단계 첨부)

"발톱 입양"을 모두 완료하신 것을 축하합니다! 이제 OpenClaw의 설치 및 구성, 모바일 액세스, 자동화된 작업, 기술 시스템, 외부 서비스 통합, 생산 배포, 다중 모델 최적화 및 실제 응용 프로그램 시나리오를 마스터했습니다.

OpenClaw의 내부에 대해 자세히 알아보거나 처음부터 자신만의 AI 에이전트를 구축하고 싶다면 2부 "Claw 구축"을 계속 읽어보세요.

다음 단계: 第二部分：构建 Claw

11장 문제 해결 및 최적화 ​

1. 빠른 FAQ ​

1.1 설치 문제 ​

1.2 API 연결 문제 ​

1.3 채널 접근 문제 ​

1.4 스킬 문제 ​

2. 로그 진단 ​

2.1 로그 보기 ​

2.2 로그 수준 ​

3. 성능 최적화 ​

3.1 응답 속도 ​

3.2 메모리 최적화 ​

3.3 토큰 최적화 ​

4. 데이터 백업 및 복구 ​

4.1 백업해야 할 사항 ​

4.2 백업 명령 ​

4.3 복구 ​

5. 업그레이드 안내 ​

5.1 OpenClaw 업그레이드 ​

5.2 업그레이드 참고 사항 ​

6. 커뮤니티 리소스 ​

6.1 공식 리소스 ​

6.2 중국 커뮤니티 ​

6.3 도움 받기 ​

11장 문제 해결 및 최적화

1. 빠른 FAQ

1.1 설치 문제

1.2 API 연결 문제

1.3 채널 접근 문제

1.4 스킬 문제

2. 로그 진단

2.1 로그 보기

2.2 로그 수준

3. 성능 최적화

3.1 응답 속도

3.2 메모리 최적화

3.3 토큰 최적화

4. 데이터 백업 및 복구

4.1 백업해야 할 사항

4.2 백업 명령

4.3 복구

5. 업그레이드 안내

5.1 OpenClaw 업그레이드

5.2 업그레이드 참고 사항

6. 커뮤니티 리소스

6.1 공식 리소스

6.2 중국 커뮤니티

6.3 도움 받기