📘 PaleoClaw 部署与使用手册

本手册提供从零到生产可用的完整部署流程，覆盖 Windows / macOS / Linux，包含快速安装、团队部署、反向代理、HTTPS、升级、备份与排障。

📘 PaleoClaw Deployment & Operations Manual

This guide covers end-to-end deployment for Windows / macOS / Linux, including quick install, team setup, reverse proxy, HTTPS, upgrades, backup, and troubleshooting.

📘 PaleoClaw 導入・運用マニュアル

Windows / macOS / Linux 向けに、クイック導入から本番運用までを網羅。リバースプロキシ、HTTPS、更新、バックアップ、トラブル対応を詳しく解説します。

CLI + Gateway Deployment Handbook Research-ready

1) 概览

PaleoClaw 是面向古生物学研究场景的 AI 研究代理。部署后可进行文献检索、PBDB 查询、分类学验证、地层分析、形态测量与记忆检索。

部署方式适用场景复杂度
官方脚本个人学习/快速体验低
npm/pnpm实验室日常使用中
源码部署二次开发/定制中-高
Docker团队服务化/隔离运维高

1) Overview

PaleoClaw is an AI research agent for paleontology workflows: literature search, PBDB queries, taxonomy checks, stratigraphic context, morphometric analysis, and memory retrieval.

MethodBest forComplexity
Official installerPersonal learning / quick trialLow
npm/pnpmLab daily operationsMedium
From sourceCustomization / developmentMed-High
DockerTeam service deploymentHigh

1) 概要

PaleoClaw は古生物学向け AI 研究エージェントです。文献検索、PBDB照会、分類検証、層序解析、形態計測、記憶検索を統合します。

方式用途難易度
公式インストーラ個人学習 / 迅速評価低
npm/pnpm研究室の通常運用中
ソース導入カスタマイズ / 開発中〜高
Dockerチームのサービス運用高

2) 环境要求

  • Node.js >= 22.12.0
  • Git（源码部署需要）
  • curl（脚本安装需要）
  • 建议：4GB+ 内存，10GB+ 磁盘空间
node -v
git --version
curl --version
建议：科研环境中请固定 Node 版本，并将命令输出保存到实验记录。

2) Requirements

  • Node.js >= 22.12.0
  • Git (for source deployment)
  • curl (for installer scripts)
  • Recommended: 4GB+ RAM, 10GB+ storage
node -v
git --version
curl --version
Tip: Pin Node version in research environments and keep command outputs in project logs.

2) 前提条件

  • Node.js >= 22.12.0
  • Git（ソース導入時）
  • curl（インストーラスクリプト利用時）
  • 推奨：メモリ4GB以上、空き容量10GB以上
node -v
git --version
curl --version
推奨：研究運用では Node バージョンを固定し、実行ログを保存してください。

3) 快速部署（推荐入门）

macOS / Linux / WSL

curl -fsSL https://paleoclaw.ai/install.sh | bash

Windows PowerShell

iwr -useb https://paleoclaw.ai/install.ps1 | iex

初始化与验证

paleoclaw profile init
paleoclaw config set --ai-provider openai --ai-model gpt-5-mini
paleoclaw --version
paleoclaw doctor

3) Quick Deployment (Recommended)

macOS / Linux / WSL

curl -fsSL https://paleoclaw.ai/install.sh | bash

Windows PowerShell

iwr -useb https://paleoclaw.ai/install.ps1 | iex

Initialize & Verify

paleoclaw profile init
paleoclaw config set --ai-provider openai --ai-model gpt-5-mini
paleoclaw --version
paleoclaw doctor

3) クイック導入（推奨）

macOS / Linux / WSL

curl -fsSL https://paleoclaw.ai/install.sh | bash

Windows PowerShell

iwr -useb https://paleoclaw.ai/install.ps1 | iex

初期化と確認

paleoclaw profile init
paleoclaw config set --ai-provider openai --ai-model gpt-5-mini
paleoclaw --version
paleoclaw doctor

4) npm / pnpm 标准部署

npm 全局安装

npm install -g paleoclaw@latest
paleoclaw onboard --install-daemon

pnpm 全局安装

pnpm add -g paleoclaw@latest
pnpm approve-builds -g
paleoclaw onboard --install-daemon
说明：如果提示命令不存在，请检查全局 PATH（npm prefix -g / pnpm root -g）。

4) Standard Deployment via npm/pnpm

npm global install

npm install -g paleoclaw@latest
paleoclaw onboard --install-daemon

pnpm global install

pnpm add -g paleoclaw@latest
pnpm approve-builds -g
paleoclaw onboard --install-daemon
Note: If command is not found, verify global PATH (npm prefix -g / pnpm root -g).

4) npm / pnpm 標準導入

npm グローバル導入

npm install -g paleoclaw@latest
paleoclaw onboard --install-daemon

pnpm グローバル導入

pnpm add -g paleoclaw@latest
pnpm approve-builds -g
paleoclaw onboard --install-daemon
注記：コマンド未検出の場合、グローバルPATHを確認してください。

5) 源码部署（开发/定制）

  1. 克隆仓库并进入目录
  2. 安装依赖并构建
  3. 链接到全局命令
