Getting Started

Install xopc, add at least one LLM provider key, then use the CLI, TUI, gateway (browser console), or the Electron app. This page walks through a first install from scratch.

Up and running in 30 seconds

Install the CLI, run onboarding, and start chatting in the terminal — three steps:

npm install -g @xopcai/xopc
xopc onboard          # faster path: xopc onboard --quick
xopc tui --local

China mirror: npm install -g @xopcai/xopc --registry=https://registry.npmmirror.com

The sections below cover gateway, channels, desktop, and troubleshooting in more detail.

Terminal demo

1. Prerequisites

• Node.js 22 or newer (node -v)
• pnpm: required only when building from source in this repo (pnpm --version)

End users can install the published CLI with npm install -g @xopcai/xopc (or pnpm add -g).

2. Installation

Option 1: Install from npm (Recommended)

npm install -g @xopcai/xopc

Option 2: Build from source

git clone https://github.com/xopcai/xopc.git
cd xopc
pnpm install
pnpm run build

3. Configuration

Interactive Setup (Recommended)

Use the onboard wizard for guided setup:

xopc onboard
# or: pnpm run dev -- onboard

The wizard will guide you through:

1. Creating the primary Markdown workspace directory (typically ~/.xopc/workspace/main/ when using default config)
2. Generating default ~/.xopc/xopc.json
3. Choosing an LLM provider and API key (DeepSeek is a good default for many setups)
4. Optional messaging channels (Telegram, WeChat (Weixin), Feishu/Lark)
5. Gateway Web console (and optional xopc tui vs gateway choice at the end)

Quick Setup

For minimal setup without interactive prompts:

xopc setup

This creates basic config and workspace files only.

Manual Configuration

Edit ~/.xopc/xopc.json directly:

{
  "agents": {
    "defaults": {
      "model": "anthropic/claude-sonnet-4-5",
      "max_tokens": 8192,
      "temperature": 0.7
    }
  },
  "providers": {
    "anthropic": "${ANTHROPIC_API_KEY}"
  }
}

Tip: Use environment variables for API keys (e.g., ANTHROPIC_API_KEY).

4. First chat (CLI or TUI)

One-shot (agent)

xopc agent -m "Explain what an LLM is in one sentence."
# from a dev clone: pnpm run dev -- agent -m "…"

Interactive TTY (agent -i)

xopc agent -i
# from a dev clone: pnpm run dev -- agent -i

You’ll see a You: prompt. Ctrl+C to exit.

Full-screen TUI (no gateway required)

xopc tui --local

See Terminal UI (TUI) for gateway-connected mode (xopc tui) and session flags.

5. Gateway, OS service, and channels

Telegram (example)

1. Get Bot Token: Open Telegram, search @BotFather, send /newbot

2. Configure in ~/.xopc/xopc.json:

{
  "channels": {
    "telegram": {
      "enabled": true,
      "botToken": "YOUR_BOT_TOKEN",
      "dmPolicy": "allowlist",
      "allowFrom": [123456789]
    }
  }
}

3. Start the gateway (foreground — logs show the URL and token):

xopc gateway
# from a dev clone: pnpm run dev -- gateway

4. Chat in Telegram, or open the Web console in a browser (default port is often 18790 unless you changed gateway.port).

Run the gateway as an OS service

xopc gateway service install
xopc gateway service start

Then use xopc gateway status, xopc gateway stop, xopc gateway restart, and xopc gateway logs as needed. See Gateway.

Web console URL

After xopc gateway, open the URL printed in the terminal (commonly http://localhost:18790 if that is your configured port).

Other bundled channels

WeChat and Feishu/Lark are configured under channels.* in the same JSON file. See Channels.

6. Electron desktop (optional)

Prebuilt macOS / Windows / Linux installers are published on GitHub Releases when available (Windows: xopc-<version>-x64.exe or xopc-<version>-arm64.exe). They bundle the gateway and the same React console as the browser UI.

To build locally from a clone:

pnpm install
pnpm run electron:build   # outputs under dist/release/

7. What's Next?

Explore these guides to unlock more features:

Guide	Description
CLI Reference	All available commands
Configuration	Full config reference
Extensions	Extend functionality
Skills	Add domain-specific knowledge
Tools	Built-in tools reference
Channels	Telegram, WeChat, Feishu, web chat
TUI	Full-screen terminal UI
Routing	Session keys and agent bindings
Models	LLM provider configuration

Troubleshooting

Common Issues

Issue	Solution
ERR_MODULE_NOT_FOUND	Run pnpm install
Cannot find module '@xopcai/...'	Run pnpm run build
Config not loading	Verify ~/.xopc/xopc.json is valid JSON
Bot not responding	Check TELEGRAM_BOT_TOKEN and bot status
API key errors	Verify environment variables are set

Getting Help

• Check Documentation for detailed guides
• Review AGENTS.md for development guide
• View logs: xopc gateway logs --follow