feat: make workspace path configurable via CLI flag (#98)

* feat: make workspace path configurable via CLI flag and env var

Add --workspace flag and DOCSCLAW_WORKSPACE env var to the serve
command, allowing operators to override the workspace directory
without editing the ConfigMap. Priority: agent-config.yaml >
flag/env > default (/workspace).

Unifies workspace resolution into a single resolveWorkspace
function, replacing two ad-hoc inline resolution blocks.

Closes #96

Assisted-By: Claude (Anthropic AI) <noreply@anthropic.com>
Signed-off-by: Pavel Anni <panni@redhat.com>

* fix: clarify workspace env var comment and trim whitespace

- Clarify DOCSCLAW_WORKSPACE comment in deployment manifest to
  note it is a fallback, not an override, when agent-config.yaml
  sets tools.workspace
- Trim whitespace in resolveWorkspace to reject blank strings

Assisted-By: Claude (Anthropic AI) <noreply@anthropic.com>
Signed-off-by: Pavel Anni <panni@redhat.com>

* fix: address CodeRabbit nitpicks on workspace PR

- Reword workspace table entry to a complete sentence
- Add whitespace-trimming test for resolveWorkspace

Assisted-By: Claude (Anthropic AI) <noreply@anthropic.com>
Signed-off-by: Pavel Anni <panni@redhat.com>

---------

Signed-off-by: Pavel Anni <panni@redhat.com>

Author: pavelanni

deploy/standalone-agent.yaml

@@ -126,6 +126,10 @@ spec:
           env:
             - name: DOCSCLAW_SERVICE_PORT
               value: "8000"
+            # Fallback workspace directory — used only when
+            # agent-config.yaml does not set tools.workspace:
+            # - name: DOCSCLAW_WORKSPACE
+            #   value: "/data/agent"
           envFrom:
             - secretRef:
                 name: llm-secret

docs/agent-config-guide.md

@@ -99,7 +99,7 @@ agent-config.yaml
 | Field | Type | Default | Description |
 | ----- | ---- | ------- | ----------- |
 | `allowed` | `[]string` | `[]` (none) | Tools the LLM may call. See [available tools](#available-tools). |
-| `workspace` | `string` | `/workspace` | Root directory for `read_file` and `write_file`. The agent cannot access files outside this path. |
+| `workspace` | `string` | `/workspace` | Root directory for `read_file` and `write_file`. The agent cannot access files outside this path. The workspace path can also be set via the `--workspace` flag or the `DOCSCLAW_WORKSPACE` env var; the config file value takes precedence. |
 
 ### `tools.exec`
 
@@ -289,6 +289,9 @@ for a complete example.
 
 Workspace context loads regardless of whether `agent-config.yaml`
 exists. It works in both phase 1 (single-shot) and phase 2
-(agentic loop). The workspace directory defaults to `/workspace`;
-if `agent-config.yaml` specifies `tools.workspace`, that path is
-used instead.
+(agentic loop). The workspace directory is resolved with this
+priority:
+
+1. `agent-config.yaml` `tools.workspace` (config file wins)
+2. `--workspace` flag or `DOCSCLAW_WORKSPACE` env var
+3. Default: `/workspace`

internal/cmd/serve.go

@@ -251,10 +251,13 @@ func init() {
 	serveCmd.Flags().String("llm-model", "", "LLM model to use")
 	serveCmd.Flags().Int("llm-max-tokens", 4096, "Max tokens for LLM response")
 	serveCmd.Flags().Int("llm-timeout", 45, "LLM request timeout in seconds")
+	serveCmd.Flags().String("workspace", "",
+		"Workspace directory path (default: /workspace)")
 	serveCmd.Flags().String("session-db", "",
 		"Session database backend ('memory' for in-memory, or a file path for SQLite; default: memory)")
 
 	_ = v.BindPFlag("config_dir", serveCmd.Flags().Lookup("config-dir"))
+	_ = v.BindPFlag("workspace", serveCmd.Flags().Lookup("workspace"))
 	_ = v.BindPFlag("skills_dir", serveCmd.Flags().Lookup("skills-dir"))
 	_ = v.BindPFlag("document_service_url", serveCmd.Flags().Lookup("document-service-url"))
 	_ = v.BindPFlag("llm.provider", serveCmd.Flags().Lookup("llm-provider"))
@@ -271,11 +274,22 @@ type Config struct {
 	config.CommonConfig `mapstructure:",squash"`
 	ConfigDir          string     `mapstructure:"config_dir"`
 	SkillsDir          string     `mapstructure:"skills_dir"`
+	Workspace          string     `mapstructure:"workspace"`
 	DocumentServiceURL string     `mapstructure:"document_service_url"`
 	LLM                llm.Config `mapstructure:"llm"`
 	SessionDB          string     `mapstructure:"session_db"`
 }
 
+func resolveWorkspace(cfgWorkspace, flagWorkspace string) string {
+	if v := strings.TrimSpace(cfgWorkspace); v != "" {
+		return v
+	}
+	if v := strings.TrimSpace(flagWorkspace); v != "" {
+		return v
+	}
+	return defaultWorkspace
+}
+
 // startAgent loads config from configDir and validates it.
 // This function is separated from runServe for testability.
 func startAgent(configDir string, _ llm.Provider) error {
@@ -338,6 +352,13 @@ func runServe(cmd *cobra.Command, args []string) error {
 		return err
 	}
 
+	// Resolve workspace path: agent-config.yaml > --workspace flag/env > default
+	var cfgWorkspace string
+	if agentCfg != nil {
+		cfgWorkspace = agentCfg.Tools.Workspace
+	}
+	workspace := resolveWorkspace(cfgWorkspace, cfg.Workspace)
+
 	// Set up tool registry and skill loading if agent config exists
 	var toolRegistry *tools.Registry
 	var loopCfg tools.LoopConfig
@@ -346,10 +367,6 @@ func runServe(cmd *cobra.Command, args []string) error {
 	if agentCfg != nil {
 		toolRegistry = tools.NewRegistry(agentCfg.Tools.Allowed)
 
-		workspace := agentCfg.Tools.Workspace
-		if workspace == "" {
-			workspace = defaultWorkspace
-		}
 		if err := os.MkdirAll(workspace, 0755); err != nil {
 			return fmt.Errorf("failed to create workspace: %w", err)
 		}
@@ -385,10 +402,6 @@ func runServe(cmd *cobra.Command, args []string) error {
 	slog.SetDefault(log.Logger)
 
 	// Load OpenClaw workspace context (works in both phase 1 and phase 2)
-	workspace := defaultWorkspace
-	if agentCfg != nil && agentCfg.Tools.Workspace != "" {
-		workspace = agentCfg.Tools.Workspace
-	}
 	systemPrompt += loadWorkspaceContext(workspace)
 
 	// Load OS tool inventory and inject into system prompt

internal/cmd/workspace_test.go

@@ -167,6 +167,34 @@ func TestLoadWorkspaceContextUnicodeTruncation(t *testing.T) {
 	}
 }
 
+func TestResolveWorkspaceConfigWins(t *testing.T) {
+	result := resolveWorkspace("/from-config", "/from-flag")
+	if result != "/from-config" {
+		t.Fatalf("expected /from-config, got %q", result)
+	}
+}
+
+func TestResolveWorkspaceFlagFallback(t *testing.T) {
+	result := resolveWorkspace("", "/from-flag")
+	if result != "/from-flag" {
+		t.Fatalf("expected /from-flag, got %q", result)
+	}
+}
+
+func TestResolveWorkspaceDefault(t *testing.T) {
+	result := resolveWorkspace("", "")
+	if result != defaultWorkspace {
+		t.Fatalf("expected %q, got %q", defaultWorkspace, result)
+	}
+}
+
+func TestResolveWorkspaceWhitespaceIgnored(t *testing.T) {
+	result := resolveWorkspace("   ", "/from-flag")
+	if result != "/from-flag" {
+		t.Fatalf("expected /from-flag, got %q", result)
+	}
+}
+
 func TestLoadWorkspaceContextNonexistentDir(t *testing.T) {
 	result := loadWorkspaceContext("/nonexistent/path")