快速开始

从源码构建、配置 Provider，并跑起来第一批 Agent。

前置条件

Java 21+（必须，虚拟线程是运行时核心）
Maven 3.9+（从源码构建）
至少一个 LLM Provider 的 API Key（DeepSeek、Qwen、Kimi 等）

Windows 提示

在 Windows（PowerShell）上可以从源码构建并运行，注意：

安装 JDK 21+ 与 Maven 3.9+，并确认 java -version / mvn -version 可用。
复制配置文件：

powershell

Copy-Item config\application.yml.example config\application.yml

构建：

powershell

mvn clean package "-DskipTests"

powershell

java -jar (Get-ChildItem oryxos-boot\target\oryxos-boot-*.jar | Select-Object -First 1).FullName init
java -jar (Get-ChildItem oryxos-boot\target\oryxos-boot-*.jar | Select-Object -First 1).FullName serve --port 8080

浏览器打开：http://localhost:8080/admin/
健康检查：http://localhost:8080/api/v1/health

bin/start.sh 面向 Unix；Windows 上优先用上面的 java -jar 方式。密钥请用环境变量（如 DEEPSEEK_API_KEY）配合 ${DEEPSEEK_API_KEY} 占位符，不要把明文 Key 写进仓库。

构建

OryxOS 是 Maven 多模块项目，从源码构建可执行的 boot JAR：

bash

mvn clean package -DskipTests

产物在 oryxos-boot/target/。下文用 java -jar oryxos-boot/target/oryxos-boot-*.jar <命令> 调用；示例里统一简写为 oryxos <命令>。

配置 Provider

Provider 凭证放在一个外部配置文件里，不纳入版本管理。复制随仓库提交的模板，填入你的真实 Key：

bash

cp config/application.yml.example config/application.yml

config/application.yml 已在 .gitignore（切勿提交真实 Key）。启动脚本通过 --spring.config.additional-location 加载它；未覆盖的项从 JAR 内置的默认配置继承。

编辑 config/application.yml，为你使用的 Provider 填上 api-key。Provider 以列表形式声明在 oryxos.providers 下：

yaml

oryxos:
  root: .oryxos
  providers:
    - name: deepseek
      api-key: ${DEEPSEEK_API_KEY}      # 环境变量占位符，启动时解析
      base-url: https://api.deepseek.com
    - name: mock                        # 内置假模型——无需 key/url，用于全链路自测

用 ${环境变量} 占位符引用，不要把明文密钥写死。启动时，这里声明的 Provider 会被播种（seed）进 SQLite 的 providers 表（仅当尚不存在时）；此后数据库是权威来源，你也可以通过管理台或 /api/v1/providers 接口动态增删改 Provider——无需重启。

Spring 对列表类键是整体替换而非合并。如果你在外部文件里覆盖 oryxos.providers，必须列全所有想保留的 Provider——只写一部分会把其余的丢掉。

初始化工作区

在你希望 OryxOS 运行的目录下执行 init，它会创建 .oryxos/ 工作区：

bash

oryxos init

创建的内容：

text

.oryxos/
├── agents/             # 每个子目录 = 一个 Agent（AGENT.md + 可选 skills/ scripts/）
├── memory/             # 全局长期记忆（每个 Agent 的 MEMORY.md 在 agents/<name>/ 下）
├── sessions/           # 会话数据（备用；会话实际存 SQLite）
├── logs/               # 结构化 JSON 日志
├── AGENTS.md           # 项目级 Agent 行为说明
├── SOUL.md             # Agent 人格定义
└── USER.md             # 用户偏好（Agent 只读，不写）

SQLite 数据库（oryxos.db）在首次启动时于运行期创建。

可自定义工作区根目录

工作区默认为 .oryxos。若要指向其他位置：

config/application.yml 中的 oryxos.root——对 Spring 启动的命令（serve、gateway）生效
环境变量 ORYXOS_ROOT 或 -Doryxos.root=——对轻命令（init、status、profile）生效，并通过 Spring 宽松绑定同时对启动型命令生效

