Local Development

This guide covers setting up OpenPollen for local development.

Requirements

Tool	Version
Node.js	20 or higher
npm	10 or higher
Git	2.x

Get the Source

git clone https://github.com/tom-byte-sys/OpenPollen.git
cd OpenPollen

Install Dependencies

npm install

Configuration

Copy the example config:

cp openpollen.json.example openpollen.json

Edit openpollen.json, configure at least one model provider:

{
  "providers": {
    "anthropic": {
      "enabled": true,
      "apiKey": "sk-ant-..."
    }
  }
}

Or use environment variables:

export ANTHROPIC_API_KEY=sk-ant-...

Development Mode

npm run dev

Uses tsx watch to auto-restart on file changes.

Build

npm run build

Output goes to dist/ directory.

Run Tests

npm run test

Uses vitest test runner.

Type Check

npm run typecheck

Directory Structure

OpenPollen/
├── src/
│   ├── index.ts          # Entry point, assembles all modules
│   ├── config/           # Config loading and schema validation
│   ├── gateway/          # HTTP server and message routing
│   │   ├── server.ts     # HTTP endpoints
│   │   ├── router.ts     # Message routing
│   │   ├── session.ts    # Session management
│   │   └── auth.ts       # Auth service
│   ├── agent/            # Agent runtime
│   │   ├── runner.ts     # Agent execution engine
│   │   ├── skill-manager.ts  # Skill management
│   │   └── marketplace-client.ts  # Marketplace API client
│   ├── channels/         # Channel adapters
│   │   ├── interface.ts  # Channel interface definitions
│   │   └── webchat/      # WebChat implementation
│   ├── plugins/          # Plugin system
│   │   ├── types.ts      # Plugin type definitions
│   │   ├── registry.ts   # Plugin registry
│   │   └── loader.ts     # Plugin loader
│   ├── memory/           # Memory storage
│   └── utils/            # Utilities
├── cli/                  # CLI entry point
│   └── index.ts          # All CLI command definitions
├── plugins/              # External plugins
│   ├── dingtalk/         # DingTalk plugin
│   └── wechat/           # WeCom plugin
├── skills/               # Built-in skills
│   ├── code-review/
│   └── data-analyst/
└── tests/

Data Directory

Runtime data is stored in ~/.openpollen/:

~/.openpollen/
├── openpollen.json        # Configuration file
├── auth.json             # Login credentials
├── openpollen.pid         # Process PID file
├── memory.db             # SQLite memory database
├── memory/               # Markdown memory files
├── skills/               # Installed skills
└── logs/
    └── openpollen.log     # Log file

FAQ

Port already in use

Default ports: Gateway 18800, WebChat 3001. Change gateway.port and channels.webchat.port in config.

Model API connection timeout

If you can't access Anthropic API directly from China, configure the Beelive proxy:

{
  "providers": {
    "beelive": {
      "enabled": true,
      "apiKey": "your-beelive-key",
      "baseUrl": "https://lite.beebywork.com/api/v1/anthropic-proxy"
    }
  }
}

Claude Code Settings Conflict

If WebChat shows no response after sending a message, and the log contains Claude Code process exited with code 1 or ConnectionRefused, Claude Code's own config file may be overriding the environment variables set by OpenPollen.

How to diagnose:

Check Claude Code's global settings file:

• macOS / Linux: ~/.claude/settings.json
• Windows: C:\Users\<username>\.claude\settings.json

If the file contains an env field like:

{
  "env": {
    "ANTHROPIC_BASE_URL": "http://127.0.0.1:8045",
    "ANTHROPIC_API_KEY": "sk-..."
  }
}

Claude Code will prioritize settings.json over environment variables, ignoring the proxy URL and API key configured by OpenPollen. This causes it to connect to the wrong address.

Solution:

Clear the env field in settings.json:

{}

Or remove only the ANTHROPIC_-related entries. Restart OpenPollen after making changes.

Invalid Channel Credentials

If you enable a channel (DingTalk, Feishu, etc.) during initialization but enter invalid credentials, that channel will fail to start. Since v0.1.9, a single channel failure no longer prevents the entire service from starting — the log will show 插件启动失败，已跳过 (plugin startup failed, skipped). To disable an unused channel, set its enabled to false in the config file.

Viewing Logs

# View last 50 lines
npx openpollen logs

# Follow logs
npx openpollen logs -f

# Errors only
npx openpollen logs -l error