开始使用 xopc

让重要的事持续向前。从桌面应用开始，连接一个模型，让 xopc 帮你找到下一个可信行动。

选择开始方式

你的偏好	从这里开始
像普通应用一样安装使用	从 xopc.ai 下载
主要使用终端	终端快速开始
使用容器自托管	Docker

对大多数人来说，桌面应用最简单。安装细节见桌面应用指南。终端版和 Docker 使用相同配置，可以以后再添加。

准备内容

• 一个受支持的模型账号和 API Key，或者 Ollama 等本地模型服务。
• 只有安装命令行版本时才需要 Node.js 22 或更高版本。
• 只有选择容器安装时才需要 Docker。

第一次聊天前不需要配置消息通道、工具、额外 Agent 或远程访问。

完成第一次可用配置

1. 从官网下载、安装并打开 xopc，或选择上面的其它方式。
2. 添加一个模型服务商。桌面或网页控制台按模型设置页面操作；终端运行 xopc onboard --quick。
3. 打开 聊天，或者在终端运行 xopc。
4. 发送：请回复“xopc 已就绪”，并告诉我你正在使用哪个模型。

助手正常回复，并且没有凭据或连接错误，就表示基础设置完成。

如果没有成功，先运行 xopc doctor，再查看故障排查。

交给它一件真实的事

连接成功后，先跳过功能探索，直接告诉 xopc 一个重要方向：

这周我最想推进的一件事是 ____。
请帮我澄清想要的结果，并找出最小但可信的下一步。
任何长期记忆都先让我检查。

启用用户理解后，可以在 你 或 用户上下文 中查看等待确认的理解。只确认准确且有用的内容；其它内容可以纠正、拒绝或删除。详见用户理解。

部分桌面版本还提供实验性的 接入最近的工作 首次体验。它只分析你明确选择的文件夹，读取范围有上限且只读，并给出带证据的下一步。在 macOS 上，它还可能分别请求 Apple Notes、Calendar 和 Reminders 权限。如果更希望从对话开始，可以直接跳过。

按需要认识核心功能

功能	用途	指南
用户理解	可审查的目标、偏好、关系、当前重点和协作规则	用户理解
Session	可以从任一已连接客户端继续的对话	聊天与会话
Agent	有独立角色、模型、工具和工作区的助手	Agent
Project 与 Task	有明确结果、状态和下一步的长期工作	Project、Task 与笔记
Workflow	可重复使用的多步骤工作流程	工作流
Automation	按时间、Webhook 或手动触发工作	自动化
Channel	从 Telegram、微信或飞书使用同一个助手	消息通道

只把 xopc 当作普通聊天助手时，不需要创建 Project、Workflow 或 Automation。工作需要持续或重复时再添加即可。

推荐的下一步

1. 阅读产品理念，了解 xopc 的信任和主动性模型。
2. 阅读数据与文件位置，了解哪些内容保存在本地。
3. 添加第二个模型前，先了解模型与服务商，尤其注意哪些个人上下文可能发送给云端服务商。
4. 只有其它设备需要访问 Gateway 时才配置远程访问。
5. 本地聊天正常后再连接消息通道。

配置保存在哪里

xopc 默认将状态保存在 ~/.xopc/，主配置文件是 ~/.xopc/xopc.json。建议使用命令查看，不必手动寻找文件：

xopc config path
xopc config validate
xopc config show

config show 会隐藏已识别的敏感值。不要把 API Key、Gateway Token 或机器人 Token 放入 Issue 或截图。