# OpenLife Installation Manual

Este manual deixa qualquer usuário pronto para instalar e usar o OpenLife.

## Quick start

```bash
npm install -g @openlife/cli
openlife init
```

> **v1.11.0:** Após instalar ambos os perfis (core + agent), eles compartilham
> `~/.openlife/` automaticamente — memória, manifest de descoberta e
> cli-inbox vivem lá. Para estender memória pra nuvem:
> `export OPENLIFE_MEMORY_PROVIDER=mem0|honcho|supermemory|redis-ams` + a
> respectiva API key no `.env`. Detalhes em
> [`docs/core-agent-bridge.md`](./docs/core-agent-bridge.md).

`openlife init` é o **wizard interativo v2** (v1.8.0+): phase-based, sequencial,
multi-host, multi-product. Cada fase espera Enter — sem batched prompts.

### O que você escolhe (em ordem)

1. **Produto** — `openlife-core` (CLI local), `openlife-agent` (daemon long-running),
   ou ambos. Quando ambos selecionados, instalação é sequencial: core primeiro, agent depois.
2. **Host CLIs** — multi-select de `claude-code`, `gemini-cli`, `codex`.
   OpenLife é instalado em cada host escolhido.
3. **Providers LLM** — ~30 providers em 5 tiers (OpenAI, Anthropic, Gemini, Codex,
   Grok/xAI, DeepSeek, Groq, Together, Mistral, Bedrock, Qwen, Kimi, MiniMax, GLM,
   Hugging Face, NVIDIA NIM, Perplexity, OpenRouter, Ollama, vLLM, SGLang, llama.cpp,
   LM Studio, LiteLLM, ClawRouter, Custom OpenAI-compatible).
4. **API keys** — uma por provider, input mascarado, salvo em `.env` só após confirmar.
5. **Auth strategy (agent only)** — para cada provider você escolhe `API key`,
   `OAuth`, ou `skip`. OAuth disponível só para **Codex**, **Gemini CLI** e **Grok/xAI**.
   **Anthropic OAuth é explicitamente bloqueado** (use API key only).
6. **Telegram (agent only)** — bot token (validado via getMe), allowed user ID,
   modo de entrega (`auto`/`polling`/`webhook`).
7. **Service mode (agent only)** — `manual`/`nohup`/`systemd`/`pm2`.
8. **Confirmação** — preview completo, então Enter para aplicar.

Se já houver instalação prévia (`.openlife/install-manifest.json`), o wizard
oferece `abort | reinstall | repair` na fase 01.

Para automação/CI use o caminho não-interativo na seção 5.

### Fallback para o wizard v1

Se você scriptou contra o wizard antigo (batched-Q&A), use `openlife init --legacy`
para continuar com a v1.7.x UX. A v1 será removida em v2.0.0.

### Disponibilidade no npm

A primeira versão pública (`@openlife/cli@1.6.0`) é publicada via GitHub
Actions (`.github/workflows/publish.yml`) quando o owner do repositório
dispara o workflow após registrar o secret `NPM_TOKEN`. Detalhes em
`docs/release-process.md` seção 8.

Se `npm install -g @openlife/cli` retornar **404 Not Found**, o publish
ainda não foi acionado. Caminhos alternativos enquanto isso:

- **Via código-fonte** (seção 8 deste manual) — funciona em qualquer
  máquina com Node 20+ e Git.
- **Via `npm link` local** — se você está desenvolvendo no próprio
  clone: `git clone … && cd openlife-core && npm install && npm run
  build && npm link`. Depois `openlife --help` resolve para o checkout.

Conflito conhecido: se você já fez `npm link` local e depois roda
`npm install -g @openlife/cli`, o instalador global pode falhar.
Rode `npm unlink -g @openlife/cli` antes do `install -g`.

## 1) Requisitos

- Node.js **20+**
- npm **10+**
- Git (para instalação por fonte)

Verificação:

```bash
node -v
npm -v
git --version
```

## 2) Hosts suportados

OpenLife instala artefatos no host CLI escolhido. Cada host tem um documento dedicado em `docs/install/`.

