Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 3 additions & 3 deletions CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -35,7 +35,7 @@ internal/
│ └── methods/ RPC handlers (chat, agents, sessions, config, skills, cron, pairing)
├── hooks/ Hook system for extensibility
├── http/ HTTP API (/v1/chat/completions, /v1/agents, /v1/skills, etc.)
├── i18n/ Message catalog: T(locale, key, args...) + per-locale catalogs (en/vi/zh)
├── i18n/ Message catalog: T(locale, key, args...) + per-locale catalogs (en/ko/vi/zh)
├── knowledgegraph/ Knowledge graph storage and traversal
├── mcp/ Model Context Protocol bridge/server
├── media/ Media handling utilities
Expand Down Expand Up @@ -89,7 +89,7 @@ ui/desktop/ Wails v2 desktop app (React frontend + embedded ga
- **Config:** JSON5 at `GOCLAW_CONFIG` env. Secrets in `.env.local` or env vars, never in config.json
- **Security:** Rate limiting, input guard (detection-only), CORS, shell deny patterns, SSRF protection, path traversal prevention, AES-256-GCM encryption. All security logs: `slog.Warn("security.*")`
- **Telegram formatting:** LLM output → `SanitizeAssistantContent()` → `markdownToTelegramHTML()` → `chunkHTML()` → `sendHTML()`. Tables rendered as ASCII in `<pre>` tags
- **i18n:** Web UI uses `i18next` with namespace-split locale files in `ui/web/src/i18n/locales/{lang}/`. Backend uses `internal/i18n` message catalog with `i18n.T(locale, key, args...)`. Locale propagated via `store.WithLocale(ctx)` — WS `connect` param `locale`, HTTP `Accept-Language` header. Supported: en (default), vi, zh. New user-facing strings: add key to `internal/i18n/keys.go`, add translations to all 3 catalog files. New UI strings: add key to all 3 locale dirs. Bootstrap templates (SOUL.md, etc.) stay English-only (LLM consumption).
- **i18n:** Web UI uses `i18next` with namespace-split locale files in `ui/web/src/i18n/locales/{lang}/`. Backend uses `internal/i18n` message catalog with `i18n.T(locale, key, args...)`. Locale propagated via `store.WithLocale(ctx)` — WS `connect` param `locale`, HTTP `Accept-Language` header. Supported: en (default), ko, vi, zh. New user-facing strings: add key to `internal/i18n/keys.go`, add translations to all 4 catalog files. New UI strings: add key to all 4 locale dirs. Bootstrap templates (SOUL.md, etc.) stay English-only (LLM consumption).

## Running

Expand Down Expand Up @@ -202,7 +202,7 @@ Go conventions to follow:
- Use `append(dst, src...)` instead of loop-based append
- Always handle errors; don't ignore return values
- **Migrations (dual-DB):** PostgreSQL and SQLite have **separate migration systems**. When adding schema changes: (1) PG: add SQL in `migrations/` + bump `RequiredSchemaVersion` in `internal/upgrade/version.go`. (2) SQLite: update `internal/store/sqlitestore/schema.sql` (full schema for fresh DBs) + add incremental patch in `schema.go` `migrations` map + bump `SchemaVersion` constant. **Always update both** — missing SQLite migrations cause desktop edition to crash on startup
- **i18n strings:** When adding user-facing error messages, add key to `internal/i18n/keys.go` and translations to `catalog_en.go`, `catalog_vi.go`, `catalog_zh.go`. For UI strings, add to all locale JSON files in `ui/web/src/i18n/locales/{en,vi,zh}/`
- **i18n strings:** When adding user-facing error messages, add key to `internal/i18n/keys.go` and translations to `catalog_en.go`, `catalog_ko.go`, `catalog_vi.go`, `catalog_zh.go`. For UI strings, add to all locale JSON files in `ui/web/src/i18n/locales/{en,ko,vi,zh}/`
- **SQL safety:** When implementing or modifying SQL store code (`store/pg/*.go`), always verify: (1) All user inputs use parameterized queries (`$1, $2, ...`), never string concatenation — prevents SQL injection. (2) Queries are optimized — no N+1 queries, no unnecessary full table scans. (3) WHERE clauses, JOINs, and ORDER BY columns use existing indices — check migration files for available indexes
- **DB query reuse:** Before adding a new DB query for key entities (teams, agents, sessions, users), check if the same data is already fetched earlier in the current flow/pipeline. Prefer passing resolved data through context, event payloads, or function params rather than re-querying. Duplicate queries waste DB resources and add latency
- **Solution design:** When designing a fix or feature, identify the root cause first — don't just patch symptoms. Think through production scenarios (high concurrency, multi-tenant isolation, failure cascades, long-running sessions) to ensure the solution holds up. Prefer explicit configuration over runtime heuristics. Prefer the simplest solution that addresses the root cause directly
Expand Down
32 changes: 32 additions & 0 deletions docs/18-http-api.md
Original file line number Diff line number Diff line change
Expand Up @@ -1032,6 +1032,37 @@ Exposes GoClaw tools to Claude CLI via streamable HTTP at `/mcp/bridge`. Only li

---

## 33. OpenClaw Migration

### OpenClaw Migration

| Method | Path | Description |
|--------|------|-------------|
| POST | `/v1/import/openclaw/scan` | Scan OpenClaw directory and preview migration |
| POST | `/v1/import/openclaw` | Execute migration for selected agents |

**POST /v1/import/openclaw/scan**

Scans an OpenClaw installation directory and returns a preview of what will be migrated.

Request:
- Body: `{"path": "~/.openclaw"}` (JSON)
- Auth: System owner required

Response: Agent list, channels, MCP servers, environment variables, warnings.

**POST /v1/import/openclaw**

Executes the migration for selected agents.

Request:
- Body: `{"path": "~/.openclaw", "selected_agents": ["bbojjak"], "include_credentials": true}` (JSON)
- Auth: System owner required

Response: Per-agent import results with summary counts.

---

## Error Responses

All endpoints return errors in a consistent JSON format:
Expand Down Expand Up @@ -1122,6 +1153,7 @@ GoClaw v3 introduces new HTTP endpoints for agent evolution metrics, episodic me
| `internal/http/skills_import.go` | Skills import |
| `internal/http/agents_export.go` | Agent export |
| `internal/http/agents_import.go` | Agent import |
| `internal/http/openclaw_import.go` | OpenClaw migration scan + import |
| `internal/http/contact_merge_handlers.go` | Contact merge/unmerge |
| `internal/http/user_search.go` | User search |
| `internal/http/secure_cli_user_credentials.go` | CLI per-user credentials |
Expand Down
3 changes: 3 additions & 0 deletions internal/http/agents.go
Original file line number Diff line number Diff line change
Expand Up @@ -160,6 +160,9 @@ func (h *AgentsHandler) RegisterRoutes(mux *http.ServeMux) {
mux.HandleFunc("GET /v1/teams/{id}/export/preview", h.adminMiddleware(h.handleTeamExportPreview))
mux.HandleFunc("GET /v1/teams/{id}/export", h.adminMiddleware(h.handleTeamExport))
mux.HandleFunc("POST /v1/teams/import", h.adminMiddleware(h.handleTeamImport))
// OpenClaw migration (system owner only)
mux.HandleFunc("POST /v1/import/openclaw/scan", h.adminMiddleware(h.handleOpenClawScan))
mux.HandleFunc("POST /v1/import/openclaw", h.adminMiddleware(h.handleOpenClawImport))
// Read-only (viewer+)
mux.HandleFunc("GET /v1/agents/{id}/codex-pool-activity", h.authMiddleware(h.handleCodexPoolActivity))
mux.HandleFunc("GET /v1/agents/{id}/instances", h.authMiddleware(h.handleListInstances))
Expand Down
Loading