feat: support configurable gateway port

src/config/config.test.ts

@@ -390,6 +390,30 @@ describe("Nix integration (U3, U5, U9)", () => {
     });
   });
 
+  describe("U6: gateway port resolution", () => {
+    it("uses default when env and config are unset", async () => {
+      await withEnvOverride({ CLAWDIS_GATEWAY_PORT: undefined }, async () => {
+        const { DEFAULT_GATEWAY_PORT, resolveGatewayPort } =
+          await import("./config.js");
+        expect(resolveGatewayPort({})).toBe(DEFAULT_GATEWAY_PORT);
+      });
+    });
+
+    it("prefers CLAWDIS_GATEWAY_PORT over config", async () => {
+      await withEnvOverride({ CLAWDIS_GATEWAY_PORT: "19001" }, async () => {
+        const { resolveGatewayPort } = await import("./config.js");
+        expect(resolveGatewayPort({ gateway: { port: 19002 } })).toBe(19001);
+      });
+    });
+
+    it("falls back to config when env is invalid", async () => {
+      await withEnvOverride({ CLAWDIS_GATEWAY_PORT: "nope" }, async () => {
+        const { resolveGatewayPort } = await import("./config.js");
+        expect(resolveGatewayPort({ gateway: { port: 19003 } })).toBe(19003);
+      });
+    });
+  });
+
   describe("U9: telegram.tokenFile schema validation", () => {
     it("accepts config with only botToken", async () => {
       await withTempHome(async (home) => {

src/config/config.ts

@@ -438,6 +438,8 @@ export type GatewayRemoteConfig = {
 };
 
 export type GatewayConfig = {
+  /** Single multiplexed port for Gateway WS + HTTP (default: 18789). */
+  port?: number;
   /**
    * Explicit gateway mode. When set to "remote", local gateway start is disabled.
    * When set to "local", the CLI may start the gateway locally.
@@ -642,6 +644,24 @@ export const CONFIG_PATH_CLAWDIS =
   process.env.CLAWDIS_CONFIG_PATH ??
   path.join(STATE_DIR_CLAWDIS, "clawdis.json");
 
+export const DEFAULT_GATEWAY_PORT = 18789;
+
+export function resolveGatewayPort(
+  cfg?: ClawdisConfig,
+  env: NodeJS.ProcessEnv = process.env,
+): number {
+  const envRaw = env.CLAWDIS_GATEWAY_PORT?.trim();
+  if (envRaw) {
+    const parsed = Number.parseInt(envRaw, 10);
+    if (Number.isFinite(parsed) && parsed > 0) return parsed;
+  }
+  const configPort = cfg?.gateway?.port;
+  if (typeof configPort === "number" && Number.isFinite(configPort)) {
+    if (configPort > 0) return configPort;
+  }
+  return DEFAULT_GATEWAY_PORT;
+}
+
 const ModelApiSchema = z.union([
   z.literal("openai-completions"),
   z.literal("openai-responses"),
@@ -1217,6 +1237,7 @@ const ClawdisSchema = z.object({
     .optional(),
   gateway: z
     .object({
+      port: z.number().int().positive().optional(),
       mode: z.union([z.literal("local"), z.literal("remote")]).optional(),
       bind: z
         .union([