配置的根目录会在运行期自动纳入文件沙箱白名单，改根不会破坏文件工具。

一个目录 = 一个 Agent

一个 Agent 就是 .oryxos/agents/<name>/ 目录下的一个 AGENT.md。该文件 = YAML frontmatter（这个 Agent 的 Profile）+ Markdown 正文（注入 system prompt 的任务指令）。不再有 .oryxos/profiles/ 目录——Profile 就是 frontmatter。字段详见 Profile 配置。

OryxOS 在 .oryxos/agents/ 下自带三个 Demo Agent 演示这套模型：

Agent	做什么
`weather-daily`	从 open-meteo 拿北京天气，通过 `notify` 推送穿搭建议
`daily-tech-digest`	从 `hn.algolia.com` 拉头条，按需读取 skill 文件，推送科技日报
`github-daily`	用 `shell` 跑受信任的本地 Python 脚本，推送 GitHub 热门日报（需显式允许 `python3`）

三者都用 Provider deepseek / deepseek-v4-flash，并按名引用通知渠道。

github-daily 是需要主动启用的受信任脚本 Demo。默认 shell 白名单刻意不包含 python3，因为解释器等同于任意代码执行能力。显式加入前请先审查脚本，不要对不受信任的 Agent 输入开放。

开始对话

bash

oryxos chat --profile weather-daily

进入交互式对话界面。输入消息回车——Agent 跑一轮 ReAct 循环（思考、按需调用工具、回复）。输入 exit 或按 Ctrl-D 退出。

启动 API 服务

bash

oryxos serve --port 8080

它在 /api/v1 下暴露 REST API，并在以下地址提供 Web 管理台：

text

http://localhost:8080/admin/

管理台（Vue 3，视觉与本站同源）可管理 Agent、Provider、通知渠道、定时任务、会话、工具与沙箱白名单——在线创建和编辑 Agent，无需重启。快速健康检查：

bash

curl http://localhost:8080/api/v1/health

json

{ "code": 0, "message": "success", "data": { "status": "ok" }, "timestamp": 1720000000000 }

每个 API 响应都包裹在 { code, message, data, timestamp } 信封里（code: 0 表示成功）。

用 Docker 运行

每个版本同时在 GHCR 发布多架构容器镜像（linux/amd64 + linux/arm64）——不用装 Java 21、不用下载 tar.gz：

bash

docker run -d --name oryxos -p 8080:8080 -v oryxos-data:/data ghcr.io/oryx-labs/oryxos:latest
curl http://localhost:8080/api/v1/health      # → {"code":0,…}

容器零 key 即可启动（随后在管理台配置 Provider），全部状态——config/、.oryxos/ 工作区、oryxos.db、日志——都落在 /data 卷里，升级 = 拉新 tag 重建容器，数据不丢。镜像以非 root 用户运行，内置针对 /api/v1/health 的健康检查；开箱即用的 compose 栈见仓库根目录的 docker-compose.yml。从源码本地构建镜像：make docker（先 make build）。

注意：存储是单机 SQLite——只跑一个容器。横向扩容需要分布式存储（路线图方向 A）。

下一步

OryxOS 是什么 — 了解架构定位和设计理念
ReAct Loop — 理解 think-act-observe 循环
Profile 配置 — 每个 AGENT.md frontmatter 字段说明
Tool 体系 — 内置 Tool 和扩展方式
REST API — 端点与请求/响应示例
CLI 参考 — 所有命令行工具说明
Memory 系统 — 长期记忆如何跨会话工作

快速开始 ​

前置条件 ​

Windows 提示 ​

构建 ​

配置 Provider ​

初始化工作区 ​

可自定义工作区根目录 ​

一个目录 = 一个 Agent ​

开始对话 ​

启动 API 服务 ​

用 Docker 运行 ​

下一步 ​

快速开始

前置条件

Windows 提示

构建

配置 Provider

初始化工作区

可自定义工作区根目录

一个目录 = 一个 Agent

开始对话

启动 API 服务

用 Docker 运行

下一步