OpenClaw: documents from local path, rebuild workaround, forgejo-cli

- Documents (SOUL/TOOLS/AGENTS) from path input to openclaw-documents-repo
- Flake: openclaw-documents.url = path to local clone (no SSH under sudo)
- Remove in-repo openclaw-documents; add docs/openclaw-documents.md
- openclaw.nix: activation backup + force for openclaw.json (TODO to remove)
- home.nix: add forgejo-cli
- .gitignore: openclaw-documents-repo; drop SOUL/TOOLS ignores
- AGENTS.md: OpenClaw docs ref
- TODO: remove OpenClaw activation/force bloat

Made-with: Cursor

.gitignore

@@ -15,6 +15,5 @@ nixos/installer-wifi.nix
 # OpenClaw: Telegram user ID(s), not in public repo
 nixos/home/danny/openclaw-allow-from.nix
 
-# OpenClaw: personal assistant docs, not for public repo
+# OpenClaw: documents live in private repo; local clone optional
-nixos/home/danny/openclaw-documents/SOUL.md
+openclaw-documents-repo/
-nixos/home/danny/openclaw-documents/TOOLS.md

AGENTS.md

@@ -53,5 +53,5 @@ Rebuild on the server (flake is in `nixos/`): `ssh ... 'cd /etc/dotfiles/nixos &
 
 ## OpenClaw (macOS)
 
-OpenClaw (AI assistant gateway, Telegram) is integrated in the dotfiles flake. Config: [nixos/home/danny/openclaw.nix](nixos/home/danny/openclaw.nix). Documents: [nixos/home/danny/openclaw-documents/](nixos/home/danny/openclaw-documents/). Secrets (bot token, gateway token, Telegram user ID) live in the config or `~/.secrets/`. One apply: `darwin-rebuild switch --flake .` from `nixos/`.
+OpenClaw (AI assistant gateway, Telegram) is integrated in the dotfiles flake. Config: [nixos/home/danny/openclaw.nix](nixos/home/danny/openclaw.nix). Documents (SOUL.md, TOOLS.md, etc.) come from a separate repo via the flake input `openclaw-documents` in [nixos/flake.nix](nixos/flake.nix)—override with e.g. `openclaw-documents.url = "github:you/openclaw-documents";`. See [docs/openclaw-documents.md](docs/openclaw-documents.md). Secrets (bot token, gateway token, Telegram user ID) live in the config or `~/.secrets/`. One apply: `darwin-rebuild switch --flake .` from `nixos/`.
 

TODO.md

@@ -1,9 +1,11 @@
 # TODO
 
-1. Create a setup/boot USB that: installs NixOS on the server with encryption and WiFi configured from the start; only required input is the server's name (e.g. sunken-ship).
+1. **OpenClaw:** Remove the activation-backup + force overrides in `nixos/home/danny/openclaw.nix`. They work around "file is in the way" / "would be clobbered" when home-manager manages `~/.openclaw/`. Prefer fixing upstream (nix-openclaw) or a cleaner approach (e.g. deploy to a different path, or let the module handle existing files).
+
+2. Create a setup/boot USB that: installs NixOS on the server with encryption and WiFi configured from the start; only required input is the server's name (e.g. sunken-ship).
    * I have a set wifi SSID/PSK, assume servers will start up and be able to reach this wifi.
    * I don't know how to go about the rest of this.
 
-2. Encrypt sunken-ship (LUKS); update hardware/config for encrypted root and boot.
+3. Encrypt sunken-ship (LUKS); update hardware/config for encrypted root and boot.
 
-3. Host telegram bot once again (for what purpose?)
+4. Host telegram bot once again (for what purpose?)

docs/openclaw-documents.md

@@ -0,0 +1,21 @@
+# OpenClaw documents (separate repo)
+
+SOUL.md, TOOLS.md, and any other markdown files used by OpenClaw are supplied via the flake input `openclaw-documents` in `nixos/flake.nix`. The input points at the **local clone** `path:/Users/danny/dotfiles/openclaw-documents-repo` so `sudo darwin-rebuild` doesn’t need SSH to GitHub. (Change the path in `flake.nix` if your clone lives elsewhere.)
+
+## Repo contents
+
+The repo (or local clone) must have at least:
+- `SOUL.md` – who the assistant is, personality and boundaries
+- `TOOLS.md` – what the assistant can use and how
+- `AGENTS.md` – instructions for the AI when acting on your behalf  
+  (The nix-openclaw module asserts these exist.)
+- A minimal `flake.nix` so the repo can be used as a flake input:
+  ```nix
+  { outputs = { ... }: { source = ./.; }; }
+  ```
+
+## Local clone
+
+The flake uses the local clone at `~/dotfiles/openclaw-documents-repo/` (path input, gitignored). Edit SOUL/TOOLS there; the next rebuild uses the current directory contents (no `nix flake update` needed). Push/pull to sync with the private GitHub repo when you like.
+
+To use the remote repo instead (e.g. on another machine), set `openclaw-documents.url = "git+ssh://git@github.com/DannyDannyDanny/openclaw-documents"` in `nixos/flake.nix` and ensure your SSH key is loaded when running the rebuild.

nixos/flake.lock

@@ -292,6 +292,18 @@
         "type": "indirect"
       }
     },
+    "openclaw-documents": {
+      "locked": {
+        "lastModified": 1773484599,
+        "narHash": "sha256-Dpb4erTKZqAKolD7UjXMuIBUEax21q2jNvT+1fiIFA4=",
+        "path": "/Users/danny/dotfiles/openclaw-documents-repo",
+        "type": "path"
+      },
+      "original": {
+        "path": "/Users/danny/dotfiles/openclaw-documents-repo",
+        "type": "path"
+      }
+    },
     "root": {
       "inputs": {
         "disko": "disko",
@@ -300,6 +312,7 @@
         "nix-openclaw": "nix-openclaw",
         "nixos-wsl": "nixos-wsl",
         "nixpkgs": "nixpkgs_4",
+        "openclaw-documents": "openclaw-documents",
         "vscode-server": "vscode-server",
         "zen-browser": "zen-browser"
       }

nixos/flake.nix

@@ -20,6 +20,8 @@
     disko.inputs.nixpkgs.follows = "nixpkgs";
 
     nix-openclaw.url = "github:openclaw/nix-openclaw";
+    # OpenClaw SOUL/TOOLS and other docs. Absolute path to local clone (no SSH under sudo).
+    openclaw-documents.url = "path:/Users/danny/dotfiles/openclaw-documents-repo";
   };
 
   outputs = {
@@ -32,6 +34,7 @@
     zen-browser,
     disko,
     nix-openclaw,
+    openclaw-documents,
     ...
   }: {
     nixosConfigurations = {
@@ -92,7 +95,7 @@
 
     # macOS (nix-darwin) configuration
     darwinConfigurations."Daniel-Macbook-Air" = nix-darwin.lib.darwinSystem {
-      specialArgs = { inherit zen-browser nix-openclaw; };
+      specialArgs = { inherit zen-browser nix-openclaw openclaw-documents; };
       modules = [
         ./hosts/macos.nix
         ./fish.nix
@@ -104,13 +107,13 @@
 
         # Home Manager on macOS
         home-manager.darwinModules.home-manager
-        ({ lib, zen-browser, nix-openclaw, ... }: {
+        ({ lib, zen-browser, nix-openclaw, openclaw-documents, ... }: {
           home-manager.useGlobalPkgs = true;
           home-manager.useUserPackages = true;
           # Automatically backup files before home-manager overwrites them
           home-manager.backupFileExtension = "backup";
           # Pass flake inputs to home-manager modules (e.g. home.nix)
-          home-manager.extraSpecialArgs = { inherit zen-browser; };
+          home-manager.extraSpecialArgs = { inherit zen-browser openclaw-documents; };
           home-manager.users.danny = { ... }: {
 
             # Force an absolute path even if another module sets a bad value.

nixos/home/danny/home.nix

@@ -189,6 +189,7 @@
     wget          # downloader
     # azure-cli   # TODO: remove this Azure cli tool
     gh            # github cli tool
+    forgejo-cli   # forgejo/codeberg cli (provides fj)
     git           # version control
     jujutsu       # Git alternative
     gnupg         # GNU privacy guard (GPG)

nixos/home/danny/openclaw-documents/AGENTS.md

@@ -1,7 +0,0 @@
-# Agent instructions
-
-Instructions for the AI assistant (OpenClaw) when acting on your behalf.
-
-- Prefer terminal and scripting for automation; use GUI only when necessary.
-- Prefer tools and skills provided by enabled plugins; suggest enabling a plugin if a task needs it.
-- Do not store secrets or tokens in the repo; use ~/.secrets/ or environment.

nixos/home/danny/openclaw.nix

@@ -1,11 +1,13 @@
 # OpenClaw (AI assistant gateway) – Telegram, launchd, documents.
+# Documents (SOUL.md, TOOLS.md, etc.) come from a separate repo via the flake input
+# openclaw-documents (see flake.nix; override with e.g. github:you/openclaw-documents).
 # Secrets (not in repo):
 #   ~/.secrets/telegram-bot-token
 #   ~/.secrets/openclaw-gateway-token   (one line, gateway auth token)
 #   nixos/home/danny/openclaw-allow-from.nix  (gitignored; copy from .example)
 # After editing, run: darwin-rebuild switch --flake . (from ~/dotfiles/nixos)
 
-{ config, lib, ... }:
+{ config, lib, pkgs, openclaw-documents, ... }:
 
 let
   # Telegram user IDs from gitignored file so we don't commit them
@@ -15,7 +17,8 @@ in
 {
   programs.openclaw = {
     enable = true;
-    documents = ./openclaw-documents;
+    # Flake input: use .source (in-repo and separate-repo flakes expose source = ./.)
+    documents = openclaw-documents.source or openclaw-documents.outPath or openclaw-documents;
 
     config = { };
 
@@ -44,14 +47,29 @@ in
     executable = true;
   };
 
-  # Prepend wrapper to launchd so OPENCLAW_GATEWAY_TOKEN is set from file at runtime
+  # TODO: Remove this bloat (see dotfiles TODO.md). Back up as target user so HM can overwrite.
-  launchd.agents."com.steipete.openclaw.gateway" = lib.mkForce (
+  home.activation.backupOpenclawBeforeSwitch = lib.hm.dag.entryBefore [ "linkGeneration" ] ''
-    (config.launchd.agents."com.steipete.openclaw.gateway" or { }) // {
+    OPENCLAW="${config.home.homeDirectory}/.openclaw"
-      config = (config.launchd.agents."com.steipete.openclaw.gateway".config or { }) // {
+    USER="${config.home.username}"
+    if [ -d "$OPENCLAW" ]; then
+      for f in "$OPENCLAW"/workspace/*.md "$OPENCLAW"/openclaw.json; do
+        [ -e "$f" ] && [ ! -L "$f" ] && (sudo -u "$USER" mv -n "$f" "$f.backup" 2>/dev/null || true)
+      done
+    fi
+  '';
+  home.file.".openclaw/openclaw.json".force = true;
+
+  # Override launchd agent to run wrapper so OPENCLAW_GATEWAY_TOKEN is set from file at runtime.
+  # Do not reference config.launchd.agents."..." here (causes infinite recursion).
+  launchd.agents."com.steipete.openclaw.gateway" = lib.mkForce {
+    enable = true;
+    config = {
       ProgramArguments = [
         (config.home.homeDirectory + "/.local/bin/openclaw-gateway-wrapper")
-        ] ++ (config.launchd.agents."com.steipete.openclaw.gateway".config.ProgramArguments or [ ]);
+        "${pkgs.openclaw}/bin/openclaw-gateway"
+      ];
+      RunAtLoad = true;
+      KeepAlive = true;
+    };
   };
-    }
-  );
 }