git clone https://github.com/syxscott/PaleoClaw.git
cd PaleoClaw
pnpm install
pnpm ui:build
pnpm build
pnpm link --global
注意：源码部署适合开发人员。升级时建议先拉取变更再重新 build/link。

5) Source Deployment (Dev/Custom)

  1. Clone repository and enter directory
  2. Install dependencies and build
  3. Link CLI globally
git clone https://github.com/syxscott/PaleoClaw.git
cd PaleoClaw
pnpm install
pnpm ui:build
pnpm build
pnpm link --global
Warning: Source deployment is for developers; rebuild/relink after pulling updates.

5) ソース導入（開発・拡張向け）

  1. リポジトリをクローンして移動
  2. 依存導入とビルド
  3. CLI をグローバルリンク
git clone https://github.com/syxscott/PaleoClaw.git
cd PaleoClaw
pnpm install
pnpm ui:build
pnpm build
pnpm link --global
注意：開発向けの方式です。更新後は再ビルド/再リンクを実施してください。

6) Docker 部署

适合团队化、隔离化、可迁移部署。

git clone https://github.com/syxscott/PaleoClaw.git
cd PaleoClaw
./docker-setup.sh
# 或使用
# docker compose up -d
  • 建议挂载配置目录与日志目录，便于备份和审计
  • 生产环境请固定镜像版本，不建议直接 latest

6) Docker Deployment

Best for team, isolated, and portable deployments.

git clone https://github.com/syxscott/PaleoClaw.git
cd PaleoClaw
./docker-setup.sh
# or
# docker compose up -d
  • Mount config/log volumes for backup and auditability
  • Pin image versions in production; avoid unpinned latest

6) Docker 導入

チーム運用・分離実行・移植性重視の環境に最適です。

git clone https://github.com/syxscott/PaleoClaw.git
cd PaleoClaw
./docker-setup.sh
# または
# docker compose up -d
  • 設定とログのボリュームをマウントして保全性を確保
  • 本番ではイメージタグ固定を推奨

7) 生产环境部署（详细）

7.1 系统服务（Linux + systemd）

将 gateway 作为系统服务托管，确保开机自启与故障恢复。

sudo tee /etc/systemd/system/paleoclaw-gateway.service >/dev/null <<'EOF'
[Unit]
Description=PaleoClaw Gateway
After=network.target

[Service]
Type=simple
User=ubuntu
WorkingDirectory=/home/ubuntu
ExecStart=/usr/bin/env paleoclaw gateway run --bind loopback --port 18789 --force
Restart=always
RestartSec=3
Environment=OPENCLAW_PROFILE=prod

[Install]
WantedBy=multi-user.target
EOF

sudo systemctl daemon-reload
sudo systemctl enable paleoclaw-gateway
sudo systemctl start paleoclaw-gateway
sudo systemctl status paleoclaw-gateway

7.2 Nginx 反向代理 + HTTPS

server {
  listen 80;
  server_name paleoclaw.example.com;
  return 301 https://$host$request_uri;
}

server {
  listen 443 ssl http2;
  server_name paleoclaw.example.com;

  ssl_certificate /etc/letsencrypt/live/paleoclaw.example.com/fullchain.pem;
  ssl_certificate_key /etc/letsencrypt/live/paleoclaw.example.com/privkey.pem;

  location / {
    proxy_pass http://127.0.0.1:18789;
    proxy_http_version 1.1;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
  }
}
建议：公网部署务必启用 HTTPS 与访问控制，不要直接裸露管理端口。

7) Production Deployment (Detailed)

7.1 System service (Linux + systemd)

Run gateway as a managed service for auto-start and resilience.

sudo tee /etc/systemd/system/paleoclaw-gateway.service >/dev/null <<'EOF'
[Unit]
Description=PaleoClaw Gateway
After=network.target

[Service]
Type=simple
User=ubuntu
WorkingDirectory=/home/ubuntu
ExecStart=/usr/bin/env paleoclaw gateway run --bind loopback --port 18789 --force
Restart=always
RestartSec=3
Environment=OPENCLAW_PROFILE=prod

[Install]
WantedBy=multi-user.target
EOF

sudo systemctl daemon-reload
sudo systemctl enable paleoclaw-gateway
sudo systemctl start paleoclaw-gateway
sudo systemctl status paleoclaw-gateway

7.2 Nginx reverse proxy + HTTPS

server {
  listen 80;
  server_name paleoclaw.example.com;
  return 301 https://$host$request_uri;
}

server {
  listen 443 ssl http2;
  server_name paleoclaw.example.com;

  ssl_certificate /etc/letsencrypt/live/paleoclaw.example.com/fullchain.pem;
  ssl_certificate_key /etc/letsencrypt/live/paleoclaw.example.com/privkey.pem;

  location / {
    proxy_pass http://127.0.0.1:18789;
    proxy_http_version 1.1;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
  }
}
Best practice: Always enforce HTTPS and access control for public deployments.

7) 本番導入（詳細）

7.1 systemd サービス化（Linux）

Gateway をサービス化し、自動起動と障害復旧を実現します。

