diff --git a/README.md b/README.md index 9d5f48c..15c2465 100644 --- a/README.md +++ b/README.md @@ -56,7 +56,6 @@ The repository uses a **split-service runtime model** for local development and | `backend.apps.trading_service` | `:8001` | Read-only trading data APIs | | `backend.apps.news_service` | `:8002` | Read-only explain/news APIs | | `backend.apps.runtime_service` | `:8003` | Runtime lifecycle APIs | -| `backend.apps.openclaw_service` | `:8004` | Read-only OpenClaw facade | | WebSocket gateway | `:8765` | Live event/feed channel for the frontend | ### Active Runtime Path diff --git a/README_zh.md b/README_zh.md index dafd09c..39fc776 100644 --- a/README_zh.md +++ b/README_zh.md @@ -54,7 +54,6 @@ | `backend.apps.trading_service` | `:8001` | 只读交易数据 API | | `backend.apps.news_service` | `:8002` | 只读 explain/news API | | `backend.apps.runtime_service` | `:8003` | 运行时生命周期 API | -| `backend.apps.openclaw_service` | `:8004` | 只读 OpenClaw facade | | WebSocket gateway | `:8765` | 前端实时事件/feed 通道 | ### 活跃运行时路径 diff --git a/deploy/README.md b/deploy/README.md index e53d891..a257956 100644 --- a/deploy/README.md +++ b/deploy/README.md @@ -190,7 +190,7 @@ The `none` mode (direct execution) is for development only and displays a securi The checked-in deployment artifacts do not currently document or automate: -- split FastAPI service deployment on `8000` to `8004` +- split FastAPI service deployment on `8000` to `8003` - OpenClaw gateway deployment on `18789` - database backup/retention workflows - frontend build/publish steps diff --git a/docs/compat-removal-plan.md b/docs/compat-removal-plan.md index 36d9d07..ad59e91 100644 --- a/docs/compat-removal-plan.md +++ b/docs/compat-removal-plan.md @@ -61,7 +61,7 @@ backward-compatible behavior while migration settles. - OpenClaw currently appears through two different shapes: - WebSocket gateway integration on `:18789` - - optional REST surface at `backend.apps.openclaw_service` on `:8004` + - These are both valid, but they are not the same surface and should not be documented as interchangeable. diff --git a/docs/current-architecture.md b/docs/current-architecture.md index 76b064c..2fd43ba 100644 --- a/docs/current-architecture.md +++ b/docs/current-architecture.md @@ -83,7 +83,6 @@ Current service surfaces: - read-only explain/news APIs - `backend.apps.runtime_service` on `:8003` - runtime lifecycle and gateway process management -- `backend.apps.openclaw_service` on `:8004` - optional OpenClaw REST facade - gateway WebSocket on `:8765` - live feed/event transport and pipeline coordination diff --git a/docs/legacy-inventory.md b/docs/legacy-inventory.md index 7bc3202..c0a60dd 100644 --- a/docs/legacy-inventory.md +++ b/docs/legacy-inventory.md @@ -65,7 +65,7 @@ topology and service-routing policy are frozen. | Surface | Current State | Decision Needed | |---------|---------------|-----------------| -| OpenClaw dual integration | REST facade (`:8004`) + Gateway WebSocket (`:18789`) | Which surface is the long-term contract? | +| OpenClaw integration | Gateway WebSocket (port 18789) | Stable — REST facade removed | | Env-dependent service fallbacks | `TRADING_SERVICE_URL`, `NEWS_SERVICE_URL` fallbacks to local modules | Remove fallbacks and require explicit URLs? | | Split-service production deploy | Docs show gateway-first, dev uses split-service | Align production with dev topology? | @@ -104,70 +104,6 @@ python3 -m backend.main \ **Ownership**: ops-team **Status**: Stable and intentional -### OpenClaw Dual Integration - -Two different integration surfaces exist for OpenClaw: - -#### A. REST Facade (Port 8004) - -**File**: `backend/apps/openclaw_service.py` -**Routes**: `backend/api/openclaw.py` (prefix `/api/openclaw`) - -**Purpose**: -- Read-only OpenClaw CLI integration -- Typed Pydantic models for all responses -- Direct HTTP/REST access to OpenClaw state - -**Use when**: -- You need typed, stable API contracts -- You want to poll OpenClaw status from external systems -- You need programmatic access without WebSocket complexity - -**Example**: -```bash -curl http://localhost:8004/api/openclaw/status -``` - -#### B. Gateway WebSocket Integration (Port 18789) - -**Files**: -- `backend/services/gateway_openclaw_handlers.py` -- `shared/client/openclaw_websocket_client.py` - -**Purpose**: -- Real-time bidirectional communication with OpenClaw -- Event streaming and live updates -- Integration with Gateway event flow - -**Use when**: -- You need real-time updates -- You're already connected to Gateway WebSocket -- You want event-driven rather than polling architecture - -**Example**: -```javascript -// Frontend connects to ws://localhost:18789 -const ws = new WebSocket('ws://localhost:18789'); -``` - -#### Key Differences - -| Aspect | REST Facade (8004) | Gateway WebSocket (18789) | -|--------|-------------------|---------------------------| -| Protocol | HTTP/REST | WebSocket | -| Access pattern | Request/response | Event-driven | -| Typing | Pydantic models | JSON messages | -| Real-time | Polling required | Push notifications | -| Use case | External integrations, scripts | Frontend, live dashboards | -| Stability | Higher (explicit contracts) | Evolving with Gateway | - -**Decision needed**: Which surface becomes the long-term contract? -- REST facade is more stable but read-only -- WebSocket integration is more capable but tied to Gateway evolution - -**Ownership**: runtime-team -**Status**: Deferred until topology final - ### Dashboard Export Layer **Files**: `runs//team_dashboard/*.json` diff --git a/services/README.md b/services/README.md index d8d90f3..6baebb0 100644 --- a/services/README.md +++ b/services/README.md @@ -20,7 +20,6 @@ and the next-step execution plan lives at | `backend.apps.trading_service` | `8001` | Read-only trading data APIs such as prices, financials, insider trades | | `backend.apps.news_service` | `8002` | Read-only explain/news APIs such as story, similar days, range explain | | `backend.apps.runtime_service` | `8003` | Runtime lifecycle APIs under `/api/runtime/*` | -| `backend.apps.openclaw_service` | `8004` | Read-only OpenClaw REST facade | | Gateway (`backend.main`) | `8765` | WebSocket feed, runtime event stream, pipeline execution | | OpenClaw Gateway | `18789` | External OpenClaw WebSocket endpoint consumed by 大时代 gateway | @@ -63,7 +62,7 @@ That script starts: - `runtime_service` on `8003` - 大时代 gateway on `8765` (as subprocess of runtime_service) -It does **not** start `openclaw_service` on `8004`. +It does **not** start. Instead, the gateway expects an OpenClaw WebSocket server to already be available at `ws://localhost:18789` unless you override the OpenClaw gateway @@ -98,7 +97,6 @@ curl -X POST http://localhost:8003/api/runtime/start \ Optional OpenClaw REST surface: ```bash -python -m uvicorn backend.apps.openclaw_service:app --host 0.0.0.0 --port 8004 --reload ``` ## Runtime Responsibilities @@ -194,7 +192,6 @@ RUNTIME_SERVICE_URL=http://localhost:8003 OPENCLAW_SERVICE_URL=http://localhost:18789 ``` -Note that `OPENCLAW_SERVICE_URL` currently points at the OpenClaw gateway origin used by the live WebSocket bridge, not the optional REST app on `:8004`. ### Frontend service targets @@ -229,7 +226,6 @@ There are two separate OpenClaw integration surfaces in this repo: - OpenClaw WebSocket gateway on `:18789` - used directly by `backend/services/gateway.py` - this is what `start-dev.sh` assumes exists -- `backend.apps.openclaw_service` on `:8004` - optional REST facade over OpenClaw CLI-backed reads - useful for typed client access and service-level testing @@ -256,8 +252,6 @@ backend.apps.trading_service backend.apps.news_service └─ read-only explain/news contract -backend.apps.openclaw_service - └─ optional OpenClaw REST facade backend.gateway_server └─ Gateway subprocess entry point (run-scoped)