| Host         | Status                          | Detecção (env var)                       | Artefatos instalados                                                                |
|--------------|---------------------------------|------------------------------------------|-------------------------------------------------------------------------------------|
| `claude-code`| **Supported (v1.0)**            | `CLAUDECODE` ou `CLAUDE_PROJECT_DIR`     | `.claude/agents/openlife-*.md`, `.claude/commands/openlife/*.md`, MCP staged        |
| `gemini-cli` | Reserved for v1.1 follow-up     | `GEMINI_CONFIG_DIR`                      | Nenhum no host — `.openlife/` é criado; install retorna `HOST_NOT_YET_SUPPORTED`    |
| `codex`      | Reserved for v1.1 follow-up     | `CODEX_HOME`                             | Nenhum no host — `.openlife/` é criado; install retorna `HOST_NOT_YET_SUPPORTED`    |

**Degradação graciosa:** escolher `gemini-cli` ou `codex` não trava o setup. O `InstallFlow` captura `HostNotYetSupportedError` e segue: `.openlife/` (state dir) ainda é provisionado, e o resultado reporta `hostInstall: { ok: false, reason: 'host_not_yet_supported' }` em vez de abortar.

Documentação por host:

- `docs/install/claude-code.md`
- `docs/install/gemini-cli.md`
- `docs/install/codex.md`

## 3) Detecção automática de host

Se você não passar `--host`, o `InstallFlow.detectHostFromEnv()` infere a partir do ambiente (ordem de precedência):

1. `CLAUDECODE` ou `CLAUDE_PROJECT_DIR` → `claude-code`
2. `GEMINI_CONFIG_DIR` → `gemini-cli`
3. `CODEX_HOME` → `codex`
4. Sem match → default `claude-code`

Para forçar um host independentemente do ambiente, use `--host <name>`.

## 4) Profiles: `framework` vs `autonomous`

| Profile      | Quando usar                                                                                  | O que muda                                                                  |
|--------------|----------------------------------------------------------------------------------------------|------------------------------------------------------------------------------|
| `framework`  | Uso interativo local — operador no terminal chamando comandos.                               | Não inicia daemon, não exige `TELEGRAM_BOT_TOKEN`.                           |
| `autonomous` | Runtime contínuo — daemon + Telegram gateway + governance always-on.                         | Exige `TELEGRAM_BOT_TOKEN`; o wizard checa e avisa se ausente.               |

### Runtime profiles (advanced)

Além do profile de instalação (`framework` vs `autonomous`), existe um profile **runtime** opcional controlado por `OPENLIFE_RUNTIME_PROFILE`. Hoje só há um valor suportado:

| `OPENLIFE_RUNTIME_PROFILE` | Efeito |
|----------------------------|--------|
| `oauth-only` (case-insensitive) | `openlife doctor world` rebaixa quatro checks para **`info`** quando falham: `cli:ollama` (default: `blocker`) e `env:OPENAI_API_KEY` / `env:GEMINI_API_KEY` / `env:ANTHROPIC_API_KEY` (default: `warning`). |

Use quando o operador roda exclusivamente via CLIs autenticadas por OAuth (`claude`, `codex`, `gemini`) e não tem API keys nem Ollama local — essas ausências deixam de bloquear o doctor. **É apenas um classificador de severidade**: a fallback chain do `Brain.ts` continua igual; nenhum provider é ligado/desligado. Para detalhes (incluindo exemplo before/after) veja [`docs/install/runtime-profiles.md`](docs/install/runtime-profiles.md).

## 5) Instalação não-interativa

Para scripts, CI e automação, pule o wizard e use os flags diretos:

```bash
# Framework + claude-code (caminho mais comum)
openlife system setup --profile framework --host claude-code

# Autonomous + claude-code
openlife system setup --profile autonomous --host claude-code

# Forçar host reservado (state dir é criado, host install é skipped)
openlife system setup --profile framework --host gemini-cli
```

Explicação dos flags:

- `--profile <framework|autonomous>` — required. Veja seção 4.
- `--host <claude-code|gemini-cli|codex>` — opcional. Sem ele, usa `detectHostFromEnv()` → default `claude-code`.
- O comando imprime um JSON com o resultado por etapa (`stateDir`, `hostInstall`, `manifestPath`) para que CI processe.

## 6) Instalação recomendada (npm global)

```bash
npm install -g @openlife/cli
openlife --help
openlife init        # ou: openlife system setup --profile framework --host claude-code
```

## 7) Instalação sem global (npx)

