大部分技能設定位於
~/.openclaw/openclaw.json 的 skills 底下。代理專屬的可見性位於
agents.defaults.skills 和 agents.list[].skills 底下。
{
skills: {
allowBundled: ["gemini", "peekaboo"],
load: {
extraDirs: ["~/Projects/agent-scripts/skills"],
allowSymlinkTargets: ["~/Projects/manager/skills"],
watch: true,
watchDebounceMs: 250,
},
install: {
preferBrew: true,
nodeManager: "npm",
allowUploadedArchives: false,
},
workshop: {
autonomous: { enabled: false },
allowSymlinkTargetWrites: false,
approvalPolicy: "pending",
maxPending: 50,
maxSkillBytes: 40000,
},
entries: {
"image-lab": {
enabled: true,
apiKey: { source: "env", provider: "default", id: "GEMINI_API_KEY" },
env: { GEMINI_API_KEY: "GEMINI_KEY_HERE" },
},
peekaboo: { enabled: true },
sag: { enabled: false },
},
},
}
若要使用內建影像生成，請使用 agents.defaults.imageGenerationModel
搭配核心 image_generate 工具，而不是 skills.entries。技能
項目僅適用於自訂或第三方技能工作流程。
載入 (skills.load)
要掃描的其他技能目錄，優先順序最低（低於內建和外掛技能）。
路徑會展開，並支援 ~。
skills.load.allowSymlinkTargets
受信任的實際目標目錄，允許符號連結的技能資料夾解析到其中，
即使該符號連結位於設定的根目錄之外。這適用於有意使用的同層
儲存庫配置，例如
<workspace>/skills/manager -> ~/Projects/manager/skills。請保持此清單
精準 — 不要指向像 ~ 或 ~/Projects 這類寬泛根目錄。
監看技能資料夾，並在 SKILL.md 檔案變更時重新整理技能快照。
涵蓋分組技能根目錄底下的巢狀檔案。
skills.load.watchDebounceMs
技能監看器事件的防抖時間窗，單位為毫秒。
安裝 (skills.install)
skills.install.preferBrew
當 brew 可用時，優先使用 Homebrew 安裝器。
skills.install.nodeManager
"npm" | "pnpm" | "yarn" | "bun"
預設值:"\"npm\""
技能安裝的節點套件管理器偏好。這只會影響技能
安裝 — 閘道執行階段仍應使用節點（WhatsApp/Telegram 不建議使用 Bun）。
openclaw setup --node-manager 和
openclaw onboard --node-manager 接受 npm、pnpm 或 bun；若要使用
Yarn 支援的技能安裝，請直接在設定中設為 "yarn"。
skills.install.allowUploadedArchives
允許受信任的 operator.admin 閘道用戶端安裝透過
skills.upload.* 暫存的私人 zip 封存。一般 ClawHub 安裝不需要
此設定。
操作者安裝政策 (security.installPolicy)
當操作者需要受信任的本機命令，依主機特定政策核准或封鎖技能與外掛
安裝時，請使用 security.installPolicy。此政策會在 OpenClaw 暫存來源
材料之後、安裝或更新繼續之前執行。它適用於 ClawHub 技能、上傳的
技能、Git/本機技能、技能相依安裝器，以及外掛安裝/更新來源。
{
security: {
installPolicy: {
enabled: true,
// Omit targets to cover every supported target.
targets: ["skill", "plugin"],
exec: {
source: "exec",
command: "/usr/local/bin/openclaw-install-policy",
args: ["--json"],
timeoutMs: 10000,
noOutputTimeoutMs: 10000,
maxOutputBytes: 1048576,
passEnv: ["OPENCLAW_STATE_DIR", "PATH"],
env: { POLICY_MODE: "strict" },
trustedDirs: ["/usr/local/bin"],
},
},
},
}
security.installPolicy.enabled
啟用操作者擁有的安裝政策。啟用但沒有有效的 exec
命令時，安裝會保守失敗。
security.installPolicy.targets
選用的目標篩選器。省略時，政策會套用到每個支援的
目標，讓新的安裝不會意外放行。
security.installPolicy.exec.command
受信任政策可執行檔的絕對路徑。OpenClaw 會在不透過
shell 的情況下執行它，並在使用前驗證路徑。
security.installPolicy.exec.args
在 command 之後傳入的靜態引數。
security.installPolicy.exec.timeoutMs
單一政策決策的最長實際執行時間。
security.installPolicy.exec.noOutputTimeoutMs
在政策保守失敗之前，沒有 stdout 或 stderr 輸出的最長時間。
security.installPolicy.exec.maxOutputBytes
政策程序可接受的 stdout 和 stderr 合併位元組數上限。
security.installPolicy.exec.env
提供給政策程序的字面環境變數。
security.installPolicy.exec.passEnv
從 OpenClaw 程序複製到政策程序的環境變數名稱。
只會傳遞具名變數。
security.installPolicy.exec.trustedDirs
可包含政策可執行檔的選用目錄允許清單。
security.installPolicy.exec.allowInsecurePath
略過命令路徑擁有權和權限檢查。只有在該路徑受到其他機制保護時才使用。
security.installPolicy.exec.allowSymlinkCommand
允許設定的命令路徑是符號連結。解析後的目標仍必須通過其他路徑檢查。
直譯器指令碼引數必須是直接的一般檔案，而不是符號連結。
protocolVersion: 1、
openclawVersion、targetType、targetName、sourcePath、sourcePathKind、
選用的結構化 source、結構化 origin，以及 request。它必須
在 stdout 寫出一個 JSON 物件：{ "protocolVersion": 1, "decision": "allow" }
或 { "protocolVersion": 1, "decision": "block", "reason": "..." }。非零
退出、逾時、JSON 格式錯誤、欄位缺失，或不支援的協定版本都會保守失敗。
OpenClaw 不會在一般閘道啟動期間執行安裝政策。當政策已啟用但不可用時，
安裝和更新會保守失敗。openclaw doctor 會執行靜態驗證；
openclaw doctor --deep 會針對設定的命令執行合成安裝探測。
批次更新會逐目標套用政策：遭封鎖的技能或外掛更新會讓該目標失敗，
但不會停用政策，也不會略過批次中後續的目標。
stdin 範例：
{
"protocolVersion": 1,
"openclawVersion": "2026.6.1",
"targetType": "skill",
"targetName": "weather",
"sourcePath": "/var/folders/.../openclaw-skill-clawhub/root",
"sourcePathKind": "directory",
"source": {
"kind": "clawhub",
"authority": "openclaw",
"mutable": false,
"network": true
},
"origin": {
"type": "clawhub",
"registry": "https://clawhub.openclaw.ai",
"slug": "weather",
"version": "1.0.0"
},
"request": {
"kind": "skill-install",
"mode": "install",
"requestedSpecifier": "clawhub:weather@1.0.0"
},
"skill": {
"installId": "clawhub"
}
}
#!/usr/bin/env node
let input = "";
process.stdin.setEncoding("utf8");
process.stdin.on("data", (chunk) => {
input += chunk;
});
process.stdin.on("end", () => {
const request = JSON.parse(input);
if (request.targetType === "plugin" && request.source?.kind === "local-path") {
process.stdout.write(
JSON.stringify({
protocolVersion: 1,
decision: "block",
reason: "local plugin paths are not approved on this host",
}),
);
return;
}
process.stdout.write(JSON.stringify({ protocolVersion: 1, decision: "allow" }));
});
內建技能允許清單
僅適用於內建技能的選用允許清單。設定後，只有清單中的內建
技能符合資格。受管理、代理層級和工作區技能不受影響。
個別技能項目 (skills.entries)
entries 底下的鍵預設會符合技能 name。如果技能定義了
metadata.openclaw.skillKey，請改用該鍵。請將含連字號的名稱加上引號
（JSON5 允許加引號的鍵）。
skills.entries.<key>.enabled
false 會停用該技能，即使它是內建或已安裝也一樣。
coding-agent 內建技能採用選擇加入 — 將它設為 true，並確認
claude、codex、opencode 或其他支援的命令列介面已安裝且已驗證。
skills.entries.<key>.apiKey
string | { source, provider, id }
供宣告 metadata.openclaw.primaryEnv 的技能使用的便利欄位。
支援明文字串或 SecretRef：{ source: "env", provider: "default", id: "VAR_NAME" }。
為代理執行注入的環境變數。只有在該變數尚未於程序中設定時才會注入。
skills.entries.<key>.config
用於自訂個別技能設定欄位的選用集合。
代理允許清單 (agents)
當你希望同一台機器/工作區使用相同的技能根目錄，但每個代理可見的
技能集不同時，請使用代理設定。
{
agents: {
defaults: {
skills: ["github", "weather"], // shared baseline
},
list: [
{ id: "writer" }, // inherits github, weather
{ id: "docs", skills: ["docs-search"] }, // replaces defaults entirely
{ id: "locked-down", skills: [] }, // no skills
],
},
}
由省略 agents.list[].skills 的代理繼承的共享基準允許清單。
完全省略可讓技能預設不受限制。
該代理的明確最終技能集。明確清單會取代繼承的預設值 —
不會合併。設為 [] 可讓該代理不公開任何技能。
代理技能允許清單是 OpenClaw 技能探索、提示、斜線命令探索、
沙盒同步和技能快照的可見性與載入篩選器。它們不是 shell 執行時的
授權邊界。如果代理可以執行主機 exec，該 shell 仍可執行外部用戶端
或讀取執行使用者可見的主機檔案，包括 MCP 用戶端登錄檔，例如
~/.openclaw/skills/config/mcporter.json。若要進行個別代理的 MCP 隔離，
請將技能允許清單與沙盒/作業系統使用者隔離結合，拒絕或嚴格允許清單化
主機 exec，並優先在 MCP 伺服器使用個別代理憑證。
工作坊 (skills.workshop)
skills.workshop.autonomous.enabled
當為 true 時，代理可以在成功輪次後，從持久的對話訊號建立待處理提案。使用者提示的技能建立一律會
經由技能工作坊，不受此設定影響。
skills.workshop.approvalPolicy
"pending" | "auto"
預設值:"\"pending\""
pending 要求操作員核准後，代理發起的套用、拒絕或隔離才可執行。
auto 允許這些動作無須核准。
skills.workshop.allowSymlinkTargetWrites
允許技能工作坊套用作業透過工作區技能符號連結寫入，其實際目標已受
skills.load.allowSymlinkTargets 信任。除非產生的提案套用作業應該變更該共用
技能根目錄，否則請保持停用。
skills.workshop.maxPending
每個工作區保留的待處理與隔離提案上限（允許範圍：1-200）。
skills.workshop.maxSkillBytes
提案本文大小上限（以位元組計，允許範圍：1024-200000）。提案
說明另有 160 位元組的硬性上限，因為它們會出現在探索與列表輸出中。
符號連結的技能根目錄
預設情況下，工作區、專案代理、額外目錄與內建技能根目錄都是
包含邊界。位於 <workspace>/skills 下且解析到根目錄外部的符號連結技能資料夾
會被略過，並記錄一則日誌訊息。
若要允許刻意設計的符號連結配置，請宣告受信任目標：
{
skills: {
load: {
extraDirs: ["~/Projects/manager/skills"],
allowSymlinkTargets: ["~/Projects/manager/skills"],
},
},
}
<workspace>/skills/manager -> ~/Projects/manager/skills
會在 realpath 解析後被接受。extraDirs 會直接掃描同層 repo；
allowSymlinkTargets 會為現有配置保留符號連結路徑。
技能工作坊套用作業預設不會透過這些符號連結寫入。若要讓
工作坊套用作業變更已受信任符號連結目標下的技能，請另外選擇加入：
{
skills: {
load: {
allowSymlinkTargets: ["~/Projects/manager/skills"],
},
workshop: {
allowSymlinkTargetWrites: true,
},
},
}
~/.openclaw/skills 與個人 ~/.agents/skills 目錄
已無條件接受技能目錄符號連結（每個技能的
SKILL.md 包含規則仍然適用）— allowSymlinkTargets 只需要用於
工作區、額外目錄與專案代理（<workspace>/.agents/skills）
根目錄。
沙箱化技能與環境變數
skills.entries.<skill>.env 與 apiKey 只適用於主機執行。
在沙箱內它們不會生效 — 依賴
GEMINI_API_KEY 的技能會因 apiKey not configured 而失敗，除非沙箱
另外取得該變數。
{
agents: {
defaults: {
sandbox: {
docker: {
env: { GEMINI_API_KEY: "your-key-here" },
},
},
},
},
}
擁有 Docker daemon 存取權的使用者可以透過 Docker 中繼資料檢查
sandbox.docker.env 值。當這種暴露不可接受時，請使用掛載的祕密檔案、自訂映像檔或
其他傳遞路徑。
載入順序提醒
workspace/skills （最高）
workspace/.agents/skills
~/.agents/skills
~/.openclaw/skills
內建技能
skills.load.extraDirs （最低）
技能參考
技能是什麼、載入順序、閘控與 SKILL.md 格式。
