Skip to content

INSTALL.md

Latest commit

 

History

History
211 lines (148 loc) · 9.6 KB

INSTALL.md

File metadata and controls

211 lines (148 loc) · 9.6 KB

HiMe — Detailed Install Guide

The README's Quick Start covers the happy path. This document covers everything else: manual Docker setup, native dev install, public deployment, IM gateway details, iOS build from source, and customization.

Table of Contents

Manual Docker setup

If you want full control over the wizard's choices, edit .env directly:

git clone https://github.com/thinkwee/HiMe.git HiMe
cd HiMe
cp .env.example .env
# Edit .env and at minimum set DEFAULT_LLM_PROVIDER + the matching *_API_KEY,
# and the Telegram or Feishu gateway block.
docker compose up --build -d

Endpoints when ready:

Native dev install

For developers iterating on the code (Python venv + Vite dev server, no Docker):

python3 -m venv .venv
source .venv/bin/activate
pip install -r backend/requirements.txt
cp .env.example .env  # configure
./hime.sh start  # starts backend + frontend + watch exporter

./hime.sh is the developer's native-mode CLI; full reference: ./hime.sh help. For backend-only work, python -m backend.main runs the API server in isolation; set HIME_DEV_RELOAD=true to enable Uvicorn auto-reload. The frontend lives in frontend/ (npm install && npm run dev). See docs/DEVELOPMENT.md for full developer onboarding.

Public deployment

Mostly defer to docs/DEPLOYMENT.md, but the critical steps are:

  1. Set a strong API_AUTH_TOKEN in .env (openssl rand -hex 32).
  2. Add your public origin to CORS_ORIGINS=.
  3. Reverse-proxy 8000 + 8765 behind nginx/Caddy with TLS — do NOT expose backend ports directly.
  4. Configure the iOS app with the same API_AUTH_TOKEN in Settings → Auth Token.

Full nginx + Caddy examples: docs/DEPLOYMENT.md.

IM gateway setup

HiMe chats with you exclusively through an IM gateway. The web dashboard does not have a chat UI. Pick Telegram, Feishu, or WeChat (or set up multiple, but most people pick one).

Telegram

  1. Open @BotFather → /newbot → follow prompts → save the bot token.

  2. Open @userinfobot → /start → save the chat_id (numeric).

  3. Send /start to your new bot once so Telegram allows the bot to message you back.

  4. In .env:

    TELEGRAM_GATEWAY_ENABLED=true
TELEGRAM_TOKEN=<bot_token>
CHAT_ID=<chat_id>
TELEGRAM_ALLOWED_CHAT_IDS=<chat_id>

Feishu (Lark)

  1. Visit open.feishu.cn → "开发者后台" → "创建企业自建应用".

  2. After creation: "凭证与基础信息" → save APP_ID (cli_...) and APP_SECRET.

  3. "权限管理" → grant im:message, im:message:send_as_bot, im:chat, im:chat:readonly (and others as needed).

  4. "事件订阅" → choose "长连接" (long-poll WebSocket) — no public URL needed.

  5. Publish the app draft and add it to a group chat.

  6. Get the open_chat_id (oc_...) by inviting the bot to a group and querying /open-apis/im/v1/chats with the bot token (or check the message events the bot receives).

  7. In .env:

    FEISHU_GATEWAY_ENABLED=true
FEISHU_APP_ID=cli_xxx
FEISHU_APP_SECRET=...
FEISHU_DEFAULT_CHAT_ID=oc_xxx
FEISHU_ALLOWED_CHAT_IDS=oc_xxx
FEISHU_TRANSPORT=ws

WeChat (Weixin ClawBot)

WeChat support is provided through Tencent's official ClawBot plugin (the iLink bot protocol at ilinkai.weixin.qq.com). No developer console, no API keys — just one QR scan from your personal WeChat. Limitations: text-only messages (no images yet), and proactive pushes require the user to have messaged the bot at least once.

  1. In .env, enable the gateway:

    WEIXIN_GATEWAY_ENABLED=true

    You can leave WEIXIN_ALLOWED_USER_IDS and WEIXIN_DEFAULT_USER_ID blank — by default the bot trusts whoever scanned the QR.

  2. From the host running HiMe, generate a bot_token by scanning a QR:

    # Native install
python -m backend.weixin.qr_login

