Bắt đầu

Bestie là AI companion local-first. Bạn cài Bestie trên máy của mình, kết nối một LLM provider được bestie llm setup hỗ trợ, rồi dùng lệnh bestie để thiết lập, chẩn đoán và chat.

Cần chuẩn bị

• Node.js 24+ và npm có quyền cài package global.
• Một LLM provider được hỗ trợ, ví dụ OpenAI, Anthropic, Gemini, OpenRouter, Groq, Ollama hoặc custom compatible endpoint.
• API key lưu trong .bestie/.env, không lưu trong config.json.
• Để sau cũng được: Telegram bot token nếu muốn dùng kênh Telegram.

Tối thiểu, file .bestie/.env cần có biến môi trường được LLM profile đang dùng trỏ tới bằng apiKeyEnv:

OPENAI_API_KEY=sk-your-key-here

Dùng key thật và tên biến đúng với provider của bạn. Đừng nhét secret vào config.json, không là tự bắn vào chân rồi lại hỏi mèo vì sao đau.

Cài từ npm

Bestie đã được publish trên npm với package bestie-agent. Cài global rồi chạy onboarding và Doctor:

npm install -g bestie-agent
bestie onboard
bestie doctor

Package global sẽ cung cấp lệnh bestie. Chỉ dùng source installer khi phát triển Bestie hoặc cần test hành vi installer từ checkout.

Lệnh hay dùng

bestie --help
bestie onboard
bestie onboard --skip-provider-test
bestie llm providers
bestie llm setup --provider openai --set-default
bestie llm test --model openai/gpt-4.1
bestie chat
bestie status
bestie logs
bestie doctor
bestie doctor --json
bestie doctor --fix

Trong terminal chat:

/help
/status
/memory
/memory pause
/memory resume
/pending

Kiểm tra setup

Sau onboarding, chạy:

bestie doctor
bestie status

Khi Doctor pass, mở terminal chat:

bestie chat

Thử một câu nhỏ trước:

Tóm tắt trạng thái hiện tại của bạn trong một câu.

Nếu bạn dùng bestie onboard --skip-provider-test, coi setup vẫn chưa hoàn tất cho tới khi bestie doctor pass mà không còn lỗi provider. Flag này chỉ nên dùng khi provider tạm thời không reachable.

Lỗi provider thường gặp

Nên bắt đầu bằng:

bestie doctor
bestie status

• Provider request timed out: endpoint phản hồi quá chậm. Thử lại, đổi model nhanh hơn hoặc tăng llm.timeoutMs.
• Could not reach the provider endpoint: kiểm tra baseUrl trong LLM profile đang dùng, mạng, DNS, VPN/proxy và trạng thái provider.
• Provider authentication failed: kiểm tra API key trong .bestie/.env và apiKeyEnv trong LLM profile đang dùng.
• Provider rate limit reached: chờ hoặc kiểm tra quota/billing.
• Provider returned an unusable response: kiểm tra model ref đã chọn có được provider profile hỗ trợ không.

Ví dụ tăng timeout:

{
  "llm": {
    "timeoutMs": 120000
  }
}

Timeout mặc định là 300000 ms. Chỉ giảm hoặc tăng giá trị này khi provider và điều kiện vận hành của bạn cần. Retry mặc định khá dè chừng: llm.maxRetries là 1 và llm.retryDelayMs là 500 ms.