0xranx/OpenContext 详细部署教程

项目概述

OpenContext 是一个轻量级的个人上下文/知识库工具，为 AI 助手（Agent）和编码工具（如 Cursor、Claude Code、Codex）提供持久记忆功能。

核心理念：OpenContext 不替换你已有的编码代理 CLI，而是复用你现有的 CLI（Codex/Claude/OpenCode），并为其添加 GUI 和内置 Skills/工具，让 Agent 能够“先读历史再动手、做完再沉淀”。

解决的痛点：

上下文跨天、跨仓库、跨会话丢失
需要重复解释背景、重复决策
现有知识无法被 Coding Agent 直接读写

包含的组件：

oc CLI：管理全局 contexts/ 文档库（目录/文档、清单、检索）
MCP Server：让 Cursor/Claude Code/Codex 通过工具调用 OpenContext
Skills + 斜杠命令：为 Cursor/Claude Code/Codex 生成用户级 skills
桌面应用：原生 UI 管理/搜索/编辑上下文
Web UI：本地浏览/编辑文档

部署前准备

系统要求

项目	要求
Node.js	>= 18
操作系统	Windows / macOS / Linux
已有编码代理	Cursor、Claude Code、Codex 或 OpenCode 之一
磁盘空间	最低 500MB

环境检查

1 2	node --version # 应 >= 18 npm --version

方案一：CLI + 工具接入（推荐）

这是最适合开发者的部署方式，复用你已有的编码代理 CLI。

步骤 1：安装 CLI

1	npm install -g @aicontextlab/cli

步骤 2：初始化 OpenContext

进入你的项目目录，运行初始化命令：

1 2	cd your-project oc init

oc init 会提示你选择要集成的工具（默认全选），并自动生成用户级 skills 和斜杠命令。

步骤 3：验证安装

初始化完成后，你可以查看生成的配置文件位置：

斜杠命令（Cursor/Claude Code）：

Cursor: ~/.cursor/commands
Claude Code: ~/.claude/commands（或 $CLAUDE_CONFIG_DIR/commands）

Skills：

Cursor: ~/.cursor/skills/opencontext-*/SKILL.md
Claude Code: ~/.claude/skills/opencontext-*/SKILL.md
Codex: ~/.codex/skills/opencontext-*/SKILL.md

MCP 配置：

Cursor: ~/.cursor/mcp.json
Claude Code: ~/.claude/mcp.json
Codex: ~/.codex/mcp.json

步骤 4：非交互式安装（可选）

如果你需要在自动化脚本中安装：

# 指定工具
oc init --tools cursor,claude,codex

# 或排除某些工具
oc init --no-cursor --no-claude

方案二：桌面应用安装

如果你偏好图形界面，可以从 Releases 页面下载桌面应用。

步骤 1：访问 Releases 页面

text

1	https://github.com/0xranx/OpenContext/releases

步骤 2：下载对应平台安装包

根据你的操作系统下载 macOS 或 Windows 安装包。仓库中未明确提供 Linux 桌面包或源码编译桌面应用的详细步骤。

步骤 3：安装并运行

按照安装向导完成安装，启动后即可通过原生 UI 管理上下文。

方案三：仅安装 CLI（高级用户）

如果你只需要 CLI 进行自动化管理：

1	npm install -g @aicontextlab/cli

常用命令参考

根据 CLI 命令快速参考：

命令	功能
`oc init`	初始化 OpenContext + 用户级工具集成
`oc folder ls`	列出所有文件夹
`oc folder create <path> -d "desc"`	创建文件夹
`oc doc create <folder> <name>.md -d "desc"`	创建文档
`oc doc ls <folder>`	列出文件夹中的文档
`oc context manifest <folder>`	生成供 AI 读取的文件清单
`oc search "query"`	搜索文档
`oc mcp`	启动 MCP 服务器
`oc ui`	启动本地 Web UI

运行 oc <cmd> --help 查看详细用法。

在编码代理中使用

安装完成后，你可以在 Cursor 或 Claude Code 中使用以下斜杠命令：

命令	功能
`/opencontext-context`	开始工作前加载背景
`/opencontext-search`	查找相关文档
`/opencontext-create`	创建新文档
`/opencontext-iterate`	沉淀学到的内容

使用流程：

开始新任务时，先运行 /opencontext-context 加载相关背景
需要查找特定信息时，使用 /opencontext-search
学到新知识或做出决策后，用 /opencontext-create 或 /opencontext-iterate 沉淀

从源码开发（可选）

如果你需要参与开发或自定义功能：

# 克隆并安装
git clone https://github.com/0xranx/OpenContext.git
cd OpenContext && npm install

# 桌面应用开发
npm run tauri:dev    # 开发模式
npm run tauri:build  # 生产构建

# Web UI 开发
npm run ui:dev       # 开发模式
npm run ui:build     # 生产构建

常见问题排查

问题	解决方案
`oc` 命令未找到	确认 npm 全局 bin 目录在 PATH 中
`oc init` 后代理看不到 skills	重启你的编码代理（Cursor/Claude Code/Codex）
MCP 工具调用失败	检查 `mcp.json` 配置文件路径是否正确
Node.js 版本过低	升级到 Node.js 18 或更高版本
桌面应用无法启动	检查系统版本，macOS 可能需要处理隔离属性

总结

部署方式	适用场景	难度	推荐度
CLI + 工具接入	开发者，使用 Cursor/Claude Code/Codex	⭐	⭐⭐⭐⭐⭐
桌面应用	偏好图形界面的用户	⭐	⭐⭐⭐⭐
仅 CLI	高级用户/自动化	⭐⭐	⭐⭐⭐

对于大多数开发者，CLI + 工具接入是最简单直接的选择：

# 安装
npm install -g @aicontextlab/cli

# 初始化（在你的项目目录中）
cd your-project
oc init

# 在 Cursor/Claude Code 中使用
# /opencontext-context  — 加载背景
# /opencontext-search   — 查找文档
# /opencontext-create   — 创建文档
# /opencontext-iterate  — 沉淀知识