快速开始

装好 xopc、配上至少一家大模型厂商的密钥后，就可以用 命令行、全屏终端（TUI）、网关网页控制台 或 Electron 桌面版。本页从「第一次安装」讲起。

30 秒，立即开始

安装 CLI、运行 onboard、在终端开聊——三步，半分钟上手：

npm install -g @xopcai/xopc
xopc onboard          # 想更快可先执行：xopc onboard --quick
xopc tui --local

国内镜像： npm install -g @xopcai/xopc --registry=https://registry.npmmirror.com

下文会展开网关、频道、桌面版与故障排除等细节。

终端演示

1. 环境要求

• Node.js：22 及以上（node -v）
• pnpm：仅在 从源码构建 本仓库时需要（pnpm --version）

日常使用可直接 npm install -g @xopcai/xopc（或 pnpm add -g），不必先装 pnpm。

2. 安装

方式一：从 npm 安装（推荐）

npm install -g @xopcai/xopc

方式二：从源码构建

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

3. 配置

交互式配置（推荐）

xopc onboard
# 本仓库开发时：pnpm run dev -- onboard

向导一般会带你完成：

1. 创建主 Markdown 工作区（默认常见路径如 ~/.xopc/workspace/main/）
2. 生成默认 ~/.xopc/xopc.json
3. 选择大模型厂商并填 API Key（DeepSeek 对多数场景很合适）
4. 按需配置 Telegram、微信、飞书/Lark 等机器人（可跳过）
5. 网关网页控制台，以及结束时可选 TUI 或 网关 用法提示

快速生成文件（无交互）

xopc setup

只生成基础配置与工作区骨架，不逐步提问。

手写配置

编辑 ~/.xopc/xopc.json（也可用环境变量 XOPC_CONFIG / XOPC_CONFIG_PATH 指向别的路径）：

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

提示： API Key 建议放在环境变量里（如 ANTHROPIC_API_KEY），配置里用 ${…} 引用。

4. 第一次对话（命令行或 TUI）

只问一句（agent）

xopc agent -m "用一句话解释什么是 LLM。"
# 本仓库开发时：pnpm run dev -- agent -m "…"

普通终端里多轮聊（agent -i）

xopc agent -i
# 本仓库开发时：pnpm run dev -- agent -i

出现 You: 后输入内容回车发送，Ctrl+C 退出。

全屏终端（可不先起网关）

xopc tui --local

连已启动的网关、选会话等用法见 终端界面（TUI）。

5. 网关、系统服务与频道

以 Telegram 为例

1. 拿 Bot Token：Telegram 里搜 @BotFather，发 /newbot 按提示创建机器人。

2. 在 ~/.xopc/xopc.json 里增加 channels.telegram：

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

3. 前台启动网关（终端里会打印访问地址和 token）：

xopc gateway
# 本仓库开发时：pnpm run dev -- gateway

4. 去 Telegram 找机器人发消息，或在浏览器打开 网页控制台（端口以终端输出为准，常见默认 18790，具体看 gateway.port）。

以 OS 服务运行网关

xopc gateway service install
xopc gateway service start

之后可用 xopc gateway status、xopc gateway stop、xopc gateway restart、xopc gateway logs。详见 网关。

其它内置频道

微信、飞书/Lark 同样在 channels.* 里配置，并需先起网关。总览与私聊策略见 频道。

6. Electron 桌面版（可选）

macOS / Windows / Linux 的安装包见 GitHub Releases（有发版时；Windows 为 xopc-<版本>-x64.exe 或 xopc-<版本>-arm64.exe）。与浏览器里打开的是同一套网关 + 网页控制台。

在本仓库里自行打包：

pnpm install
pnpm run electron:build   # 产物在 dist/release/

7. 接下来看哪里

指南	说明
CLI 参考	子命令与参数
配置	xopc.json 全字段
扩展	插件与加载时机
技能	SKILL.md
工具	内置工具
频道	Telegram、微信、飞书、网页对话
TUI	全屏终端
路由	会话 key 与智能体绑定
模型	厂商与密钥

故障排除

常见问题

现象	处理
ERR_MODULE_NOT_FOUND	在本仓库根目录执行 pnpm install
Cannot find module '@xopcai/...'	先 pnpm run build
读不到配置	确认 ~/.xopc/xopc.json 是合法 JSON
机器人不回	查 Token、策略、channels.*.enabled
模型报错	查对应厂商环境变量 / 控制台密钥

需要更多帮助

• 站点内其它中文页：文档首页
• 开发约定：AGENTS.md
• 看网关日志：xopc gateway logs --follow