diff --git a/apps/site/docs/en/api.mdx b/apps/site/docs/en/api.mdx
index ccbc3390c6..aea9e67cdb 100644
--- a/apps/site/docs/en/api.mdx
+++ b/apps/site/docs/en/api.mdx
@@ -748,12 +748,17 @@ Execute an automation script written in YAML. Only the `tasks` part of the scrip
 - Type
 
 ```typescript
-function runYaml(yamlScriptContent: string): Promise<{ result: any }>;
+function runYaml(
+  yamlScriptContent: string,
+  opt?: { interpolateProcessEnv?: boolean },
+): Promise<{ result: any }>;
 ```
 
 - Parameters:
 
   - `yamlScriptContent: string` - The YAML-formatted script content.
+  - `opt?: object` - Optional configuration.
+    - `interpolateProcessEnv?: boolean` - Whether to replace `${ENV_VAR}` placeholders with `process.env` values (defaults to `true`).
 
 - Return Value:
 
diff --git a/apps/site/docs/zh/api.mdx b/apps/site/docs/zh/api.mdx
index 1590d0571d..b828dbe2ea 100644
--- a/apps/site/docs/zh/api.mdx
+++ b/apps/site/docs/zh/api.mdx
@@ -740,12 +740,17 @@ await agent.aiWaitFor('购物车图标显示数量为 2', {
 - 类型
 
 ```typescript
-function runYaml(yamlScriptContent: string): Promise<{ result: any }>;
+function runYaml(
+  yamlScriptContent: string,
+  opt?: { interpolateProcessEnv?: boolean },
+): Promise<{ result: any }>;
 ```
 
 - 参数：
 
   - `yamlScriptContent: string` - YAML 格式的脚本内容
+  - `opt?: object` - 可选配置。
+    - `interpolateProcessEnv?: boolean` - 是否将 `${ENV_VAR}` 占位符替换为 `process.env` 中的值（默认为 `true`）。
 
 - 返回值：
 
diff --git a/packages/core/src/agent/agent.ts b/packages/core/src/agent/agent.ts
index 76f3ea33b3..59d7eb3006 100644
--- a/packages/core/src/agent/agent.ts
+++ b/packages/core/src/agent/agent.ts
@@ -1234,10 +1234,13 @@ export class Agent<
     return this.aiAct(...args);
   }
 
-  async runYaml(yamlScriptContent: string): Promise<{
+  async runYaml(
+    yamlScriptContent: string,
+    opt?: { interpolateProcessEnv?: boolean },
+  ): Promise<{
     result: Record<string, any>;
   }> {
-    const script = parseYamlScript(yamlScriptContent, 'yaml');
+    const script = parseYamlScript(yamlScriptContent, 'yaml', opt);
     const player = new ScriptPlayer(script, async () => {
       return { agent: this, freeFn: [] };
     });
diff --git a/packages/core/src/yaml/utils.ts b/packages/core/src/yaml/utils.ts
index 08da2eb7d8..a7531670d4 100644
--- a/packages/core/src/yaml/utils.ts
+++ b/packages/core/src/yaml/utils.ts
@@ -39,6 +39,9 @@ export function interpolateEnvVars(content: string): string {
 export function parseYamlScript(
   content: string,
   filePath?: string,
+  opt?: {
+    interpolateProcessEnv?: boolean;
+  },
 ): MidsceneYamlScript {
   let processedContent = content;
   if (content.indexOf('android') !== -1 && content.match(/deviceId:\s*(\d+)/)) {
@@ -54,7 +57,10 @@ export function parseYamlScript(
       `please use string-style deviceId in yaml script, for example: deviceId: "${matchedDeviceId}"`,
     );
   }
-  const interpolatedContent = interpolateEnvVars(processedContent);
+  const shouldInterpolate = opt?.interpolateProcessEnv ?? true;
+  const interpolatedContent = shouldInterpolate
+    ? interpolateEnvVars(processedContent)
+    : processedContent;
   const obj = yaml.load(interpolatedContent, {
     schema: yaml.JSON_SCHEMA,
   }) as MidsceneYamlScript;
diff --git a/packages/core/tests/unit-test/yaml-env-interpolation.test.ts b/packages/core/tests/unit-test/yaml-env-interpolation.test.ts
new file mode 100644
index 0000000000..75020a430c
--- /dev/null
+++ b/packages/core/tests/unit-test/yaml-env-interpolation.test.ts
@@ -0,0 +1,36 @@
+import { parseYamlScript } from '../../src/yaml/utils';
+import { afterEach, describe, expect, it } from 'vitest';
+
+const TEST_ENV_KEY = 'MIDSCENE_TEST_ENV_KEY';
+const placeholder = `\${${TEST_ENV_KEY}}`;
+
+const yamlScript = `tasks:
+  - name: check env
+    flow:
+      - ai: ${placeholder}
+`;
+
+afterEach(() => {
+  delete process.env[TEST_ENV_KEY];
+});
+
+describe('parseYamlScript env interpolation', () => {
+  it('interpolates process.env by default', () => {
+    const expectedValue = 'interpolated';
+    process.env[TEST_ENV_KEY] = expectedValue;
+
+    const result = parseYamlScript(yamlScript);
+
+    expect(result.tasks[0]?.flow?.[0]).toEqual({ ai: expectedValue });
+  });
+
+  it('skips interpolation when interpolateProcessEnv is false', () => {
+    process.env[TEST_ENV_KEY] = 'interpolated';
+
+    const result = parseYamlScript(yamlScript, 'yaml', {
+      interpolateProcessEnv: false,
+    });
+
+    expect(result.tasks[0]?.flow?.[0]).toEqual({ ai: placeholder });
+  });
+});