sudo tee /etc/systemd/system/paleoclaw-gateway.service >/dev/null <<'EOF'
[Unit]
Description=PaleoClaw Gateway
After=network.target

[Service]
Type=simple
User=ubuntu
WorkingDirectory=/home/ubuntu
ExecStart=/usr/bin/env paleoclaw gateway run --bind loopback --port 18789 --force
Restart=always
RestartSec=3
Environment=OPENCLAW_PROFILE=prod

[Install]
WantedBy=multi-user.target
EOF

sudo systemctl daemon-reload
sudo systemctl enable paleoclaw-gateway
sudo systemctl start paleoclaw-gateway
sudo systemctl status paleoclaw-gateway

7.2 Nginx リバースプロキシ + HTTPS

server {
  listen 80;
  server_name paleoclaw.example.com;
  return 301 https://$host$request_uri;
}

server {
  listen 443 ssl http2;
  server_name paleoclaw.example.com;

  ssl_certificate /etc/letsencrypt/live/paleoclaw.example.com/fullchain.pem;
  ssl_certificate_key /etc/letsencrypt/live/paleoclaw.example.com/privkey.pem;

  location / {
    proxy_pass http://127.0.0.1:18789;
    proxy_http_version 1.1;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
  }
}
推奨：公開運用では HTTPS とアクセス制御を必ず有効化してください。

8) 更新、备份与回滚

更新

npm install -g paleoclaw@latest
paleoclaw --version
paleoclaw doctor

备份建议

  • 备份 ~/.paleoclaw/（含 profile、memory、配置）
  • 备份反向代理配置与证书路径
  • 每次升级前创建时间戳备份包

回滚

npm install -g paleoclaw@1.4.0
# 或安装你验证过的稳定版本

8) Upgrade, Backup, Rollback

Upgrade

npm install -g paleoclaw@latest
paleoclaw --version
paleoclaw doctor

Backup

  • Back up ~/.paleoclaw/ (profile, memory, config)
  • Back up reverse proxy configs and cert paths
  • Create timestamped snapshots before every upgrade

Rollback

npm install -g paleoclaw@1.4.0
# or any validated stable version

8) 更新・バックアップ・ロールバック

更新

npm install -g paleoclaw@latest
paleoclaw --version
paleoclaw doctor

バックアップ

  • ~/.paleoclaw/（profile, memory, config）を保存
  • リバースプロキシ設定と証明書パスを保存
  • 更新前に必ずスナップショットを取得

ロールバック

npm install -g paleoclaw@1.4.0
# 検証済みの安定版へ戻す

9) 常见问题排查

问题 A：`paleoclaw` 命令找不到

  • 检查 npm/pnpm 全局路径是否在 PATH
  • 重新打开终端或刷新 shell 配置

问题 B：Gateway 启动失败

  • 检查端口占用（18789）
  • 执行 paleoclaw doctor 获取诊断建议

问题 C：外部 API 调用失败

  • 确认网络可访问与 API 密钥配置正确
  • 检查是否存在代理、防火墙或证书问题
若提交 issue，请附带：系统版本、Node 版本、完整错误日志、复现步骤。

9) Troubleshooting

Issue A: command not found

  • Verify npm/pnpm global path is in PATH
  • Re-open terminal or reload shell profile

Issue B: gateway fails to start

  • Check port conflicts (18789)
  • Run paleoclaw doctor for diagnostics

Issue C: API requests fail

  • Validate network reachability and API key settings
  • Check proxy/firewall/certificate issues
When filing issues, include OS, Node version, full logs, and reproducible steps.

9) トラブルシューティング

問題A：コマンド未検出

  • npm/pnpm のグローバルPATHを確認
  • ターミナル再起動またはシェル再読込

問題B：Gateway 起動失敗

  • ポート競合（18789）を確認
  • paleoclaw doctor を実行して診断

問題C：外部API接続失敗

  • ネットワーク到達性とAPIキー設定を確認
  • プロキシ/FW/証明書設定を確認
Issue登録時は OS / Node / 完全ログ / 再現手順を添付してください。

10) 上线前检查清单

  • ☐ `paleoclaw --version` 输出正确
  • ☐ `paleoclaw doctor` 无关键错误
  • ☐ profile 与 memory 已初始化并可读写
  • ☐ Gateway 可启动，端口与代理连通
  • ☐ HTTPS 与访问控制已启用（生产）
  • ☐ 备份策略与回滚方案已验证

10) Go-Live Checklist

  • ☐ `paleoclaw --version` returns expected version
  • ☐ `paleoclaw doctor` has no critical errors
  • ☐ profile/memory initialized and writable
  • ☐ Gateway and proxy routing validated
  • ☐ HTTPS + access control enabled (production)
  • ☐ backup and rollback tested

10) 本番前チェックリスト

  • ☐ `paleoclaw --version` を確認
  • ☐ `paleoclaw doctor` に重大エラーなし
  • ☐ profile/memory の初期化と書込確認
  • ☐ Gateway とプロキシ疎通確認
  • ☐ HTTPS とアクセス制御を有効化
  • ☐ バックアップとロールバック検証済み