介绍

OpenEarth 把 agent 运行过程中的全部经验 —— 轨迹、技能、知识、记忆 —— 沉淀成可检视、可演进、可分享的明文数据,下次会话直接用上,越用越强。

• 📡 无感采集:后台读各 agent 原生会话库(零插桩),采下完整轨迹(思考 / 工具调用 / 结果),训练与推理共用一套。
• 🗂️ 经验即数据:轨迹 / 技能 / 知识 / 记忆进同一个明文 git store,可检视、可版本化、可分享。
• 🌿 从经验演进:在 train/* 分支上从轨迹蒸馏技能,无回退 gate 通过才合并进 main。
• 📚 知识库:文档摄入成可检索 wiki,agent 直接读。
• 🔌 多 agent:opencode · claude-code · codex · cursor · codeagent。

安装

OpenEarth 有三种角色:

把对应模式的 skill 复制给你的 agent,它会自动装好。 详细部署指南见 docs/deployment.md。

standalone / server

---
name: openearth-setup
description: 安装并初始化 OpenEarth standalone 或 server 模式。
---

# openearth-setup

**不要索要或回显 API key 明文**,需要就让用户设环境变量。

## 1. 装包

```bash
pip install openearth-ai
```

Windows 如果 Python < 3.10,从 python.org 装新版。Linux (Ubuntu 24.04) 用 venv:
```bash
python3 -m venv ~/.venv-openearth && ~/.venv-openearth/bin/pip install openearth-ai
```

## 2. 设环境变量

**API key 只能放环境变量,不要 echo 明文。**

Windows (PowerShell,重开终端生效):
```powershell
setx OPENEARTH_DOMAIN_AGENT_KEY "sk-..."
```

Linux:
```bash
export OPENEARTH_DOMAIN_AGENT_KEY=sk-...      # 加到 ~/.bashrc 或 ~/.profile
```

## 3. 初始化配置

```bash
openearth config --init
```

编辑 `~/.openearth/config.yaml`,确认 `domain_agent`(`base_url` / `model`),`api_key` 保持 `env:` 形式:

```yaml
domain_agent:
  agent_backend: pydantic-ai
  model: <your-model>
  base_url: https://<your-openai-compatible-endpoint>/v1
  api_key: env:OPENEARTH_DOMAIN_AGENT_KEY
```

> 如果 LLM endpoint 在内网,确认 `no_proxy` 包含其 IP,否则 LLM 请求走 proxy 会被拒绝。

## 4a. standalone:直接启动

```bash
openearth install         # 装技能 + 写 Knowledge pointer + 起 daemon
openearth service status
openearth agents
```

## 4b. server:onboard 后启动

```bash
openearth onboard --role server --host 0.0.0.0 --port <port>
openearth service start
```

`onboard` 会保留上一步的 LLM 配置并打印 **join token**(保存好,client 用它连接)。
daemon 运行 knowledge / trajectory / skills / link 服务。

## 5. 加文档到知识库

```bash
openearth knowledge ingest <path>
openearth knowledge progress
```

client

---
name: openearth-client-setup
description: 安装 openearth client,连接到已运行的 server。
---

# openearth-client-setup

client 不需要 LLM 配置 —— 文档解析在 server 端完成。

## 1. 装包

```bash
pip install openearth-ai
```

## 2. Onboard 为 client

需要 server 的 URL 和 join token。**join token 是明文，不要直接敲在命令行上**
(会进 shell history / 进程表)。先放进环境变量,再以 `env:` 引用：

```bash
# 把 join token 存进环境变量(不要 echo 明文)
export OPENEARTH_JOIN_TOKEN=<join-token>    # Linux;Windows 用 setx OPENEARTH_JOIN_TOKEN "<join-token>"

openearth onboard --role client \
  --server-url http://<server-ip>:<server-port> \
  --token env:OPENEARTH_JOIN_TOKEN \
  --materialize
```

> `--token` 支持 `env:VAR` / `file:PATH` 引用。用 `env:` 时 token 只在运行时的环境变量里，
> 不会落盘也不会出现在政策文件里；直接给明文 token 则会写进 gitignored 的
> `Link/.meta/runtime/link.token`。

## 3. 启动 daemon

```bash
openearth service start
openearth service status
```

daemon 自动连接 server、上传轨迹、拉取知识 / 技能、安装到本地 agent(materialize)。
(client 用 `service start`;standalone 才用 `install`,后者还会先把技能种进本地 store。)

## 4. 验证已连接

```bash
openearth service status                 # 应 running
# server 侧(有 server 权限时)确认 client 已注册:
openearth link clients                   # 应从列表看到本机的 client_id 和版本
```

## 5. 提交文档

```bash
openearth doc submit <file> --topic "<topic>"
openearth doc status <job-id>
```

锁版本 / 离线:到 Releases 下载 .whl,pip install openearth_ai-<ver>-py3-none-any.whl。 升级:client 连的 server 发布更高版本后,client daemon 会自动检测并升级(auto_upgrade);也可手动 openearth upgrade --check。openearth upgrade --package <whl> 要求 wheel 文件名以 openearth_ai- 开头,否则报 "not a pure-python openearth wheel"。