@yahaha-studio/kichi-forwarder 0.1.1-beta.8 → 0.1.2-beta.1

package/config/environments.json

@@ -0,0 +1,5 @@
+{
+  "steam": "focus-wss.yahaha.com",
+  "steam-playtest": "focus-steam-playtest-wss-int.yahaha.com",
+  "test": null
+}

package/index.ts

@@ -15,11 +15,14 @@ import type {
   Album,
   ClockAction,
   ClockConfig,
+  KichiEnvironment,
+  KichiEnvironmentsConfig,
   KichiStaticConfig,
   PomodoroPhase,
   PoseType,
 } from "./src/types.js";
 const BUNDLED_STATIC_CONFIG_PATH = new URL("./config/kichi-config.json", import.meta.url);
+const BUNDLED_ENVIRONMENTS_CONFIG_PATH = new URL("./config/environments.json", import.meta.url);
 const FIXED_HOOK_STATUSES: Record<string, ActionResult> = {
   beforePromptBuild: {
     poseType: "sit",
@@ -200,6 +203,52 @@ function loadStaticConfig(): KichiStaticConfig {
   return cachedStaticConfig;
 }
 
+const VALID_ENVIRONMENTS: KichiEnvironment[] = ["steam", "steam-playtest", "test"];
+let cachedEnvironmentsConfig: KichiEnvironmentsConfig | null = null;
+let cachedEnvironmentsConfigMtime = 0;
+
+function getEnvironmentsConfigPath(): string {
+  return fileURLToPath(BUNDLED_ENVIRONMENTS_CONFIG_PATH);
+}
+
+function loadEnvironmentsConfig(): KichiEnvironmentsConfig {
+  const configPath = getEnvironmentsConfigPath();
+  const stat = fs.statSync(configPath);
+  if (cachedEnvironmentsConfig && stat.mtimeMs === cachedEnvironmentsConfigMtime) {
+    return cachedEnvironmentsConfig;
+  }
+  const raw = JSON.parse(fs.readFileSync(configPath, "utf-8")) as unknown;
+  if (!raw || typeof raw !== "object") {
+    throw new Error("config/environments.json must be a valid object");
+  }
+  const config = raw as Record<string, unknown>;
+  for (const env of VALID_ENVIRONMENTS) {
+    if (!(env in config)) {
+      throw new Error(`config/environments.json missing environment "${env}"`);
+    }
+    const value = config[env];
+    if (value !== null && typeof value !== "string") {
+      throw new Error(`config/environments.json environment "${env}" must be a string or null`);
+    }
+  }
+  cachedEnvironmentsConfig = config as KichiEnvironmentsConfig;
+  cachedEnvironmentsConfigMtime = stat.mtimeMs;
+  return cachedEnvironmentsConfig;
+}
+
+function isKichiEnvironment(value: unknown): value is KichiEnvironment {
+  return typeof value === "string" && VALID_ENVIRONMENTS.includes(value as KichiEnvironment);
+}
+
+function resolveEnvironmentHost(environment: KichiEnvironment): { host?: string; error?: string } {
+  const config = loadEnvironmentsConfig();
+  const configuredHost = config[environment];
+  if (typeof configuredHost === "string" && configuredHost.trim()) {
+    return { host: configuredHost };
+  }
+  return { error: `environment "${environment}" has no configured host — update config/environments.json first` };
+}
+
 function sendStatusUpdate(service: KichiForwarderService, status: ActionResult): void {
   const actionDefinition = getActionDefinition(status.poseType, status.action);
   service.sendStatus(
@@ -902,18 +951,6 @@ function buildMusicAlbumToolDescription(): string {
   ].join("\n");
 }
 
-function isKichiHost(value: unknown): value is string {
-  if (typeof value !== "string") {
-    return false;
-  }
-  const trimmed = value.trim();
-  return trimmed.length > 0
-    && !trimmed.includes("://")
-    && !trimmed.includes("/")
-    && !trimmed.includes("?")
-    && !trimmed.includes("#");
-}
-
 function buildMusicTitlesDescription(): string {
   return [
     "Track names are injected into this tool schema from the static config bundled with the plugin package.",
@@ -1006,10 +1043,12 @@ function createAgentScopedTool(
   factory: (service: KichiForwarderService, ctx: OpenClawPluginToolContext) => AnyAgentTool,
 ) {
   return (ctx: OpenClawPluginToolContext) => {
-    const service = runtimeManager.getRuntime(resolveToolLocator(ctx));
-    if (!service) {
+    const locator = resolveToolLocator(ctx);
+    const agentId = runtimeManager.resolveRuntimeAgentId(locator);
+    if (!agentId) {
       throw new Error("Failed to resolve agent-scoped Kichi runtime");
     }
+    const service = runtimeManager.getRuntime(locator) ?? runtimeManager.createRuntimeForAgent(agentId);
     return factory(service, ctx);
   };
 }
@@ -1045,6 +1084,11 @@ const plugin = {
       id: "kichi-forwarder",
       start: (ctx) => {
         parse(ctx.config.plugins?.entries?.["kichi-forwarder"]?.config);
+        runtimeManager.setEnvironmentHostResolver((environment) => {
+          const config = loadEnvironmentsConfig();
+          const host = config[environment];
+          return typeof host === "string" && host.trim() ? host : null;
+        });
         runtimeManager.initializeStartupRuntimes();
       },
       stop: () => {
@@ -1124,27 +1168,34 @@ const plugin = {
       return ({
       name: "kichi_switch_host",
       description:
-        "Switch Kichi runtime host and reconnect immediately without restarting the gateway.",
+        "Switch Kichi runtime environment and reconnect immediately without restarting the gateway. Host is resolved from config/environments.json.",
       parameters: {
         type: "object",
         properties: {
-          host: {
+          environment: {
             type: "string",
-            description: "Target Kichi host, for example your.kichi.host or 127.0.0.1",
+            enum: VALID_ENVIRONMENTS,
+            description: "Target environment: steam, steam-playtest, or test",
           },
         },
-        required: ["host"],
+        required: ["environment"],
       },
       execute: async (_toolCallId, params) => {
-        const host = (params as { host?: unknown } | null)?.host;
-        if (!isKichiHost(host)) {
-          return { success: false, error: "host must be a non-empty hostname without protocol or path" };
+        const environment = (params as { environment?: unknown } | null)?.environment;
+        if (!isKichiEnvironment(environment)) {
+          return { success: false, error: `environment must be one of: ${VALID_ENVIRONMENTS.join(", ")}` };
+        }
+
+        const resolved = resolveEnvironmentHost(environment);
+        if (resolved.error) {
+          return { success: false, error: resolved.error };
         }
 
-        const status = await service.switchHost(host.trim());
+        const status = await service.switchHost(resolved.host!, environment);
         return {
           success: true,
-          host: host.trim(),
+          environment,
+          host: resolved.host,
           status,
         };
       },

package/openclaw.plugin.json

@@ -2,7 +2,7 @@
   "id": "kichi-forwarder",
   "name": "Kichi Forwarder",
   "description": "Native OpenClaw plugin for Kichi World with direct avatar control, status sync, timers, notes, and music tools",
-  "version": "0.1.1-beta.8",
+  "version": "0.1.2-beta.1",
   "author": "OpenClaw",
   "skills": ["./skills/kichi-forwarder"],
   "configSchema": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yahaha-studio/kichi-forwarder",
-  "version": "0.1.1-beta.8",
+  "version": "0.1.2-beta.1",
   "description": "Native OpenClaw plugin for Kichi World with direct avatar control, status sync, timers, notes, and music tools",
   "type": "module",
   "main": "index.ts",

package/skills/kichi-forwarder/SKILL.md

@@ -17,15 +17,19 @@ The following URLs are only used when this skill is first loaded from a remote U
 - `error.md`: `https://yahaha-studio.github.io/kichi-forwarder/references/error.md`
 - `heartbeat.md`: `https://yahaha-studio.github.io/kichi-forwarder/references/heartbeat.md`
 
-## Host Rules
+## Environment Rules
 
-- Install and connect requests include `host: <value>`.
+Install and connect requests use `on <environment>` syntax. Supported environments:
+
+- `steam`: connects to `focus-wss.yahaha.com`
+- `steam-playtest`: connects to `focus-steam-playtest-wss-int.yahaha.com`
+- `test`: no fixed host — ask the user for the current test node host, write it to the plugin's `config/environments.json`, then call `kichi_switch_host`
 
 ## Runtime State
 
 Runtime data lives under the user home directory and is isolated per OpenClaw agent:
 
-- `kichi-world/agents/<encoded-agent-id>/state.json`: stores that agent's `currentHost` and `llmRuntimeEnabled`
+- `kichi-world/agents/<encoded-agent-id>/state.json`: stores that agent's `currentEnvironment` and `llmRuntimeEnabled`
 - `kichi-world/agents/<encoded-agent-id>/hosts/<encoded-host>/identity.json`: stores that agent's host-specific `avatarId` and `authKey`
 
 ## Remote URL Install Entry
@@ -34,7 +38,7 @@ When this skill is first loaded from:
 
 - `https://yahaha-studio.github.io/kichi-forwarder/SKILL.md`
 
-and the user asks to connect/install with `avatarId` and `host`, do not invent a separate install flow in this file.
+and the user asks to connect/install with `avatarId` and an environment (e.g. `on steam-playtest`), do not invent a separate install flow in this file.
 
 The install and join flow is defined only in:
 
@@ -42,14 +46,18 @@ The install and join flow is defined only in:
 
 Read that file once to complete the initial install. After local installation, the local `install.md` is used instead.
 
-## Install Gate
+## Tool Availability
+
+All tools listed in this file (`kichi_join`, `kichi_connection_status`, `kichi_action`, etc.) are available immediately once the plugin is installed and loaded. The recommended order below is sequencing guidance, not an availability gate — you can call any tool at any time.
+
+## Install Flow
 
 For install/onboarding/connect requests:
 
 - Read and follow `install.md` before starting the install flow.
-- Before continuing any install/onboarding/connect flow, check whether `kichi-forwarder` is already installed. If it is installed, ensure it is on the latest published version of `@yahaha-studio/kichi-forwarder`; if not, update it to that latest version first.
+- Attempt to install `@yahaha-studio/kichi-forwarder` directly. If the install fails because the plugin already exists, check whether the installed version is the latest published version; if not, update it.
 - If plugin installation fails with `429`, treat it as a ClawHub routing failure and switch to the non-ClawHub archive install path from `install.md`/`error.md`. Do not retry the same bare package command.
-- Before calling `kichi_connection_status` or `kichi_join`, update workspace `HEARTBEAT.md` by following `heartbeat.md`. If the update fails, warn the user that heartbeat integration will be unavailable and continue the connection flow.
+- Recommended: update workspace `HEARTBEAT.md` by following `heartbeat.md` before calling `kichi_connection_status` or `kichi_join`. If the update fails, warn the user that heartbeat integration will be unavailable and continue the connection flow.
 
 ## LLM Runtime
 
@@ -58,18 +66,16 @@ For install/onboarding/connect requests:
 - When `true`, sync status uses LLM-driven prompts and may consume extra tokens.
 - When `false`, sync uses fixed English text.
 
-## Tool Selection Flow
-
-Use this order unless the user asks for a different explicit action:
+## Recommended Tool Order
 
-Install/onboarding requests are the exception: follow `install.md` first.
+Use this order unless the user asks for a different explicit action. For install/onboarding requests, follow `install.md` first.
 
 1. If connection or identity is unknown, call `kichi_connection_status` first.
-2. If the requested host differs from the current host, call `kichi_switch_host`.
+2. If the requested environment differs from the current environment, call `kichi_switch_host` with the target environment.
 3. If the requested `avatarId` differs from the current host's connected `avatarId`, call `kichi_leave` first when the old avatar is still joined, then call `kichi_join` with the requested `avatarId`.
-4. Otherwise, if no `authKey` is available, call `kichi_join`.
+4. If no `authKey` is available, call `kichi_join`.
 5. If `authKey` exists but websocket is not open, call `kichi_rejoin` or wait for automatic reconnect and rejoin.
-6. Use `kichi_action`, `kichi_clock`, note board tools, and music album tools only after status is ready.
+6. Use `kichi_action`, `kichi_clock`, note board tools, and music album tools after status is ready.
 
 ## Tools
 
@@ -88,10 +94,13 @@ kichi_join(avatarId: "your-avatar-id", botName: "<from IDENTITY.md>", bio: "<fro
 ### kichi_switch_host
 
 ```text
-kichi_switch_host(host: "your.kichi.host")
+kichi_switch_host(environment: "steam")
+kichi_switch_host(environment: "test")
 ```
 
-- `host`: required
+- `environment`: required. One of `steam`, `steam-playtest`, `test`.
+- Host is resolved from `config/environments.json`. If the environment has no configured host (null), the call fails.
+- For `test` environment: ask the user for the test node host, write it to the plugin's `config/environments.json`, then call this tool.
 - This reloads the host-specific `identity.json` and reconnects the websocket immediately.
 
 ### kichi_connection_status
@@ -102,7 +111,7 @@ kichi_connection_status()
 
 Use this to confirm:
 
-- current host
+- current environment and host
 - websocket URL
 - host-specific identity file path
 - websocket state
@@ -119,7 +128,7 @@ kichi_leave()
 When the user asks to leave Kichi World:
 
 1. Call `kichi_leave`.
-2. Suggest removing the Kichi heartbeat workflow from workspace `HEARTBEAT.md`. If the user declines, leave it in place.
+2. Clean up the Kichi heartbeat section from workspace `HEARTBEAT.md`. If the user declines, leave it in place.
 3. Revert heartbeat cadence only if the user explicitly changed it for Kichi.
 4. Do not claim the plugin removed heartbeat settings automatically.
 

package/skills/kichi-forwarder/references/heartbeat.md

@@ -2,7 +2,7 @@
 
 ## Session Startup Rule
 
-If the plugin is installed and enabled, update workspace `HEARTBEAT.md` to include the Kichi heartbeat workflow before first `kichi_connection_status` or `kichi_join` in an install/onboarding flow:
+If the plugin is installed and enabled, update workspace `HEARTBEAT.md` to include the Kichi heartbeat workflow as part of the install/onboarding flow (recommended before first `kichi_connection_status` or `kichi_join`, but not required):
 
 1. If the workflow snippet is missing, add the snippet from `HEARTBEAT.md Snippet` section below.
 2. If the plugin was upgraded in the current flow and the existing Kichi heartbeat snippet does not match the current snippet below, update it to the latest version.
@@ -10,7 +10,7 @@ If the plugin is installed and enabled, update workspace `HEARTBEAT.md` to inclu
 
 This startup rule is a recommended step for full heartbeat functionality.
 
-## First Join Gate
+## First Join Setup
 
 For "join Kichi World" onboarding requests:
 
@@ -21,11 +21,11 @@ For "join Kichi World" onboarding requests:
 
 ## Workflow Boundary
 
-This plugin only provides websocket tools. It does not edit workspace files itself.
+The plugin code itself does not write to workspace files. The onboarding instructions above direct the agent to update `HEARTBEAT.md` on behalf of the user as part of the install flow.
 
 If user wants recurring note board checks:
 
-1. Suggest updating workspace `HEARTBEAT.md`. If the user declines, skip the update.
+1. Update workspace `HEARTBEAT.md`.
 2. Keep the existing OpenClaw heartbeat cadence unless the user explicitly wants a different interval.
 3. Do not claim the plugin edited `HEARTBEAT.md` automatically.
 

package/skills/kichi-forwarder/references/install.md

@@ -1,8 +1,12 @@
 # Install
 
-## Host Rules
+## Environment Rules
 
-- Install and connect requests include `host: <value>`.
+Install and connect requests use `on <environment>` syntax. Supported environments:
+
+- `steam`: connects to `focus-wss.yahaha.com`
+- `steam-playtest`: connects to `focus-steam-playtest-wss-int.yahaha.com`
+- `test`: no fixed host — ask the user for the current test node host, write it to the plugin's `config/environments.json`, then connect
 
 ## Runtime Files
 
@@ -13,12 +17,12 @@ Persist runtime state to the current agent's `state.json`:
 
 ```json
 {
-  "currentHost": "your.kichi.host",
+  "currentEnvironment": "steam",
   "llmRuntimeEnabled": true
 }
 ```
 
-If the current host has no saved `avatarId` yet, save it to the current agent's host-specific `identity.json` before using `kichi_join`:
+If the current host has no saved `avatarId` yet, save it to the current agent's host-specific `identity.json` (this helps `kichi_join` resolve the avatar automatically when `avatarId` is omitted):
 
 - Linux/macOS: `~/.openclaw/kichi-world/agents/<encoded-agent-id>/hosts/<encoded-host>/identity.json`
 - Windows: `%USERPROFILE%\.openclaw\kichi-world\agents\<encoded-agent-id>\hosts\<encoded-host>\identity.json`
@@ -58,7 +62,7 @@ You may also use the exact absolute or relative `.tgz` path that `npm pack` prod
 This section only applies when the skill is first loaded from a remote URL before local installation. If the user asks:
 
 ```text
-Read https://yahaha-studio.github.io/kichi-forwarder/SKILL.md and connect me to Kichi World with avatarId: {avatarId} and host: {host}
+Read https://yahaha-studio.github.io/kichi-forwarder/SKILL.md, use AvatarId: {avatarId} to join kichi world on {environment}
 ```
 
 ## Command Execution Flow
@@ -67,21 +71,20 @@ When the user asks with one of the commands above, execute in this fixed order:
 
 1. If loaded from a remote URL, read `install.md` and `heartbeat.md` from the published skill URLs first. If installed locally, use the local files.
 2. Parse `avatarId` from user text (`AvatarId`/`avatarId`, case-insensitive).
-3. Resolve the host and write the current agent's `state.json`.
-4. Check whether `@yahaha-studio/kichi-forwarder` is already installed.
-5. If the plugin already exists, check whether the installed version is the latest published version.
-6. If the plugin is missing, run `openclaw plugins install @yahaha-studio/kichi-forwarder`.
-7. If the plugin is already installed but the version is not the latest, run `openclaw plugins update @yahaha-studio/kichi-forwarder`.
-8. If step 6 fails with `429`, do not retry the same bare package command. Run `npm pack @yahaha-studio/kichi-forwarder`, then install the generated `.tgz` with `openclaw plugins install <tgz-path>`.
-9. If step 7 fails with `429`, do not retry the same bare package command. Run `npm pack @yahaha-studio/kichi-forwarder`, then overwrite the existing install with `openclaw plugins install <tgz-path> --force`.
-10. Ensure the plugin is installed, enabled, and at the latest version.
-11. If the plugin was newly installed or upgraded in this flow, check workspace `HEARTBEAT.md` against the latest Kichi heartbeat requirements before continuing.
-12. Update workspace `HEARTBEAT.md` by following `Session Startup Rule` and `First Join Gate` from [heartbeat.md](heartbeat.md). If the update fails, warn the user and continue.
-13. Call `kichi_connection_status`.
-14. If the current agent runtime host does not match the requested one, call `kichi_switch_host`.
-15. If the current host is still connected with a different `avatarId`, call `kichi_leave` first, then call `kichi_join` with parsed `avatarId`, `botName`, `bio`, and `tags`.
-16. Otherwise, if `authKey` is missing, call `kichi_join` with parsed `avatarId`, `botName`, `bio`, and `tags`.
-17. Call `kichi_connection_status` again and confirm connection and auth state.
+3. Parse environment from the `on <environment>` part of the command (e.g. `on steam-playtest`). Write the current agent's `state.json`.
+4. Run `openclaw plugins install @yahaha-studio/kichi-forwarder`.
+5. If step 4 succeeds, the plugin is installed and up-to-date — skip to step 9.
+6. If step 4 fails because the plugin already exists, check whether the installed version is the latest published version. If the version is already the latest, skip to step 9. If not, run `openclaw plugins update @yahaha-studio/kichi-forwarder`.
+7. If step 4 fails with `429`, do not retry the same bare package command. Run `npm pack @yahaha-studio/kichi-forwarder`, then install the generated `.tgz` with `openclaw plugins install <tgz-path>`.
+8. If step 6 update fails with `429`, do not retry the same bare package command. Run `npm pack @yahaha-studio/kichi-forwarder`, then overwrite the existing install with `openclaw plugins install <tgz-path> --force`.
+9. Ensure the plugin is installed, enabled, and at the latest version.
+10. If the plugin was newly installed or upgraded in this flow, check workspace `HEARTBEAT.md` against the latest Kichi heartbeat requirements before continuing.
+11. Update workspace `HEARTBEAT.md` by following `Session Startup Rule` and `First Join Setup` from [heartbeat.md](heartbeat.md). If the update fails, warn the user and continue.
+12. Call `kichi_connection_status`.
+13. If the current agent runtime environment does not match the requested one, call `kichi_switch_host` with the target environment (and host for test).
+14. If the current host is still connected with a different `avatarId`, call `kichi_leave` first, then call `kichi_join` with parsed `avatarId`, `botName`, `bio`, and `tags`.
+15. Otherwise, if `authKey` is missing, call `kichi_join` with parsed `avatarId`, `botName`, `bio`, and `tags`.
+16. Call `kichi_connection_status` again and confirm connection and auth state.
 
 ## Required Post-install Integration
 
@@ -95,4 +98,4 @@ If any box is unchecked, the onboarding remains incomplete.
 
 If the `HEARTBEAT.md` update fails, warn the user that heartbeat integration will be unavailable but do not block the connection flow.
 
-This plugin does not edit workspace files automatically. Do not claim plugin-side auto-write of `HEARTBEAT.md`.
+The plugin code does not write to workspace files directly. The agent updates `HEARTBEAT.md` as part of this onboarding flow.

package/src/runtime-manager.ts

@@ -3,6 +3,7 @@ import os from "node:os";
 import path from "node:path";
 import type { Logger } from "openclaw/plugin-sdk";
 import { KichiForwarderService } from "./service.js";
+import type { KichiEnvironment } from "./types.js";
 
 const OPENCLAW_HOME_DIR = path.join(os.homedir(), ".openclaw");
 const KICHI_WORLD_ROOT_DIR = path.join(OPENCLAW_HOME_DIR, "kichi-world");
@@ -16,9 +17,14 @@ type AgentLocator = {
 
 export class KichiRuntimeManager {
   private services = new Map<string, KichiForwarderService>();
+  private resolveEnvironmentHost: ((environment: KichiEnvironment) => string | null) | null = null;
 
   constructor(private logger: Logger) {}
 
+  setEnvironmentHostResolver(resolver: (environment: KichiEnvironment) => string | null): void {
+    this.resolveEnvironmentHost = resolver;
+  }
+
   getRuntime(locator: AgentLocator): KichiForwarderService | null {
     const agentId = this.resolveAgentId(locator);
     if (!agentId) {
@@ -112,12 +118,17 @@ export class KichiRuntimeManager {
   }
 
   private createRuntime(agentId: string): KichiForwarderService {
+    if (!this.resolveEnvironmentHost) {
+      throw new Error("Environment host resolver not set on KichiRuntimeManager");
+    }
     const runtimeDir = this.getRuntimeDir(agentId);
     fs.mkdirSync(runtimeDir, { recursive: true, mode: 0o700 });
 
+    const resolveEnvironmentHost = this.resolveEnvironmentHost;
     const service = new KichiForwarderService(this.logger, {
       agentId,
       runtimeDir,
+      resolveEnvironmentHost,
     });
     service.start();
     this.services.set(agentId, service);

package/src/service.ts

@@ -17,6 +17,7 @@ import type {
   JoinAckPayload,
   JoinPayload,
   KichiConnectionStatus,
+  KichiEnvironment,
   KichiIdentity,
   KichiState,
   LeaveAckPayload,
@@ -53,6 +54,7 @@ export type LeaveResult =
 type KichiForwarderServiceOptions = {
   agentId: string;
   runtimeDir: string;
+  resolveEnvironmentHost: (environment: KichiEnvironment) => string | null;
 };
 
 type ConnectReason = "startup" | "switch_host" | "reconnect";
@@ -64,6 +66,7 @@ export class KichiForwarderService {
   private joinTimeout: NodeJS.Timeout | null = null;
   private identity: KichiIdentity | null = null;
   private host: string | null = null;
+  private environment: KichiEnvironment | null = null;
   private joinResolve: ((result: JoinResult) => void) | null = null;
   private pendingRequests = new Map<
     string,
@@ -81,7 +84,13 @@ export class KichiForwarderService {
   ) {}
 
   start(): void {
-    this.host = this.loadCurrentHost();
+    const state = this.readStateFile();
+    this.environment = (state?.currentEnvironment as KichiEnvironment) ?? null;
+    if (this.environment) {
+      this.host = this.options.resolveEnvironmentHost(this.environment);
+    } else {
+      this.host = null;
+    }
     this.identity = this.host ? this.loadIdentity() : null;
     this.stopped = false;
     if (this.host) {
@@ -99,9 +108,10 @@ export class KichiForwarderService {
     this.closeSocket();
   }
 
-  async switchHost(host: string): Promise<KichiConnectionStatus> {
-    this.persistCurrentHost(host);
+  async switchHost(host: string, environment?: KichiEnvironment): Promise<KichiConnectionStatus> {
+    this.persistCurrentHost(host, environment);
     this.host = host;
+    this.environment = environment ?? null;
     this.identity = this.loadIdentity();
     this.clearReconnectTimeout();
     this.rejectPendingRequests(`Kichi websocket switched to ${host}`);
@@ -406,6 +416,7 @@ export class KichiForwarderService {
         wsUrl: this.getWsUrl(),
         identityPath: this.getIdentityPath(),
       } : {}),
+      ...(this.environment ? { environment: this.environment } : {}),
       hostConfigured: !!host,
       connected: this.isConnected(),
       websocketState: this.getWebsocketState(),
@@ -709,8 +720,10 @@ export class KichiForwarderService {
     if (!this.host) {
       throw new Error("No Kichi host configured");
     }
-    const protocol = this.isPlainIpHost(this.host) || this.host === "localhost" ? "ws" : "wss";
-    return `${protocol}://${this.host}:48870/ws/openclaw`;
+    const isLocal = this.isPlainIpHost(this.host) || this.host === "localhost";
+    const protocol = isLocal ? "ws" : "wss";
+    const port = isLocal ? ":48870" : "";
+    return `${protocol}://${this.host}${port}/ws/openclaw`;
   }
 
   private isPlainIpHost(host: string): boolean {
@@ -719,26 +732,10 @@ export class KichiForwarderService {
       || /^[0-9a-f:]+$/i.test(host);
   }
 
-  private loadCurrentHost(): string | null {
-    try {
-      const statePath = this.getStatePath();
-      if (!fs.existsSync(statePath)) {
-        return null;
-      }
-      const data = JSON.parse(fs.readFileSync(statePath, "utf-8")) as { currentHost?: unknown };
-      if (typeof data.currentHost === "string" && data.currentHost.trim()) {
-        return data.currentHost;
-      }
-      throw new Error(`Invalid currentHost value in ${statePath}`);
-    } catch (error) {
-      throw new Error(`Failed to load current host: ${error}`);
-    }
-  }
-
-  private persistCurrentHost(host: string): void {
+  private persistCurrentHost(host: string, environment?: KichiEnvironment): void {
     const previousState = this.readStateFile();
     const nextState: KichiState = {
-      currentHost: host,
+      ...(environment ? { currentEnvironment: environment } : {}),
       llmRuntimeEnabled: previousState?.llmRuntimeEnabled ?? DEFAULT_LLM_RUNTIME_ENABLED,
     };
     fs.mkdirSync(this.options.runtimeDir, { recursive: true, mode: 0o700 });

package/src/types.ts

@@ -36,8 +36,12 @@ export type Album = {
   track: Track[];
 };
 
+export type KichiEnvironment = "steam" | "steam-playtest" | "test";
+
+export type KichiEnvironmentsConfig = Record<KichiEnvironment, string | null>;
+
 export type KichiState = {
-  currentHost?: string;
+  currentEnvironment?: KichiEnvironment;
   llmRuntimeEnabled: boolean;
 };
 
@@ -51,6 +55,7 @@ export type KichiConnectionStatus = {
   runtimeDir?: string;
   statePath?: string;
   host?: string;
+  environment?: KichiEnvironment;
   wsUrl?: string;
   identityPath?: string;
   hostConfigured: boolean;