# Docker install — run inside the backend container so the token lands
# at the path the gateway reads (./data/weixin_bot_token.json).
docker exec -it hime-backend python -m backend.weixin.qr_login

    The script prints both a URL and an ANSI-rendered QR (install qrcode if it's missing, but it ships in requirements.txt). On your phone open WeChat → Settings → Plugins → ClawBot and scan. The script will progress through wait → scaned → confirmed and write the token to ./data/weixin_bot_token.json.

  3. Restart HiMe — ./hime.sh restart for native, docker compose restart hime-backend for Docker. The backend log should print WeChat (Weixin) Gateway started.

  4. In WeChat, search for the ClawBot you just bound (it appears as a regular contact named "微信Claw" or similar) and send a message. The agent replies in the same chat.

The token is long-lived; re-run step 2 only if the backend log starts reporting iLink: 401 Unauthorized.

iOS app

Easy path

Install HiMe on the App Store. Open the app → Settings → enter your Server URL.

Server URL accepts:

  • localhost — iPhone simulator on the same Mac running the backend.
  • 192.168.1.100 — Mac/Linux backend on the same Wi-Fi LAN.
  • homelab.local — mDNS hostname on the same LAN (works if the host publishes via Avahi/Bonjour).
  • example.com — your public domain (with https://api.example.com and wss://watch.example.com derived automatically; requires reverse-proxy setup from docs/DEPLOYMENT.md).

If API_AUTH_TOKEN is set on the server, paste the same value into Settings → Auth Token.

Build from source

  1. Open ios/hime/hime.xcodeproj in Xcode 16+.
  2. cp ios/hime/Config.xcconfig.template ios/hime/Config.xcconfig and fill in DEVELOPMENT_TEAM (your Apple team ID) and BUNDLE_ID_PREFIX (e.g. com.example).
  3. ⌘R to build and run.

Customization

Switching LLM providers

.env controls everything:

DEFAULT_LLM_PROVIDER=anthropic
ANTHROPIC_API_KEY=sk-...
DEFAULT_MODEL=claude-sonnet-4-6   # optional override; omit to use provider mid-tier default

Supported providers (matches backend/agent/llm/__init__.py): gemini, openai, azure_openai, anthropic, mistral, groq, deepseek, xai, openrouter, perplexity, google_vertex, amazon_bedrock, minimax, vllm, zhipuai.

Each has a default model in .env.example under "Per-provider default models" — uncomment to override the default.

Fallback provider chain

To automatically retry against a backup provider when the primary returns 503/529/overloaded three times in a row:

FALLBACK_LLM_PROVIDER=openai
FALLBACK_LLM_MODEL=gpt-5.4-mini

Reasoning effort (GPT-5 family)

OPENAI_REASONING_EFFORT=low   # minimal | low | medium | high | xhigh | none

For agentic tool-calling, recommended low or minimal. Default medium is overkill for HiMe's loops.

Skills

Skills are reusable analysis playbooks (.md files) under ./skills/. The registry also auto-scans ~/.hime/skills so you can add personal skills outside the repo. Toggle individual skills via the dashboard's Skills tab.

Personalised pages

The agent can generate single-page apps on demand using the create_page tool. Pages live under data/personalised_pages/<page_id>/ and use the bundled HimeUI JS component library at data/personalised_pages/_shared/. Spec: prompts/create_page_guide.md.

Troubleshooting

Symptom Likely cause Fix
setup.sh: Docker daemon not running Docker Desktop not started Start Docker Desktop and re-run ./setup.sh
setup.sh finishes but nothing responds Containers crashed docker compose logs -f --tail=100
iOS app shows "Cannot connect" Wrong Server URL or firewall curl http://<host>:8765/ping from another LAN device
401 Unauthorized from API API_AUTH_TOKEN mismatch Set the same value in iOS app's Settings → Auth Token
Telegram bot silent TELEGRAM_ALLOWED_CHAT_IDS empty Add your chat_id to the allowlist (setup.sh handles this)
Feishu card buttons do nothing Feishu Card Request URL not set Set the public callback URL in Feishu console — see docs/DEPLOYMENT.md
WeChat bot silent after restart Token file missing or expired Re-run python -m backend.weixin.qr_login and re-scan; check that ./data/weixin_bot_token.json exists
WeChat iLink: 401 Unauthorized in logs bot_token revoked Re-run the QR login; bot tokens stay valid until you log out from WeChat → Settings → Plugins → ClawBot
WeChat agent never sees the message Gateway disabled or not loaded docker exec hime-backend env | grep WEIXIN_GATEWAY_ENABLED — must be true; trailing # comments after = get treated as the value, strip them

For deeper debugging see logs in ./logs/backend.log (or docker compose logs backend).