```bash
npx @openlife/cli --help
npx @openlife/cli init
```

## 8) Instalação via código-fonte

```bash
git clone https://github.com/GOOODZ/openlife-core.git
cd openlife-core
npm install
npm run build
node bin/openlife.js init
```

## 9) Modo autônomo (após install)

### Instalação de artefatos do daemon

```bash
openlife agent install
```

### Start manual

```bash
openlife agent start
openlife agent status
```

### Bundle automatizado (local/WSL/Linux)

```bash
./scripts/openlife-autonomous-install.sh
```

## 10) Uninstall reversível

```bash
openlife system uninstall --host claude-code
```

**Removido** (apenas artefatos OpenLife):
- `.claude/agents/openlife-*.md` — somente arquivos com prefixo `openlife-`, agentes do usuário ficam intactos
- `.claude/commands/openlife/` — diretório inteiro (namespace nosso)
- MCP snippet staged

**Preservado** (intencionalmente, para evitar perda de dados):
- `.openlife/` — runtime state, missions, governance consents, learning, pilots
- `.catalog/` — catálogos runtime de agents/skills/squads
- `~/.claude.json` — config global do Claude Code (operator merges manualmente)

Para começar do zero: `rm -rf .openlife/` após o uninstall.

## 11) Linux server (systemd)

```bash
sudo cp scripts/openlife-agent.service.example /etc/systemd/system/openlife-agent.service
sudo systemctl daemon-reload
sudo systemctl enable --now openlife-agent
sudo systemctl status openlife-agent
```

## 12) Fallback (Supervisor)

```bash
sudo supervisorctl reread
sudo supervisorctl update
sudo supervisorctl status
```

Use o template: `scripts/openlife-agent.supervisord.conf.example`.

## 13) PATH e pós-instalação

O pacote executa checks automáticos no `postinstall`:
- valida Node/npm no PATH
- avisa sobre PATH global npm
- alerta sobre dependências opcionais (`claude`, `codex`, `gemini`)

Descobrir diretório de binários globais npm:

```bash
npm bin -g
```

## 14) Diagnóstico

Após o install, rode:

```bash
openlife system doctor
openlife system status
openlife models status
```

No Claude Code (depois de instalar para `claude-code`), use os slash commands:

- `/openlife:status`
- `/openlife:doctor`
- `/openlife:ask`
- `/openlife:dream`

## 15) Troubleshooting

### Problema 1 — Missing API keys (`OPENAI_API_KEY` / `ANTHROPIC_API_KEY` / `GEMINI_API_KEY`)

`openlife system doctor` reporta keys ausentes. Crie `.env` na raiz do projeto:

```bash
OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...
GEMINI_API_KEY=...
```

O wizard `openlife init` não bloqueia por falta de keys (`framework` profile roda com fallback), mas o autonomous profile precisa de pelo menos um provider funcional + Telegram.

### Problema 2 — Host não detectado / wizard escolhe o errado

Sintoma: `openlife init` propõe `claude-code` quando você queria `gemini-cli` (ou vice-versa).

Causa: env vars ausentes ou conflitantes. Verifique:

```bash
echo $CLAUDECODE $CLAUDE_PROJECT_DIR $GEMINI_CONFIG_DIR $CODEX_HOME
```

Solução: passe `--host` explicitamente no caminho não-interativo, ou aceite o default proposto pelo wizard e troque depois com um novo `openlife system setup`.

### Problema 3 — Install para `gemini-cli` ou `codex` retorna `skipped`

Esperado. Esses hosts estão **reservados para v1.1 follow-up** (ver seção 2). O `.openlife/` ainda é criado e o restante do sistema funciona — só não há agents/commands no host. Quando a Story 3.7 (gemini-cli/codex installers) for shipada, o mesmo comando passa a instalar sem alterações de flags.

## 16) Links úteis

- README: [README.md](README.md)
- Per-host docs: [docs/install/claude-code.md](docs/install/claude-code.md), [docs/install/gemini-cli.md](docs/install/gemini-cli.md), [docs/install/codex.md](docs/install/codex.md)
- Quickstart: [docs/quickstart.md](docs/quickstart.md)
- Comandos: [docs/commands.md](docs/commands.md)
- Autônomo: [docs/autonomous-install.md](docs/autonomous-install.md)
