Nhảy tới nội dung

🛠️ Cài đặt OpenClaw từ Source

Hướng dẫn này dành cho developers muốn:

  • Contribute vào OpenClaw
  • Customize tính năng
  • Debug issues
  • Build custom version
Lưu ý
Nếu bạn chỉ muốn **sử dụng** OpenClaw, hãy xem [Quick Start](/docs/getting-started/quick-start).

Prerequisites​

1. Node.js >= 22​

node --version  # v22.x.x

2. pnpm (Khuyên dùng)​

npm install -g pnpm
pnpm --version  # 8.x+
Tại sao pnpm?
- Nhanh hơn npm/yarn - Tiết kiệm disk space - Monorepo support tốt - Đây là package manager chính thức của OpenClaw

3. Build Tools​

```bash xcode-select --install ```

Clone Repository​

git clone https://github.com/openclaw/openclaw.git
cd openclaw

Repository structure:

openclaw/
├── packages/
│   ├── cli/           # CLI tool
│   ├── gateway/       # Gateway server
│   ├── core/          # Core libraries
│   └── ui/            # Web dashboard
├── plugins/           # Channel plugins
├── docs/              # Documentation
└── pnpm-workspace.yaml

Install Dependencies​

pnpm install

Điều này sẽ:

  • Install tất cả dependencies
  • Link các packages trong monorepo
  • Setup husky git hooks

Build​

Build toàn bộ project​

pnpm build

Build từng package​

# Build CLI only
pnpm --filter cli build

# Build Gateway only
pnpm --filter gateway build

# Build UI/Dashboard
pnpm ui:build
UI Build
Lần đầu chạy `pnpm ui:build` sẽ tự động cài đặt UI dependencies.

Build Canvas (Advanced UI)​

pnpm canvas:a2ui:bundle

Chạy Development Mode​

Gateway với verbose logging​

node openclaw.mjs gateway --port 18789 --verbose

Hoặc dùng pnpm:

pnpm openclaw gateway --port 18789 --verbose

Watch mode (auto-rebuild)​

pnpm dev

Onboarding từ Source​

Sau khi build xong:

openclaw onboard --install-daemon

Hoặc:

node openclaw.mjs onboard --install-daemon

Testing​

Run unit tests​

pnpm test

Run specific test file​

pnpm test -- packages/cli/__tests__/commands.test.ts

Run e2e tests​

pnpm test:e2e

Linting & Formatting​

# Lint
pnpm lint

# Fix lint issues
pnpm lint:fix

# Format code
pnpm format

Development Workflow​

1. Tạo branch mới​

git checkout -b feature/my-feature

2. Code & Test​

# Watch mode
pnpm dev

# Run specific tests
pnpm test -- --watch

3. Build & Verify​

pnpm build
pnpm lint
pnpm test

4. Commit​

git add .
git commit -m "feat: add my feature"

OpenClaw sử dụng Conventional Commits:

  • feat: - New feature
  • fix: - Bug fix
  • docs: - Documentation
  • chore: - Maintenance
  • refactor: - Code refactoring

5. Push & Create PR​

git push origin feature/my-feature

Debugging​

Enable debug logs​

DEBUG=openclaw:* openclaw gateway --port 18789

VS Code Launch Config​

Tạo .vscode/launch.json:

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Debug Gateway",
      "type": "node",
      "request": "launch",
      "runtimeArgs": ["--experimental-vm-modules"],
      "program": "${workspaceFolder}/openclaw.mjs",
      "args": ["gateway", "--port", "18789", "--verbose"],
      "cwd": "${workspaceFolder}",
      "console": "integratedTerminal"
    }
  ]
}

Common Issues​

pnpm install fails​

# Clear cache
pnpm store prune
rm -rf node_modules
pnpm install

Build errors​

# Clean build
pnpm clean
pnpm build

Node version mismatch​

# Use nvm
nvm install 22
nvm use 22

TypeScript errors​

# Rebuild TypeScript project references
pnpm build --force

Architecture Overview​

┌──────────────┐     ┌──────────────┐     ┌──────────────┐
│  CLI Tool    │ ──▸ │   Gateway    │ ◀── │  Channels    │
└──────────────┘     └──────────────┘     └──────────────┘
                           │
                           ▼
                    ┌──────────────┐
                    │    Agents    │
                    └──────────────┘
                           │
                           ▼
                    ┌──────────────┐
                    │  LLM APIs    │
                    │ (Claude/GPT) │
                    └──────────────┘
  • CLI: Command-line interface, communicates with Gateway
  • Gateway: Central hub, manages agents and channels
  • Agents: AI reasoning units with tools
  • Channels: Telegram, WhatsApp, Discord integrations

Contributing​

  1. Fork repository
  2. Create feature branch
  3. Make changes
  4. Write/update tests
  5. Submit Pull Request

See CONTRIBUTING.md for detailed guidelines.

Resources​

Have questions? Ask in Discord #dev